扇形/弧线生成器 Arcs 用以生成一个个扇形或环形，然后将多个扇形或环形拼起来就构成了饼图或圆环图。

使用方法 d3.arc() 创建一个扇形生成器（以下称为 arc）

它既是一个方法，可以直接调用，传递一个包含多个设置参数的对象作为入参（实际这些参数在内部被相应的方法调用），来创建一个扇形；它也是一个对象，具有多种方法设置不同的参数，一般通过链式调用的方式来使用。

// 创建一个默认的扇形生成器
const arc = d3.arc();

// 在调用生成器时需要传递相关的设置参数（半径和角度）
// 适用于动态生成各种形状的扇形
arc({
  innerRadius: 0,
  outerRadius: 100,
  startAngle: 0,
  endAngle: Math.PI / 2
}); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

// 创建一个扇形生成器，并设置了相应的参数
const arc = d3.arc()
    .innerRadius(0)
    .outerRadius(100)
    .startAngle(0)
    .endAngle(Math.PI / 2);

// 当扇形生成器已经设置了半径和角度，可以直接调用，生成路径
arc(); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

// 包含一系列扇形角度（开始和结束的角度，单位是弧度）的数组
const angleArr = [
    {
        start: 0 * 2 * Math.PI,
        end: 1/4 * 2 * Math.PI
    },
    {
        // ...
    },
    // ...
]

// 创建一个预设了半径的扇形生成器，开始角度和结束角度以参数的形式传入
arc = d3.arc()
    .innerRadius(210)
    .outerRadius(310)
    .startAngle(([startAngle, endAngle]) => startAngle)
    .endAngle(([startAngle, endAngle]) => endAngle)

const pathArr = []
angleArr.forEach(angle => {
    pathArr.push(arc([angleArr.start, angleArr.end]))
})

扇形生成器具有的方法，这些方法一般都返回扇形生成器本身，便于进行链式调用：

• arc.centroid() 计算扇形的「中点」，即位于弧度是 $(startAngle + endAngle) / 2$ 半径是 $(innerRadius + outerRadius) / 2$ 的点，一般将扇形的文本注释添加到此 ⚠️ 该点可能不在扇形/环形内部
• arc.innerRadius([radius]) 设置内半径，入参可以是一个数值，或是返回数值的函数；如果没有入参，则返回当前的内半径。如果 radius=0 则生成扇形，如果 radius 不为零则生成环形
• arc.outerRadius([radius]) 设置外半径
  提示

  如果内半径大于外半径，则 D3 会将两者调换；如果入参是负值则会被当作 $0$

• arc.cornerRadius([radius]) 设置圆角的半径，对于扇形则设置外侧的两个角；对于环形则设置内外侧的四个角
  注意

  但是圆角的半径不会大于 $(outerRadius - innerRadius)/2$

  而且当两个相邻的圆角靠得太近时，圆角半径会减小，这种情况一般出现在环形的弧长小于 $\pi$ 的内侧圆角

  
  

  

• arc.startAngle([angle]) 设置扇形的一边的起始角度，作为起始角，单位是弧度。其中在 12 点方向（即 SVG 坐标系统的 -y 方向）为 $0$。如果入参的是负值表示起始角度在逆时针方向上。
• arc.endAngle([angle]) 设置扇形的另一边的起始角度，作为结束角。
  提示

  如果 $|endAngle - startAngle| \ge 2\pi$ 则生成一个完整的圆或圆环

• arc.padAngle([angle]) 设置扇形的间隔角度
• arc.padRadius([radius]) 设置扇形的间隔半径
  提示

  间隔角度结合间隔半径算出间隔弧长 $padAngle \times padRadius$ 对于环形的内外侧都会减去相同的间隔弧长，这样就会得到如下方右侧图的效果（两个环形的相邻的边是平行的）；对于扇形或内半径较小的环形和开角较小的环形，只会在外侧减去间隔弧长，这样就得到如下方左侧图的效果（扇形或环形的内侧相连到一点）。但是如果扇形或环形的开角 $|endAngle - startAngle| \ge 2\pi$（生成一个完整的圆或圆环）则会忽略间隔弧长

  

