分隔值 (Delimiter-Separated Values) API

D3.js - 分隔符分隔值 (DSV) API

分隔符分隔值（Delimiter-Separated Values, DSV）是一种常见的纯文本格式，用于存储表格数据（tabular data）。CSV（逗号分隔值）和 TSV（制表符分隔值）是众所周知的例子。D3 的 d3-dsv 模块提供了强大的工具，用于将 DSV 字符串解析成 JavaScript 对象或数组，以及将 JavaScript 对象/数组格式化回 DSV 字符串。

配置 DSV API

d3-dsv 模块包含在 D3.js 主捆绑包中。如果单独使用模块，可以安装 d3-dsv。

<!-- 选项 1：包含完整的 D3 库 -->
<script src="https://d3js.org/d3.v7.min.js"></script>

<!-- 选项 2：包含独立的 d3-dsv 模块 -->
<!-- <script src="https://d3js.org/d3-dsv.v3.min.js"></script> -->

<script>
  // 示例：解析 CSV 字符串
  // const csvString = "name,value\nAlice,10\nBob,20";
  // const parsedData = d3.csvParse(csvString, d3.autoType);
  // console.log(parsedData);
</script>

注意：d3-dsv 负责解析和格式化 字符串。要从 URL 获取 DSV 文件，通常需要使用 d3-fetch（例如，d3.csv(url)），它在获取文本内容后内部使用 d3-dsv 进行解析。

核心 DSV 解析方法

d3.csvParse(string[, rowConverter]) − 将给定的 string 解析为 CSV 数据。返回一个对象数组，每个对象代表一行。可选的 rowConverter 函数对每个行对象调用，允许你转换值（例如，将字符串转换为数字或日期）。d3.autoType 是一个常用的行转换器，用于自动类型推断。
d3.csvParseRows(string[, rowConverter]) − 将 string 解析为 CSV 数据，但返回一个数组的数组（字符串），表示行和列。这里的 rowConverter 处理每行的字符串数组。
d3.tsvParse(string[, rowConverter]) − 类似于 csvParse，但用于 TSV 数据（制表符分隔）。
d3.tsvParseRows(string[, rowConverter]) − 类似于 csvParseRows，但用于 TSV 数据。
d3.dsvFormat(delimiter) − 返回一个用于自定义 delimiter 的 DSV 解析器/格式化器对象。此对象具有 parse、parseRows、format、formatBody、formatRows、formatRow、formatValue 方法。

示例：解析 CSV 字符串

const csvString = `year,make,model,price
1997,Ford,E350,3000.00
2000,Mercury,Cougar,2500.50
2005,Toyota,Camry,8000.00`;

// 1. 基本解析（所有值均为字符串）
const rawData = d3.csvParse(csvString);
console.log("原始数据:", rawData);
// 输出：每个 price 都是一个字符串，例如 "3000.00"

// 2. 使用 d3.autoType 进行类型转换解析
const autoTypedData = d3.csvParse(csvString, d3.autoType);
console.log("自动类型推断数据:", autoTypedData);
// 输出：price 现在是一个数字，例如 3000

// 3. 使用自定义行转换器进行解析
const customParsedData = d3.csvParse(csvString, (d) => {
  return {
    year: new Date(+d.year, 0, 1), // 将 year 转换为 Date 对象
    make: d.make.toUpperCase(),    // 将 make 转换为大写
    model: d.model,
    price: parseFloat(d.price)     // 将 price 转换为浮点数
  };
});
console.log("自定义解析数据:", customParsedData);

核心 DSV 格式化方法

d3.csvFormat(rows[, columns]) − 将一个 rows 数组（对象）格式化为 CSV 字符串。可选的 columns 数组指定要包含哪些属性及其顺序。如果省略，则从第一行推断列。
d3.csvFormatBody(rows[, columns]) - 类似于 d3.csvFormat，但省略头部行。
d3.csvFormatRows(rowsArray) − 将一个 rowsArray 数组（其中每行是字符串数组）格式化为 CSV 字符串。
d3.tsvFormat(rows[, columns]) − 类似于 csvFormat，但用于 TSV。
d3.tsvFormatBody(rows[, columns]) - 类似于 d3.tsvFormat，但省略头部行。
d3.tsvFormatRows(rowsArray) − 类似于 csvFormatRows，但用于 TSV。

示例：将数据格式化为 CSV 字符串

const dataToFormat = [
  { name: "Alice", score: 95, city: "New York" },
  { name: "Bob", score: 88, city: "London" },
  { name: "Charlie", score: 92, city: "Paris" }
];

// 1. 使用推断的列进行格式化
const csvString1 = d3.csvFormat(dataToFormat);
console.log("格式化后的 CSV（推断列）：\n", csvString1);
// 输出：
// name,score,city
// Alice,95,New York
// Bob,88,London
// Charlie,92,Paris

// 2. 使用指定的列进行格式化
const csvString2 = d3.csvFormat(dataToFormat, ["name", "city", "score"]);
console.log("\n格式化后的 CSV（指定列）：\n", csvString2);
// 输出：
// name,city,score
// Alice,New York,95
// Bob,London,88
// Charlie,Paris,92

// 3. 格式化数组的数组（行）
const rowsArray = [
  ["fruit", "color"],
  ["apple", "red"],
  ["banana", "yellow"]
];
const csvString3 = d3.csvFormatRows(rowsArray);
console.log("\n从数组的数组格式化后的 CSV：\n", csvString3);
// 输出：
// fruit,color
// apple,red
// banana,yellow

实际应用

d3-dsv 模块对于以下场景至关重要：

数据导入: 解析用户粘贴或从本地文件读取的 CSV/TSV 数据（使用浏览器 File API 结合 d3-fetch 中的 d3.text 或 FileReader，然后使用 d3.csvParse）。
数据导出: 允许用户以 CSV 或 TSV 格式下载可视化中的数据。
互操作性: 处理使用 DSV 格式的电子表格或其他系统中的数据。
数据预处理: 在加载外部 DSV 文件时，通常与 d3-fetch 结合使用。

如需更高级的 DSV 操作或处理带有特殊引用或分隔符的文件，请查阅 d3-dsv 文档。