d3.partition 分区布局完全指南：用 d3-hierarchy 构建 Icicle 与 Sunburst 邻接图

本文围绕 d3 仓库中的 Partition 布局文档（docs/d3-hierarchy/partition.md）展开，系统讲解 d3-hierarchy 提供的分区（partition）布局：它如何把层级结构转换成充满空间的邻接图（矩形 icicle 图或环形 sunburst 图）、x0 / y0 / x1 / y1 四个输出坐标的确切含义，以及 size、round、padding 三个配置项的默认值与用法。读完本文，你可以直接写出可运行的 icicle 图代码，并理解布局计算的前提条件（必须先 sum、建议先 sort）与坐标输出设计背后的工程考量。

什么是分区布局：邻接图的思想

分区布局（partition layout）生成的是邻接图（adjacency diagram）：一种"充满空间"（space-filling）的 node-link 树图变体。与 node-link 图在父子节点之间画连线不同，partition 布局把每个节点画成实心区域——矩形（即 "icicle" 冰柱图）或圆弧扇形（即 "sunburst" 日环图），节点之间的相对位置本身即表达了层级关系；而区域的大小则编码了一个量化维度（如收入、文件体积、占比）。这个维度在 node-link 图中很难直观呈现。

在 d3-hierarchy 模块总览中，partition 被归类为三类层级可视化技术之一：

• Node-link 图：用离散标记（节点 + 连线）表达拓扑，如 tree、cluster；
• 邻接图：通过节点相对位置表达拓扑，可同时用面积编码数量维度。"icicle" 图用矩形、"sunburst" 用环形扇区，两者都由 partition 布局产生；
• 包含图：通过包含关系表达拓扑，如 treemap、pack。

需要说明：partition 布局的实现源码位于 d3-hierarchy 包（对应版本为 ^3.1.2，见 package.json 的 dependencies 与 yarn.lock 中的解析结果）中的 src/partition.js。当前仓库是 d3 元包与官方文档仓库，src/index.js 只做 export * from "d3-hierarchy" 这样的再导出，因此仓库内不包含 partition.js 本体；本文对实现的描述以官方文档与 CHANGES.md 为准。

API 一览：方法与默认值

Partition 的完整 API 只有五个成员，全部见 api.md 中的索引。整理成表如下：

成员	作用	默认值
partition()	以默认设置创建一个新的 partition 布局	—
*partition*(*root*)	对给定 root hierarchy执行布局，向 root 及其所有后代写入坐标属性	—
*partition*.size(*size*)	设置布局尺寸为二元数组 [width, height]；不传参时返回当前尺寸	[1, 1]
*partition*.round(*round*)	按布尔值开启/关闭坐标取整；不传参时返回当前取整状态	false
*partition*.padding(*padding*)	设置节点相邻子节点之间的间距（数字）；不传参时返回当前 padding	0

所有方法都遵循 d3 一贯的 getter/setter 风格：传参则设置并返回布局本身（可链式调用），不传参则返回当前值。

partition(root) 的输出坐标

布局计算会在 root 及其每个后代节点上写入四个属性：

• node.x0 — 矩形左边缘
• node.y0 — 矩形顶边缘
• node.x1 — 矩形右边缘
• node.y1 — 矩形底边缘

文档同时给出两条硬性前提：

1. 必须先调用 node.sum（或 node.count）再传入布局。partition 依赖 node.value 决定每个节点占据的宽度，未求和的节点没有 value；
2. 建议先调用 node.sort 排好序再计算布局。排序发生在布局之前才会影响子节点的排布顺序。

这一点在 hierarchy.md 中有对应的推荐排序方式——对 icicle 图推荐"先按高度降序、再按聚合值降序"：

root
    .sum((d) => d.value)
    .sort((a, b) => b.height - a.height || b.value - a.value);

坐标输出为什么是 x0/x1 而不是 x0/dx

CHANGES.md 记录了这一设计的历史：v4.0.0 起，d3.treemap 与 d3.partition 两个空间填充布局改为输出 x0, x1, y0, y1 四个边缘坐标，替代旧版的 x0, dx, y0, dy 宽度/高度形式。原因是精度：相邻单元格的公共边缘在"起点 + 宽度"模式下可能因浮点运算出现微小偏差（例如 a.x0 + a.dx 与 b.x0 相差一个 ε），而直接存边缘坐标可以保证相邻单元格边缘严格相等。同一版本中还为 partition 新增了 round（取整）与 padding（间距）支持。

完整示例：构建一张 icicle 图

下面是一份可直接运行的完整流程：数据 → stratify → hierarchy → sum/sort → partition → 渲染 SVG 矩形。数据沿用 stratify.md 文档中的表格结构（name,parent 两列 CSV），因为多数真实业务数据（组织、目录、科目）都是这种扁平父子表而非嵌套 JSON。

<svg width="960" height="500"></svg>
<script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
<script>
const name = "Eve,Cain,Seth,Enos,Noam,Abel,Awan,Enoch,Azura";
const parent = ",Eve,Eve,Seth,Seth,Eve,Eve,Awan,Eve";
const value  = "0,3,7,4,3,1,5,2,2"; // 叶子节点带数值

// 1. 把扁平行转成层级（stratify）
const table = d3.csvParse(name + "\n" + parent + "\n" + value,
    (d) => ({name: d.name, parent: d.parent, value: +d.value}));

