d3-chord 弦图布局深度解析chord() 的角度计算、排序与有向变体【免费下载链接】d3Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:项目地址: https://gitcode.com/GitHub_Trending/d3/d3弦图Chord Diagram用环形布局加丝带ribbon可视化一组节点之间的成交流量例如状态转移概率、资金流向或人口迁移。本文以 d3 仓库中的 docs/d3-chord/chord.md 为主体系统讲解d3.chord()布局的矩阵输入约定、chord/group 输出结构、三个排序器与 padAngle 参数、chordDirected()与chordTranspose()两个变体并结合 docs/components/ExampleChord.vue 中的官方完整示例给出从矩阵到 SVG 渲染的可复制实现。1. 弦图与流量矩阵chord() 的输入约定docs/d3-chord.md 开篇定义了弦图的数据模型D3 的弦图布局使用n×n 的方阵 matrix表示 n 个节点之间的流量其中matrix[i][j]表示从节点i流向节点j的数值。两个关键约束每个matrix[i][j]必须非负没有流量时可以取 0对角线matrix[i][i]表示节点保留在自身自环流量。官方文档使用的示例是一个来自 Circos 的假数据集——不同发色之间染发的迁移人数const matrix [ // to black, blond, brown, red [11975, 5871, 8916, 2868], // from black [ 1951, 10048, 2060, 6171], // from blond [ 8010, 16145, 8090, 8045], // from brown [ 1013, 990, 940, 6907] // from red ];矩阵的每一行和每一列对应一种发色每个值代表从一种颜色染成另一种颜色的人数。例如 5,871 人从黑色染成金色而 1,951 人从金色染回黑色矩阵对角线表示保持原色不变的人数。布局的工作流程是把每个人群按起始颜色沿圆周排布成一个个扇形区块group然后在区块之间绘制丝带丝带的起点/终点宽度分别与其 source/target 流量成正比。这正是 chord.md 中 “computes angles to generate a chord diagram” 的含义——chord() 本质上是一个角度分配器它把矩阵中的数值换算成沿圆周的 startAngle/endAngle。2. chord() 与chord(matrix)输出结构详解2.1 构造与调用const chord d3.chord(); const chords chord(matrix);chord()按默认设置构造一个新布局调用chord(matrix)时输入必须是对应 n 个节点有向完全图complete digraph流量的 n×n 方阵。2.2 chords 数组双向流量的合并返回值是一个chord 对象数组每个 chord 表示节点i与j之间i可以等于j的双向合并流量{ source: { startAngle, endAngle, value, index }, target: { startAngle, endAngle, value, index } }source 与 target 都是 subgroup属性如下属性含义startAngle起始角弧度endAngle结束角弧度value流量值matrix[i][j]index节点下标i文档明确了两条去重规则这是理解输出数组的关键零流量不生成 chord只有matrix[i][j]或matrix[j][i]非零的配对才会出现在结果里每个配对只保留一个 chordchordij同时代表i→j和j→i两个方向的流量不会重复出现ji且 source 一侧总是取matrix[i][j]与matrix[j][i]中较大的那个target 一侧是较小方向。chords 数组随后通常交给 ribbon 生成器用丝带绘制出网络关系。2.3 chords.groups每个节点的总流出返回的 chords 数组附带一个长度为 n 的次级数组chords.groups每个 group 对应节点i的合并流出即matrix[i][0 … n-1]整行之和同样是对象属性含义startAngle起始角弧度endAngle结束角弧度value节点i的总流出流量index节点下标igroups 通常传给 d3-shape 的 arc 生成器在圆周上生成一圈甜甜圈式的环形扇区donut。也就是说一幅完整的弦图 arc 画 groups ribbon 画 chords这也是官方示例的做法见 ExampleChord.vue 中d3.arc()配d3.ribbon()的组合。3. 参数与排序器padAngle、sortGroups、sortSubgroups、sortChordsd3.chord提供四个配置方法均为标准的“设置/读取”双重签名3.1chord.padAngle(angle)const chord d3.chord().padAngle(0.05);指定相邻 group 之间的间隙角弧度返回该布局本身可链式调用。不传参则返回当前值默认是 0即各 group 首尾相接、不留缝隙。间隙角让环形扇区彼此分离视觉上更容易区分节点。3.2chord.sortGroups(compare)设置或读取group 排序比较器默认null即保持矩阵中的原始顺序。比较器非 null 时它按各节点的**总流出量total outflow**对 group 排序决定各扇区在圆周上的先后位置。3.3chord.sortSubgroups(compare)设置或读取subgroup 排序比较器默认null。非 null 时对给定 groupi按其总流出量对matrix[i][0 … n-1]对应的 subgroups 排序决定同一个扇区内部各段丝带切片的排布顺序。3.4chord.sortChords(compare)设置或读取chord 排序比较器默认null。非 null 时按合并流量combined flow对 chords 排序注意文档特别强调它只影响丝带的 z-order叠放顺序不改变任何角度。比如按降序排大流量的丝带会画在上层小流量的丝带被大丝带覆盖可读性更好。三个排序器都可复用 d3-array 的 sort 模块中的d3.ascending/d3.descending比较函数官方示例正是如此。4. 变体chordDirected() 与 chordTranspose()4.1 chordDirected()const chords d3.chordDirected()(matrix);用于单向流量的弦图布局i到j的 chord 只由matrix[i][j]一个值生成不做双向合并。它适合真正的有向数据例如时间序列上的单向迁移通常配合 ribbonArrow() 箭头丝带使用。4.2 chordTranspose()const chords d3.chordTranspose()(matrix);转置布局实用用途是突出**流出outgoing**而非流入的流量方向。这两个布局是 d3-chord 3.x 引入的新能力仓库 CHANGES.md 中记录了 d3 7.0 时新增d3.chordDirected、d3.chordTranspose、d3.ribbonArrow、ribbon.padAngle、ribbon.sourceRadius、ribbon.targetRadius等 API 的历史。5. 完整实战从矩阵到可渲染的弦图下面整合 docs/components/ExampleChord.vue 的核心逻辑展示文档中所有概念如何落地为一个 688×688 的 SVG 弦图。5.1 布局与几何参数import * as d3 from d3; const width 688, height 688; const outerRadius Math.min(width, height) * 0.5 - 30; // 外半径留 30px 边距 const innerRadius outerRadius - 20; // 内半径20px 的环带5.2 三个生成器的配置// groups 环形扇区内径 0 则为饼图这里做成甜甜圈 const arc d3.arc() .innerRadius(innerRadius) .outerRadius(outerRadius); // 丝带固定半径后chord 数据里不必再携带 radius 字段 const ribbon d3.ribbon() .radius(innerRadius); // 布局组间留 0.05 弧度间隙组内按流出量降序排切片 const chords d3.chord() .padAngle(0.05) .sortSubgroups(d3.descending) (matrix);注意ribbon.radius(240)这类固定半径的用法设置后调用ribbon(d)时数据只需提供startAngle/endAngle见 ribbon.md 中radius的说明chord()输出的 subgroup 恰好就是这种结构天然匹配。5.3 渲染groups 用 arcchords 用 ribbonsvg :viewBox-344 -344 688 688 !-- 1) 圆周环带每个 group 一个环形扇区 -- g v-ford in chords.groups path :darc(d) :fillcolors[d.index] :strokecolors[d.index] title{{ d.value.toLocaleString(en-US) }} {{ names[d.index] }}/title /path /g !-- 2) 丝带每个 chord 一条半透明路径 -- g fill-opacity0.67 strokevar(--vp-c-bg) path v-ford in chords :dribbon(d) :fillcolors[d.target.index] title {{ d.source.value.toLocaleString(en-US) }} {{ names[d.source.index] }} → {{ names[d.target.index] }} /title /path /g /svg几个官方示例中的细节值得留意配色约定丝带填充色取colors[d.target.index]即 d3-chord.md 所述“任意地取两个值中较大方向对应的颜色”由于 chord 的 source 恒为较大方向等价于按 source 取色时以 target 为键hover 提示通过title展示双向流量例如5,871 black → blond若 source 与 target 不同还附上反向数值1,951 blond → black与文档“chord 合并双向流量”的语义一一对应组刻度group ticks示例额外计算了每组内的小刻度线核心是把 group 的角度范围按值线性插值——(d.endAngle - d.startAngle) / d.value得到每单位流量的角度增量再用d3.range(0, d.value, step)生成刻度值并映射到角度。刻度间隔借助 d3-array 的 ticks 工具d3.tickStep(0, sum, 100)取得标签用d3.formatPrefix做数量级缩写。这是“angles 即比例”这一弦图核心性质的直接运用。5.4 与 d3 包的依赖关系本仓库是 d3 v7.9.0 的聚合包package.json 声明了对d3-chord: ^3.0.1的依赖src/index.js 通过export * from d3-chord将d3.chord、d3.ribbon等 API 平铺到顶层命名空间因此import * as d3 from d3后即可直接调用。6. 小结d3.chord的布局 API 围绕“矩阵 → 角度”这一单一职责展开chord(matrix)输出去重后的双向 chords 与按总流出的 groupspadAngle控制 group 间隙sortGroups/sortSubgroups分别控制扇区顺序与扇区内切片顺序sortChords只影响丝带叠放层次chordDirected与chordTranspose则覆盖单向与转置两类非对称场景。配合 ribbon 与 arc即可从一份 n×n 流量矩阵直接得到完整、可交互的弦图。【免费下载链接】d3Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:项目地址: https://gitcode.com/GitHub_Trending/d3/d3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考