• arc.context(canvasContext) 用于设置绘图上下文 context
  在使用扇形生成器时，如果设置了绘图上下文 context，就会生成一系列在画布绘制线条的命令/方法；如果没有设置绘图上下文 context，则生成可用于作为 <path> 元素的属性 d 的属性值的字符串

const data = [1, 1, 2, 3, 5, 8, 13, 21];
const pie = d3.pie();
const pieArcData = pie(data)

// 结果
// [
//  {"data":  1, "value":  1, "index": 6, "startAngle": 6.050474740247008, "endAngle": 6.166830023713296, "padAngle": 0},
//  {"data":  1, "value":  1, "index": 7, "startAngle": 6.166830023713296, "endAngle": 6.283185307179584, "padAngle": 0},
//  {"data":  2, "value":  2, "index": 5, "startAngle": 5.817764173314431, "endAngle": 6.050474740247008, "padAngle": 0},
//  {"data":  3, "value":  3, "index": 4, "startAngle": 5.468698322915565, "endAngle": 5.817764173314431, "padAngle": 0},
//  {"data":  5, "value":  5, "index": 3, "startAngle": 4.886921905584122, "endAngle": 5.468698322915565, "padAngle": 0},
//  {"data":  8, "value":  8, "index": 2, "startAngle": 3.956079637853813, "endAngle": 4.886921905584122, "padAngle": 0},
//  {"data": 13, "value": 13, "index": 1, "startAngle": 2.443460952792061, "endAngle": 3.956079637853813, "padAngle": 0},
//  {"data": 21, "value": 21, "index": 0, "startAngle": 0.000000000000000, "endAngle": 2.443460952792061, "padAngle": 0}
// ]

pieArcData.forEach((d) => {
  arc(d); // arc 是扇形生成器
})

线段生成器 Lines 基于给定的坐标点生成线段（或曲线），常用于构成一些可视化图形，如折线图 line chart 或分层的边缘捆绑图 hierarchical edge bundling。

使用方法 d3.line([xFunc], [yFunc]) 创建一个线段生成器（以下称为 line）

它既是一个方法，可以直接调用，传递需要可视化的数据（一个数组）作为入参（实际这些参数在内部被相应的方法调用，例如在创建线段生成器时，传递横坐标和纵坐标的读取函数 xFunc 和 yFunc 作为入参，然后数组每一个元素都会调用这两个函数，来获取相应的坐标值），来创建线段。

// 创建一个默认的线段生成器
const line = d3.line();

line([[10, 60], [40, 90]]); // "M10,60L40,90"

// 创建一个线段生成器，并设置了相应的参数
const line = d3.line(
    (d)=> d.xValue,
    (d)=> d.yValue
);

const lineData = line([
  {
    xValue: 10,
    yValue: 60
  },
  {
    xValue: 40,
    yValue: 90
  },
]); // "M10,60L40,90"

它也是一个对象，具有多种方法设置不同的参数，一般通过链式调用的方式来使用。例如使用默认参数创建一个线段生成器 const line = d3.line()，然后在之后再调用相应的方法进行设置：

• line.x(xFunc) 设置横坐标读取函数，该函数会在调用线段生成器时，为数组中的每一个元素都执行一次，以返回该数据所对应的横坐标。
  该函数有三个入参（线段生成器的其他方法的入参函数一般都是有这三个入参）：当前的元素 d，该元素在数组中的索引 i，整个数组 data。通过这些入参数据，一般利用比例尺进行映射，返回相应的横坐标的值。
  D3 默认在使用线段生成器时，传递进来的数组的格式如 [[10, 60], [40, 90]]，即每个元素都是由两个数值构成的数组，因此它的默认横坐标读取函数如下
  js

  function x(d) {
    return d[0];
  }
  

  提示

  如果数组中的元素并不是上述的默认结构，而是其他更复杂的结构，或者数据并不是坐标值，都需要配置 line.x(xFunc) 横坐标读取函数

