第 1 章 数据

关键代码 ① SVG 金字塔路径

Key Code ① SVG Pyramid Path

金字塔由 4 个 trapezoid 拼接而成 —— D3 path 的 d 属性。

The pyramid is composed of 4 trapezoids joined together — the d attribute of the D3 path.

⭐ // 关键点 ①：trapezoid 路径 —— 从上到下 4 个点的连线
const topW = 60, botW = 120;
const yTop = 20, yBot = 100;
const path = `
  M ${cx - topW/2} ${yTop}
  L ${cx + topW/2} ${yTop}
  L ${cx + botW/2} ${yBot}
  L ${cx - botW/2} ${yBot}
  Z
`;

关键点解释：SVG path 的 M(moveto)、L(lineto)、Z(close) 是 3 个最常用指令。 模板字符串 `${...}` 可以直接嵌入 JS 变量，比字符串拼接更可读。 实践：复杂形状用 D3 的 d3.symbol()（内置 ★●▲ 等），自己 path 容易出错。

Key-Point Explanation: The SVG path commands M (moveto), L (lineto), and Z (close) are the three most commonly used. Template literals `${...}` can embed JS variables directly, making them more readable than string concatenation. Practice: For complex shapes, use D3's d3.symbol() (which has built-in ★●▲ etc.); hand-writing paths is error-prone.

关键代码 ② 交互高亮（hover/click）

Key Code ② Interactive Highlighting (hover/click)

⭐ // 关键点 ②：选择集绑定事件 —— D3 的事件模型
const g = svg.append("g")
  .style("cursor", "pointer")
  .on("mouseover", function() {       // 注意 function 而非箭头函数
    d3.select(this).select("path")
       .transition().duration(150)
       .attr("fill", d3.color(layer.color).brighter(0.5));
  })
  .on("click", () => showDetail(layer));

关键点解释：必须用 function() 而非箭头函数—— 因为 D3 回调里要用 this 访问当前元素，箭头函数会捕获外层 this 导致失效。这是 D3 最常见的坑。 transition().duration() 是 D3 内置动画 API，比 jQuery 还简洁。

Key-Point Explanation: You must use function() instead of arrow functions — because D3 callbacks use this to access the current element, and arrow functions capture the outer this, causing it to fail. This is the most common D3 pitfall. transition().duration() is D3's built-in animation API, even more concise than jQuery.

鼠标悬停金字塔 → 高亮该层 · 点击 → 右侧显示该层定义 / 示例 / 常用可视化

Hover over the pyramid → highlight that tier · click → show that tier's definition / examples / common visualizations on the right

关键代码 ① 比例尺选型

Key Code ① Scale Selection

⭐ // 关键点 ①：scale 选型 —— 属性 ↔ 通道的映射
// 比率型数据 → scaleLinear（连续定量）
const x = d3.scaleLinear().domain([0, 100]).range([0, 800]);

// 名义/序数型数据 → scaleBand（离散分类）
const x = d3.scaleBand().domain(["软件1班", "软件2班"]).range([0, 800]);

关键点解释：D3 比例尺的 domain() 是数据域（输入），range() 是值域（输出像素）。 选错比例尺是初学者最常犯的错：类别数据用 scaleLinear 会算出没有意义的中间值（如 0.5 班）。 记忆口诀：连续定量用 Linear，离散分类用 Band，序数可用 Point。

Key-Point Explanation: A D3 scale's domain() is the data domain (input) and range() is the value range (output pixels). Choosing the wrong scale is the most common beginner mistake: using scaleLinear for categorical data produces meaningless intermediate values (e.g., class 0.5). Memory Aid: Use Linear for continuous quantitative, Band for discrete categorical, and Point for ordinal.

关键代码 ② colormap 选型

Key Code ② Colormap Selection

⭐ // 关键点 ②：颜色映射 —— 顺序型 vs 定性型 vs 发散型
// 顺序型（顺序有意义）→ interpolateViridis / interpolateBlues
const color = d3.scaleSequential(d3.interpolateViridis);