const root = d3.stratify()
    .id((d) => d.name)
    .parentId((d) => d.parent)
  (table);

// 2. 求和 + 排序（partition 的前置条件）
root.sum((d) => d.value)
    .sort((a, b) => b.height - a.height || b.value - a.value);

// 3. 布局：显式指定画布尺寸
const width = 960, height = 500;
d3.partition()
    .size([width, height])
    .padding(2)        // 相邻兄弟节点之间留 2px 缝隙
  (root);

// 4. 渲染：x0/y0/x1/y1 直接映射为 rect 属性
d3.select("svg")
  .selectAll("rect")
  .data(root.descendants())
  .join("rect")
    .attr("x", (d) => d.x0)
    .attr("y", (d) => d.y0)
    .attr("width", (d) => Math.max(0, d.x1 - d.x0))
    .attr("height", (d) => Math.max(0, d.y1 - d.y0))
    .attr("fill", (d) => d3.schemeCategory10[d.depth % 10]);
</script>

几个值得注意的细节：

• size 的默认值是 [1, 1]，即不设置时坐标落在 [0,1]×[0,1] 归一化区间内（这对配合 d3.scaleLinear 二次映射很方便，但直接画 SVG 必须显式设置画布尺寸）；
• padding(2) 让相邻兄弟节点之间留出 2 像素的视觉分隔，padding 越大缝隙越明显，但会等比压缩节点可用面积；
• 渲染时 d.x1 - d.x0 可能出现极小的负值（padding 作用于极小节点时），用 Math.max(0, ...) 兜底是常见做法；
• node.x0 等四个属性是布局原地写入节点对象的，布局函数本身不返回新的数据副本，所以 root.descendants() 里每个节点都自带坐标。

变体：sunburst 日环图

Icicle 与 sunburst 共用同一个布局，只是渲染几何不同：把 y0/y1 解释为半径、x0/x1 解释为角度（乘以 2π），再交给 d3-shape 的 arc 生成器即可：

// 布局不变：
d3.partition().size([2 * Math.PI, radius])
    .padding(0.5)
  (root.sum((d) => d.value));

// 渲染：角度取弧度，半径取 y0/y1
const arc = d3.arc()
    .innerRadius((d) => d.y0)
    .outerRadius((d) => d.y1)
    .startAngle((d) => d.x0)
    .endAngle((d) => d.x1);

svg.selectAll("path")
  .data(root.descendants())
  .join("path")
    .attr("d", arc)
    .attr("fill", (d) => d3.schemeCategory10[d.depth % 10]);

从源码结构看，arc 生成器以原点为中心、默认读取 innerRadius / outerRadius / startAngle / endAngle 字段（见 arc.md），因此只要把 partition 的坐标映射过去就能复用饼图/环图的圆角（cornerRadius）与角间隙（padAngle）能力；配合 d3.zoom 还可以实现点击某个扇区后放大下钻的经典交互。

使用与安装

partition 属于 d3 主包的一部分。通过包管理器安装（需要 Node >=12，见 package.json 的 engines 声明）：

npm install d3

安装后既可以按 ESM 方式从主包整体导入（src/index.js 会再导出 d3-hierarchy 的全部 API），也可以单独安装 d3-hierarchy（当前锁定版本为 3.1.2，见 yarn.lock）。在浏览器环境中，package.json 的 exports 字段声明了 umd 条件指向 dist/d3.min.js，即引入 UMD 构建后可直接使用全局 d3.partition。

在 d3 v7 中，d3.partition、partition.size、partition.round、partition.padding 的官方文档位置为 docs/d3-hierarchy/partition.md，API 索引位于 docs/api.md。

常见坑与参数速查

1. 忘记 sum 导致节点消失：未求和的节点 value 为 undefined，宽度为零，矩形不可见。布局前必须 root.sum((d) => d.value)（或 root.count()）。
2. value 必须非负：node.sum 要求 value 访问器返回非负数字。若只想按叶子计数，用 root.sum((d) => d.value ? 1 : 0) 或对内部节点返回 0。
3. size 忘了设，图形挤在左上角一像素：默认 [1, 1] 是归一化坐标，务必设置为目标画布的 [width, height]（sunburst 场景则为 [2 * Math.PI, radius]）。
4. round 的取舍：开启取整后坐标为整数、SVG 渲染更锐利，但大 padding 下可能出现相邻节点间出现 1px 错位；默认关闭。
5. 排序时机：node.sort 必须在布局调用之前完成，之后重排不会触发重排布——需要先 sort 再重新执行 partition(root)。
6. 与 treemap 的区别：treemap 是递归二分面积，每个父节点区域内独立排布子节点（支持多种切片算法与嵌套 padding）；partition 则是"每层占据一条水平带"，深度越深越靠下，因此 icicle 图能清晰展示每一层级的整体占比对比。

小结

Partition 布局是 d3-hierarchy 中 API 面最窄的布局之一——一个构造函数、一个可调用入口、三个配置方法——但它输出的 x0/y0/x1/y1 四个坐标足以驱动 icicle 与 sunburst 两种经典的面积编码层级图。使用它的关键链路只有三步：stratify/hierarchy 建树，sum + sort 准备数据，partition().size([...]).padding(n)(root) 计算坐标。理解了"边缘坐标代替宽度"这一 v4 起的设计、以及默认 size [1,1] 的归一化行为，就能避免绝大多数渲染问题。