• line.y(xFunc) 设置纵坐标读取函数，设置方式和横坐标读取函数一样。
• line.defined(definedState) 设置数据完整性检验函数，该函数会在调用线段生成器时，为数组中的每一个元素都执行一次，返回布尔值（默认值恒为 true），以判断该元素的数据是否完整。
  该函数也是有三个入参（当前的元素 d，该元素在数组中的索引 i，整个数组 data），当函数返回 true 时，线段线段生成器就会执行下一步（调用坐标读取函数），最后生成该元素相应的坐标数据；当函数返回 false 时，该元素就会就会跳过，当前线段就会截止，并在下一个有定义的元素再开始绘制，反映在图上就是一段段分离的线段。
  提示

  如果一个点的两侧的元素（点）完整性欠缺，导致产生「孤立」的点，一般这些点在页面上不会显示出来，除非元素 <path> 的属性 stroke-linecap 路径两端的形状设置为 round 或 square（默认值是 butt）

• line.curve(curveInterpolator) 设置两点之间的曲线插值器
  所以线段生成器除了可以绘制折线，还可以绘制曲线
  D3 提供了一系列的内置的曲线插值器，也支持自定义曲线插值生成器
  提示

  除了使用曲线插值器，还可以从原始数据入手，通过方法 d3.blur(data, radius) 对数据进行处理 ❓，得到变化更平稳的数据集，也可以让绘制的折线更平滑

  具体示例可以参考官方的这个 Observable Notebook

• line.context(canvasContext) 用于设置渲染/绘图上下文 context（针对 Canvas 画布而言）。在使用线段生成器时，如果设置了绘图上下文 context，就会生成一系列在画布绘制线条的命令/方法；如果没有设置绘图上下文 context，则生成可用于作为 <path> 元素的属性 d 的属性值的字符串
  线段生成器的 context 的默认值为 null 即未设置绘图上下文
  js

  // 在画布中绘制线段的流程
  line.context(canvasContext);
  context.beginPath(); // 开始绘制
  line(data); // 使用线段生成器生成一系列的具体绘制命令，并执行
  // 设置线段的样式
  context.fill();
  context.stroke();
  
  // 在 SVG 中绘制线段的流程
  d3.select(target)
    .append("path")
    .attr("d", line(data))
    .attr("stroke", "black")
  

• line.digits(number) 用于设置数据的精度，即路径 <path> 的属性 d 的值中描述画笔操作的数据的精度，参数 number 用于设置小数点后的最大位数（默认值为 3）
  这个配置只在关上下文联 context 为 null 时才会生效，因为这时候线段生成器返回的结果才是字符串（被用作元素 <path> 的属性 d 的属性值）

面积生成器 Areas 和线段生成器类似，也是基于给定的坐标点生成线段（或曲线），不同的是它生成两条边界线：

• 上边界线 topline y1
• 下边界线 baseline y0 一般下边界线采用横坐标轴，即设置为常量 y0=0

一般对于两条线段的横坐标相同 x0=x1 时，所对应的点的纵坐标 y0 和 y1 不同，这样两条边界线之间区域就是目标面积

使用方法 d3.area([xFunc], [y0Func], [y1Func]) 创建一个面积生成器（以下称为 area）

它既是一个方法，可以直接调用，传递需要可视化的数据（一个数组）作为入参

它也是一个对象，具有多种方法设置不同的参数，一般通过链式调用的方式来使用：

• area.x(xFunc) 和 area.x0(xFunc) 一样，用于设置下边界线横坐标读取函数。该方法会将 x0 读取函数设置为传入的参数 xFunc，并将 y1 读取函数设置为 null
• area.x0(xFunc) 设置下边界线横坐标读取函数，该函数会在调用面积生成器时，为数组中的每一个元素都执行一次，以返回该数据所对应的横坐标。
  该函数也是有三个入参（面积生成器的其他方法的入参函数一般都是有这三个入参）：当前的元素 d，该元素在数组中的索引 i，整个数组 data。通过这些入参数据，一般利用比例尺进行映射，返回相应的横坐标的值。
  提示

  D3 默认在使用面积生成器时，传递进来的数组的格式如 [[10, 60], [40, 90]]，即每个元素都是由两个数值构成的数组，因此它的默认横坐标读取函数如下

  js

  function x(d) {
  return d[0];
  }
  

  如果数组中的元素并不是上述的默认结构，而是其他更复杂的结构，或者数据并不是坐标值，都需要配置横坐标读取函数

  
  该方法所传入的参数也可以是一个常数，对于纵向延伸的面积图，其左边界可能是一条平行于纵轴的线，所以 x0 值可以是一个常数