// 定性型（无顺序）→ schemeTableau10
const color = d3.scaleOrdinal().range(d3.schemeTableau10);

// 发散型（有中点）→ interpolateRdBu
const color = d3.scaleDiverging(d3.interpolateRdBu);

关键点解释：Viridis 是顺序 colormap 的标杆，色觉缺陷（CVD）友好且感知均匀。 常见错误：用彩虹色 interpolateRainbow 编码数值数据 —— 既不 CVD 友好，又有假边界（蓝色→绿色跳跃）。 课堂提问：什么时候用发散型？答：有"中间值"的数据（如正负、温度 vs 平均值）。

Key-Point Explanation: Viridis is the benchmark sequential colormap — color-vision-deficiency (CVD) friendly and perceptually uniform. Common Mistake: Using the rainbow colormap interpolateRainbow to encode numerical data — it is neither CVD-friendly nor free of false boundaries (blue→green jumps). Class Question: When to use a diverging colormap? Answer: Data that has a 'middle value' (e.g., positive/negative, temperature vs. average).

4 个 sub-demo：① 类别用色相（✓）② 序数用亮度（✓）③ 数值用位置（✓）④ ❌ 数值用色相（错配，看不出大小关系）

4 sub-demos: ① Categorical uses hue (✓) ② Ordinal uses brightness (✓) ③ Numerical uses position (✓) ④ ❌ Numerical uses hue (mismatch — cannot tell magnitude)

关键代码 ① map / reduce 的链式组合

Key Code ① Chained Composition of map / reduce

⭐ // 关键点 ①：函数式数据流 —— map 后接 filter 再 reduce
const avgAge =
  students
    .filter(s => s.gender === "男")    // ① 过滤男生
    .map(s => s.age)                    // ② 提取年龄
    .reduce((sum, a) => sum + a, 0) // ③ 合计
  / students.filter(s => s.gender === "男").length; // ④ 求平均

关键点解释：链式调用的每一步返回新数组，不会修改原数组。 与命令式对比：命令式需要 4 个临时变量 + 一个 for 循环，函数式一行搞定。 性能权衡：每次 map/filter 都会创建新数组，对超大数组有性能损耗（百万级以上才显著）。

Key-Point Explanation: Each step of the chained call returns a new array and does not modify the original array. Compared with Imperative: The imperative style needs 4 temporary variables + a for loop, while the functional style does it in one line. Performance Trade-off: Each map/filter creates a new array, which incurs a performance cost for very large arrays (only significant above the million level).

关键代码 ② cross（笛卡尔积）

Key Code ② cross (Cartesian Product)

⭐ // 关键点 ②：cross —— 笛卡尔积，用于两两组合
const genders = ["男", "女"];
const majors  = ["软件工程", "数据科学"];
const combos  = d3.cross(genders, majors);
// → [["男","软件工程"], ["男","数据科学"], ["女","软件工程"], ["女","数据科学"]]

关键点解释：笛卡尔积常用在"两两组合"分析（如性别 × 专业的人数统计）。 第二参 reducer 可选，用来"合并"两个元素。 扩展：3 个数组的笛卡尔积是 8 种，n 个数组的笛卡尔积是乘积大小。

Key-Point Explanation: The Cartesian product is commonly used in 'pairwise combination' analysis (e.g., counting students by gender × major). The second reducer argument is optional and is used to 'combine' the two elements. Extension: The Cartesian product of 3 arrays yields 8 combinations; for n arrays it is the product of their sizes.

关键代码 ③ group / rollup（聚合）

Key Code ③ group / rollup (Aggregation)

⭐ // 关键点 ③：group 与 rollup —— 层次聚合
// group 返回 Map（保留所有元素）
const byClass = d3.group(students, s => s.class);
// rollup 返回 Map（每个 key 只保留聚合值）
const countByClass = d3.rollup(
  students,
  v => v.length,
  s => s.class
);