• area.x1(xFunc) 设置上边界线横坐标读取函数。默认复用相应的 x0 值作为 x1 的值，一般都不需要进行配置。
  该方法所传入的参数也可以是一个常数，对于纵向延伸的面积图，其右边界可能是一条平行于纵轴的线，所以 x1 值可以是一个常数
• area.y(yFunc) 和 area.y0(yFunc) 一样，用于设置下边界线纵坐标读取函数。该方法会将 y0 读取函数设置为传入的参数 yFunc，并将 y1 读取函数设置为 null
• area.y0(yFunc) 设置下边界线纵坐标读取函数（或一个常数，对于横向延伸的面积图，其下边界可能是一条平行于横轴的线，所以 y0 值可以是一个常数）
  它的默认值是 0，即默认以 svg 容器的顶部作为面积图的下边界线
  js

  function y() {
    return 0;
  }
  

  以横轴作为下边界线

  对于横向延伸的面积图，其下边界线一般是横坐标轴，而且横坐标轴所对应的 y 值为零点，则可以通过如下代码来设置下边界线

  js

  const area = d3.area().y0(y(0));
  

  其中 0 是横坐标轴所对应的 y 值（如果横坐标轴所对应的 y 值不是零点，则传递相应 y 值），再通过纵坐标轴比例尺 y 进行映射 y(0) 就得到横坐标轴在 svg 中的坐标位置

  
  如果下边界线也是折线，需要通过该方法配置下边界线纵坐标读取函数
• area.y1(yFunc) 设置上边界线纵坐标读取函数（或一个常数，对于横向延伸的面积图，其上边界可能是一条平行于横轴的线，所以 y1 值可以是一个常数）
  D3 默认在使用面积生成器时，传递进来的数组的格式如 [[10, 60], [40, 90]]，即每个元素都是由两个数值构成的数组，下边界线纵坐标读取函数的默认纵坐标读取函数如下
  js

  function y(d) {
    return d[1];
  }
  

• area.defined(definedState) 设置数据完整性检验函数，其作用和线段生成器的相应方法一样，如果存在不完整的数据，也是会生成分离的多块面积。
• area.curve(curveInterpolator) 设置两点之间的曲线插值器
• area.context(canvasContext) 用于设置渲染/绘图上下文 context（针对 Canvas 画布而言）
  在使用面积生成器时，如果设置了绘图上下文 context，就会生成一系列在画布绘制线条的命令/方法；如果没有设置绘图上下文 context，则生成可用于作为 <path> 元素的属性 d 的属性值的字符串
  线段生成器的 context 的默认值为 null 即未设置绘图上下文
• area.lineX0() 和 area.lineY0() 返回一个线段生成器（它的横坐标读取函数返回的是 x0，而纵坐标读取函数返回的是 y1），一般用于在页面生成面积的下边界线，并对其设置样式以对下边界线进行强调显示
• area.lineX1() 返回一个线段生成器，它的横坐标读取函数返回的是 x1，纵坐标读取函数返回的是 y1，一般用于在页面生成面积的上边界线
• area.lineY1() 返回一个线段生成器，它的横坐标读取函数返回的是 x0，纵坐标读取函数返回的是 y1（一般与 area.lineX1() 所返回的线段生成器一样，因为面积生成器的横坐标 x0 的读取函数与 x1 的读取函数一般是一样的）

// 原始数据样例
// 数组每个元素都是一条数据记录，它包含了多个系列的数据（不同类型的水果在当月的销量）
const data = [
  {month: new Date(2015, 0, 1), apples: 3840, bananas: 1920},
  {month: new Date(2015, 1, 1), apples: 1600, bananas: 1440},
];

const stack = d3.stack()
    .keys(["apples", "bananas"])

const series = stack(data);