关键点解释：group vs rollup 是"分组保留"vs"分组聚合"的区别。 rollup 第二参是 reducer 函数（这里取长度），后续章节 doc-02 会详细用 rollup 做树形数据。

Key-Point Explanation: group vs rollup is the difference between 'keep groups' and 'aggregate groups'. The second argument of rollup is a reducer function (here it takes the length); in later chapter doc-02, rollup will be used in detail for tree-structured data.

下拉切换 8 个函数，右侧显示输入/输出对照 + 真实场景（新生数据）

Use the dropdown to switch among the 8 functions; the right side shows input/output comparison + a real scenario (new-student data)

关键代码 ① .join(enter, update, exit) 三态

Key Code ① .join(enter, update, exit) Three States

⭐ // 关键点 ①：D3 v5+ 的 join() API —— 优雅处理三态
const circles = svg.selectAll("circle")
  .data(currentData)
  .join(
    enter  => enter.append("circle").attr("fill", "green"),  // enter
    update => update.attr("fill", "cyan"),                              // update
    exit   => exit.remove()                                                   // exit
  );

关键点解释：join 的三个回调分别在 enter / update / exit 阶段被调用。 这种"声明式三态"比 v3 的 enter().append() + exit().remove() 写法更简洁，逻辑更不易出错。 类比：React 的 diff + patch —— 同样思想，但 React 帮你做了，D3 让你自己写变换函数。

Key-Point Explanation: The three callbacks of join are invoked in the enter / update / exit phases respectively. This 'declarative three-state' pattern is more concise than the v3 enter().append() + exit().remove() style, and less error-prone. Analogy: React's diff + patch — the same idea, but React does it for you, while D3 lets you write the transformation functions yourself.

关键代码 ② key 函数保身份

Key Code ② key Function Preserves Identity

⭐ // 关键点 ②：key 函数 —— 元素身份的稳定器
// ❌ 不带 key：数据顺序变化 → 所有元素都"update"，过渡动画错乱
svg.selectAll("circle").data(newData);

// ✅ 带 key：用唯一字段绑定身份，元素"知道自己是哪个"
svg.selectAll("circle").data(newData, d => d.id);

// 同样的逻辑用 React 描述：key={item.id}

关键点解释：key 函数是 D3 动画的灵魂。 没有 key 时，D3 按 index 绑定身份：数据重排会导致"所有元素都换位置"。 带 key 后，每个 circle 知道自己的 id 是什么，重排时只是 cx 变化，过渡动画自然。 类比：与 React 的 key={item.id} 完全相同的思想。

Key-Point Explanation: The key function is the soul of D3 animation. Without a key, D3 binds identity by index: reordering data causes 'all elements to move'. With a key, each circle knows its id, and on reorder only cx changes, so the transition animation is natural. Analogy: Exactly the same idea as React's key={item.id}.

关键代码 ③ d3.select vs d3.selectAll

Key Code ③ d3.select vs d3.selectAll

⭐ // 关键点 ③：选择器的核心区别
// select：返回 1 个元素（第一个匹配）；数据绑定只对这一个元素
const title = d3.select("#title");

// selectAll：返回多个元素；数据绑定按顺序一一对应
const bars = d3.selectAll(".bar").data(values);

关键点解释：select 用于"操作单个元素"，selectAll 用于"批量绑定数据"。 常见错误：用 selectAll(".bar") 给一个数组绑定数据时，元素数量与数据数量必须匹配，否则会"留空"或"溢出"。 最佳实践：先用 selectAll 创建占位元素（可能为空），再 .data().join(...)。

Key-Point Explanation: select is used to 'operate on a single element', and selectAll is used to 'bind data in bulk'. Common Mistake: When using selectAll(".bar") to bind data to an array, the number of elements must match the number of data items, otherwise it will 'leave gaps' or 'overflow'. Best Practice: First use selectAll to create placeholder elements (possibly empty), then .data().join(...).

点击按钮触发 enter (绿) / update (蓝) / exit (红)，观察三态切换

Click the button to trigger enter (green) / update (blue) / exit (red), and observe the three-state switching