// 返回的结果，转换后得到各系列的数据
[
  // 每一个系列的数据都独立「抽取」出来组成一个数组
  // apple 系列数据
  [
    // 每个元素都是 apple 的月销量数据点
    // 前两个数值类似于面积图中的下边界线和上边界线
    // data 对象保留了转换前该数据点对应的原始数据来源
    [0, 3840, data: {month: 2014-12-31T16:00Z, apples: 3840, bananas: 1920}], // 12 月销量
    [0, 1600, data: {month: 2015-01-31T16:00Z, apples: 1600, bananas: 1440}], // 1 月销量
    key: "apples", // 该系列对应的 key（名称）
    index: 0 // 该系列在 series 中的顺序（即对应于堆叠条形图中该系列叠放的次序）
  ],
  // bananas 系列数据
  [
    [3840, 5760, data: {month: 2014-12-31T16:00Z, apples: 3840, bananas: 1920}],
    [1600, 3040, data: {month: 2015-01-31T16:00Z, apples: 1600, bananas: 1440}],
    key: "bananas",
    index: 1
  ]
]

function value(d, key) {
  return d[key];
}

曲线插值生成器并不能直接生成形状，而是定义了两个离散点之间的连线如何生成，D3 提供了多种不同的曲线插值生成器，对应于不同的连线方式，它们的作用一般都是基于离散的数据点模拟出顺滑的曲线。

它要与线段生成器或面积生成器配合使用，一般是作为线段生成器的方法 line.curve() 或面积生成器的方法 area.curve() 的入参。

const line = d3.line(d => d.date, d => d.value)
    .curve(d3.curveCatmullRom.alpha(0.5));

D3 提供了多种不同的曲线插值生成器，它们可进行的参数配置也不同，具体的效果可以参考官方文档：

• d3.curveBasis(context)
• d3.curveBasisClosed(context)
• d3.curveBasisOpen(context)
• d3.curveBasisOpen(context)
• d3.curveBumpX(context)
• d3.curveBumpY(context)
• d3.curveBundle(context) 常用于分层的边缘捆绑图 hierarchical edge bundling，只与线段生成器配合使用。该曲线插值生成器 bundle 可以设置 beta 系数 bundle.beta(bataValue)，默认值是 0.85
• d3.curveCardinal(context)
• d3.curveCardinalClosed(context)
• d3.curveCardinalOpen(context)
  以上三种曲线插值生成器 cardinal 可以设置张力 tension 系数 cardinal.tension(tensionValue)，范围是 [1, 0]
• d3.curveCatmullRom(context)
• d3.curveCatmullRomClosed(context)
• d3.curveCatmullRomOpen(context)
  以上三种曲线插值生成器 catmullRom 可以设置 alpha 系数 catmullRom.alpha(alpha)，范围是 [1, 0]
• d3.curveLinear(context)
• d3.curveLinearClosed(context)
• d3.curveMonotoneX(context)
• d3.curveMonotoneY(context)
• d3.curveNatural(context)
• d3.curveStep(context)
• d3.curveStepAfter(context)
• d3.curveStepBefore(context)

连线生成器 Links 基于两个坐标点，绘制出平滑的三次贝塞尔曲线作为两点之间（从起源点 source point 到目标点 target point）的连线，一般用于树形图 tree diagram 中。

所绘制的连线在起点和终点的处的切线可以有三种形式，分别通过三种不同的方法创建三种不同的连线生成器（以下称为 link），适用于不同方向的树形图中

• 使用方法 d3.linkVertical() 创建（生成垂直切线的）连线生成器（以下称为 linkVertical），一般用于父节点和子节点是上下相对位置的树形图中
• 使用方法 d3.linkHorizontal() 创建（生成水平切线的）连线生成器（以下称为 linkHorizontal），一般用于父节点和子节点是水平左右相对位置的树形图中
• 使用方法 d3.linkRadial() 创建（生成径向切线的）连线生成器（以下称为 linkRadial），一般用于根节点在内部，后代节点在外部的环形树形图中

它既是一个方法，可以直接调用，传递需要可视化的数据，连线生成器会根据数据构建出连线。一般是以一个对象作为入参，它最基本的形式是包含 source 和 target 这两个属性，分别表示连线的起点和终点，这两个属性的属性值最基本的形式就是一个数组，分别表示起点或终点的 x 和 y 值

// D3 默认支持的连线生成器入参数据形式
link({
  source: [100, 100],
  target: [300, 300]
});

它也是一个对象，具有多种方法设置不同的参数，一般通过链式调用的方式来使用：

对于 linkVertical 和 linkHorizontal 连线生成器有以下方法

• link.source(sourceFunc) 设置起始点读取函数。该函数的入参是调用连线生成器时传递的数据 d，D3 默认该数据是一个对象，且具有 source 属性表示起始点，因此默认读取函数如下
  js

  function source(d) {
    return d.source;
  }
  

  提示

  如果入参的数据形式和 D3 的默认形式不同，需要手动设置起始点读取函数，返回起始点

• link.target(targetFunc) 设置起始点读取函数。默认读取函数如下
  js

  function target(d) {
    return d.target;
  }
  

• link.x(xFunc) 设置横坐标读取函数。D3 默认起点和终点都是一个含有两个元素的数组，第一个元素表示这些点的横坐标，第二个元素表示这些点的纵坐标，因此默认读取函数如下
  js

  function x(d) {
    return d[0];
  }
  

  提示

  如果入参的数据形式和 D3 的默认形式不同，需要手动设置点读取函数，返回横坐标

• link.y(yFunc) 设置纵坐标读取函数。默认读取函数如下
  js

  function y(d) {
    return d[1];
  }
  

• link.context(canvasContext) 用于设置渲染/绘图上下文 context（针对 Canvas 画布而言）
  在使用连线生成器时，如果设置了绘图上下文 context，就会生成一系列在画布绘制线条的命令/方法；如果没有设置绘图上下文 context，则生成可用于作为 <path> 元素的属性 d 的属性值的字符串
  连线生成器的 context 的默认值为 null 即未设置绘图上下文

对于 linkRadial 连线生成器有类似的方法，不过它的横坐标变成角度（单位是弧度），纵坐标变成了径向距离

• linkRadial.angle(angleFunc) 类似于 link.x(xFunc)，设置角度读取函数，返回的角度单位是弧度
• linkRadial.radius(radiusFunc) 类似于 link.y(yFunc)，设置径向距离读取函数
  提示

  调用径向连线生成器时，它生成的连线的中心坐标默认是 (0, 0)，可以为其父容器（一般是元素 <g>）设置 transform 属性，移动到目标位置

符号生成器 Symbols 提供了一系列常用的符号，一般在散点图中表示数据点，以区分不同的数据类别。

D3 内置了 7 种符号：

• d3.symbolCircle 圆形
• d3.symbolCross 十字形
• d3.symbolDiamond 菱形
• d3.symbolSquare 正方形
• d3.symbolStar 星形
• d3.symbolTriangle（向上的）三角形
• d3.symbolWye Y 形

使用方法 d3.symbol([type][, size]) 创建符号生成器（以下称为 symbol）

创建符号生成器时，第一个（可选）参数设置符号的类型，可以是 7 种内置符号类型之一，也可以是自定义的符号类型；第二个（可选）参数设置符号的尺寸（单位是像素）；如果没有入参，则调用符号生成器时就会默认创建宽和高都为 64 px 的圆形符号。

它既是一个方法，可以直接调用，生成相应的符号。

它也是一个对象，具有多种方法设置不同的参数，一般通过链式调用的方式来使用：

• symbol.type([type]) 设置符号类型，可以是 7 种内置符号类型之一，也可以是自定义的符号类型。默认值是圆形，其入参是函数如下：
  js

  function type() {
    return circle;
  }
  

• symbol.size([size]) 设置符号的尺寸（宽和高都一样），单位是像素，这对于同时希望使用符号类型和符号大小两个视觉通道变量来编码数据是十分有用的。默认值是如下
  js

  function size() {
    return 64;
  }
  

• symbol.context(canvasContext) 用于设置渲染/绘图上下文 context（针对 Canvas 画布而言）
  在使用符号生成器时，如果设置了绘图上下文 context，就会生成一系列在画布绘制线条的命令/方法；如果没有设置绘图上下文 context，则生成可用于作为 <path> 元素的属性 d 的属性值的字符串