D3

圆弧 ​

¥Arcs

弧形生成器会生成 circular 或 annular 扇区，类似于 pie 或 donut 图表。圆弧以原点为中心；使用 transform 将圆弧移动到其他位置。

¥The arc generator produces a circular or annular sector, as in a pie or donut chart. Arcs are centered at the origin; use a transform to move the arc to a different position.

js
svg.append("path")
    .attr("transform", "translate(100,100)")
    .attr("d", d3.arc()({
      innerRadius: 100,
      outerRadius: 200,
      startAngle: -Math.PI / 2,
      endAngle: Math.PI / 2
    }));

如果 start 和 end 角度（角度跨度）之间的绝对差大于 2π，则圆弧生成器将生成一个完整的圆或环。如果 interpolator 小于 2π，则圆弧的角长度等于两个角度的绝对差（如果差值为正，则顺时针旋转；如果差值为负，则逆时针旋转）。如果绝对差小于 2π，则圆弧可能有 圆角 和 角度填充。

¥If the absolute difference between the start and end angles (the angular span) is greater than 2π, the arc generator will produce a complete circle or annulus. If it is less than 2π, the arc’s angular length will be equal to the absolute difference between the two angles (going clockwise if the signed difference is positive and anticlockwise if it is negative). If the absolute difference is less than 2π, the arc may have rounded corners and angular padding.

另请参阅 饼图生成器，它计算将数据数组表示为饼图或环形图所需的角度；然后，这些角度可以传递给弧生成器。

¥See also the pie generator, which computes the necessary angles to represent an array of data as a pie or donut chart; these angles can then be passed to an arc generator.

arc() ​

源代码 · 使用默认设置构造一个新的弧生成器。使用默认设置：

¥Source · Constructs a new arc generator with the default settings. With default settings:

js
const arc = d3.arc();

或者，将半径和角度配置为常量：

¥Or, with the radii and angles configured as constants:

js
const arc = d3.arc()
    .innerRadius(0)
    .outerRadius(100)
    .startAngle(0)
    .endAngle(Math.PI / 2);

arc(...arguments) {#_arc} ​

源代码 · 根据给定的参数生成一个圆弧。参数任意；它们会随 this 对象一起传递到弧生成器的访问器函数。例如，在默认设置下，预期为具有半径和角度的对象：

¥Source · Generates an arc for the given arguments. The arguments are arbitrary; they are propagated to the arc generator’s accessor functions along with the this object. For example, with the default settings, an object with radii and angles is expected:

js
const arc = d3.arc();

arc({
  innerRadius: 0,
  outerRadius: 100,
  startAngle: 0,
  endAngle: Math.PI / 2
}); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

如果半径和角度定义为常量，则可以生成不带任何参数的圆弧：

¥If the radii and angles are instead defined as constants, you can generate an arc without any arguments:

js
d3.arc()
    .innerRadius(0)
    .outerRadius(100)
    .startAngle(0)
    .endAngle(Math.PI / 2)
  (); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

如果弧生成器具有 context，则弧将作为 路径方法 调用序列渲染到此上下文，此函数返回 void。否则，返回一个 路径数据 字符串。

¥If the arc generator has a context, then the arc is rendered to this context as a sequence of path method calls and this function returns void. Otherwise, a path data string is returned.

arc.centroid(...arguments) {#arc_centroid} ​

示例 · 源代码 · 计算根据给定参数得到的 generated 圆弧中心线的中点 [x, y]。

¥Examples · Source · Computes the midpoint [x, y] of the center line of the arc that would be generated by the given arguments.

参数任意；它们会随 this 对象一起传递到弧生成器的访问器函数。为了与生成的弧保持一致，访问器必须是确定性的，即，给定相同的参数返回相同的值。中点定义为 (startAngle + endAngle) / 2 和 (innerRadius + outerRadius) / 2。例如：

¥The arguments are arbitrary; they are propagated to the arc generator’s accessor functions along with the this object. To be consistent with the generated arc, the accessors must be deterministic, i.e., return the same value given the same arguments. The midpoint is defined as (startAngle + endAngle) / 2 and (innerRadius + outerRadius) / 2. For example:

请注意，这不是圆弧的几何中心，圆弧的几何中心可能位于圆弧之外；此方法仅仅是为了方便定位标签。

¥Note that this is not the geometric center of the arc, which may be outside the arc; this method is merely a convenience for positioning labels.

arc.innerRadius(radius) {#arc_innerRadius} ​

源代码 · 如果指定了半径，则将内半径设置为指定的函数或数字，并返回此圆弧生成器。

¥Source · If radius is specified, sets the inner radius to the specified function or number and returns this arc generator.

js
const arc = d3.arc().innerRadius(40);

如果未指定半径，则返回当前内半径访问器。

¥If radius is not specified, returns the current inner radius accessor.

js
arc.innerRadius() // () => 40

内半径访问器默认为：

¥The inner radius accessor defaults to:

js
function innerRadius(d) {
  return d.innerRadius;
}

将内半径指定为函数对于构建堆叠极坐标条形图非常有用，通常与 平方比例尺 结合使用。更常见的是，对于圆环图或饼图，使用恒定的内半径。如果外半径小于内半径，则内外半径将交换。负值被视为零。

¥Specifying the inner radius as a function is useful for constructing a stacked polar bar chart, often in conjunction with a sqrt scale. More commonly, a constant inner radius is used for a donut or pie chart. If the outer radius is smaller than the inner radius, the inner and outer radii are swapped. A negative value is treated as zero.

arc.outerRadius(radius) {#arc_outerRadius} ​

源代码 · 如果指定了半径，则将外半径设置为指定的函数或数字，并返回此圆弧生成器。

¥Source · If radius is specified, sets the outer radius to the specified function or number and returns this arc generator.

js
const arc = d3.arc().outerRadius(240);

如果未指定半径，则返回当前外半径访问器。

¥If radius is not specified, returns the current outer radius accessor.

js
arc.outerRadius() // () => 240

外部半径访问器默认为：

¥The outer radius accessor defaults to:

js
function outerRadius(d) {
  return d.outerRadius;
}

将外半径指定为函数对于构建鸡冠花图或极坐标条形图非常有用，通常与 平方比例尺 结合使用。更常见的是，对于饼图或圆环图，使用恒定的外半径。如果外半径小于内半径，则内外半径将交换。负值被视为零。

¥Specifying the outer radius as a function is useful for constructing a coxcomb or polar bar chart, often in conjunction with a sqrt scale. More commonly, a constant outer radius is used for a pie or donut chart. If the outer radius is smaller than the inner radius, the inner and outer radii are swapped. A negative value is treated as zero.

arc.cornerRadius(radius) {#arc_cornerRadius} ​

示例 · 源代码 · 如果指定了 radius 参数，则将圆角半径设置为指定的函数或数字，并返回此圆弧生成器。

¥Examples · Source · If radius is specified, sets the corner radius to the specified function or number and returns this arc generator.

js
const arc = d3.arc().cornerRadius(18);

如果未指定半径，则返回当前圆角半径访问器。

¥If radius is not specified, returns the current corner radius accessor.

js
arc.cornerRadius() // () => 18

圆角半径访问器默认为：

¥The corner radius accessor defaults to:

js
function cornerRadius() {
  return 0;
}

如果圆角半径大于零，则圆弧的圆角将使用给定半径的圆角进行圆角处理。对于扇形，两个外角是圆角；对于扇形，四个角均为圆角。

¥If the corner radius is greater than zero, the corners of the arc are rounded using circles of the given radius. For a circular sector, the two outer corners are rounded; for an annular sector, all four corners are rounded.

圆角半径不得大于 (outerRadius - innerRadius) / 2。此外，对于角跨度小于 π 的圆弧，当两个相邻的圆角相交时，圆角半径可能会减小。这在内角更常见。请参阅 圆弧转角动画 获取说明。

¥The corner radius may not be larger than (outerRadius - innerRadius) / 2. In addition, for arcs whose angular span is less than π, the corner radius may be reduced as two adjacent rounded corners intersect. This occurs more often with the inner corners. See the arc corners animation for illustration.

arc.startAngle(angle) {#arc_startAngle} ​

源代码 · 如果指定了角度，则将起始角度设置为指定的函数或数字，并返回此弧生成器。

¥Source · If angle is specified, sets the start angle to the specified function or number and returns this arc generator.

js
const arc = d3.arc().startAngle(Math.PI / 4);

如果未指定角度，则返回当前起始角度访问器。

¥If angle is not specified, returns the current start angle accessor.

js
arc.startAngle() // () => 0.7853981633974483

起始角度访问器默认为：

¥The start angle accessor defaults to:

js
function startAngle(d) {
  return d.startAngle;
}

角度以弧度表示，0 度位于 -y 轴（12 点钟方向），正角度顺时针旋转。如果 |endAngle - startAngle| ≥ 2π，生成完整的圆或环，而不是扇形。

¥The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise. If |endAngle - startAngle| ≥ 2π, a complete circle or annulus is generated rather than a sector.

arc.endAngle(angle) {#arc_endAngle} ​

源代码 · 如果指定了角度，则将结束角度设置为指定的函数或数字并返回此圆弧生成器。

¥Source · If angle is specified, sets the end angle to the specified function or number and returns this arc generator.

js
const arc = d3.arc().endAngle(Math.PI);

如果未指定角度，则返回当前的结束角度访问器。

¥If angle is not specified, returns the current end angle accessor.

js
arc.endAngle() // () => 3.141592653589793

结束角度访问器默认为：

¥The end angle accessor defaults to:

js
function endAngle(d) {
  return d.endAngle;
}

角度以弧度表示，0 度位于 -y 轴（12 点钟方向），正角度顺时针旋转。如果 |endAngle - startAngle| ≥ 2π，生成完整的圆或环，而不是扇形。

¥The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise. If |endAngle - startAngle| ≥ 2π, a complete circle or annulus is generated rather than a sector.

arc.padAngle(angle) {#arc_padAngle} ​

示例 · 源代码 · 如果指定了 angle，则将填充角度设置为指定的函数或数字，并返回此弧生成器。

¥Examples · Source · If angle is specified, sets the pad angle to the specified function or number and returns this arc generator.

js
const arc = d3.arc().padAngle(0);

如果未指定角度，则返回当前的填充角度访问器。

¥If angle is not specified, returns the current pad angle accessor.

js
arc.padAngle() // () => 0

填充角度访问器默认为：

¥The pad angle accessor defaults to:

js
function padAngle() {
  return d && d.padAngle;
}

填充角度转换为相邻圆弧之间的固定线性距离，定义为 padRadius × padAngle。此距离将从圆弧的 start 和 end 中相等地减去。如果圆弧形成一个完整的圆或环，例如 |endAngle - startAngle| ≥ 2π，忽略填充角度。

¥The pad angle is converted to a fixed linear distance separating adjacent arcs, defined as padRadius × padAngle. This distance is subtracted equally from the start and end of the arc. If the arc forms a complete circle or annulus, as when |endAngle - startAngle| ≥ 2π, the pad angle is ignored.

如果 内部半径 或角度跨度相对于填充角度较小，则可能无法保持相邻圆弧之间的平行边缘。在这种情况下，圆弧的内边缘可能会折叠成一个点，类似于扇形。因此，填充通常仅适用于环形扇区（即，当 innerRadius 为正数时），如下图所示：

¥If the inner radius or angular span is small relative to the pad angle, it may not be possible to maintain parallel edges between adjacent arcs. In this case, the inner edge of the arc may collapse to a point, similar to a circular sector. For this reason, padding is typically only applied to annular sectors (i.e., when innerRadius is positive), as shown in this diagram:

使用填充时，建议的最小内半径为 outerRadius * padAngle / sin(θ)，其中 θ 是填充前最小圆弧的角跨度。例如，如果外半径为 200 像素，填充角度为 0.02 弧度，则合理的 θ 为 0.04 弧度，合理的内半径为 100 像素。请参阅 圆弧填充动画 获取说明。

¥The recommended minimum inner radius when using padding is outerRadius * padAngle / sin(θ), where θ is the angular span of the smallest arc before padding. For example, if the outer radius is 200 pixels and the pad angle is 0.02 radians, a reasonable θ is 0.04 radians, and a reasonable inner radius is 100 pixels. See the arc padding animation for illustration.

通常，填充角度不是直接在圆弧生成器上设置的，而是由 饼图生成器 计算，以确保填充圆弧的面积与其值成正比；参见 pie.padAngle。请参阅 饼图填充动画 获取说明。如果你直接将一个常量填充角度应用于圆弧生成器，它往往会不成比例地从较小的圆弧中减去，从而导致失真。

¥Often, the pad angle is not set directly on the arc generator, but is instead computed by the pie generator so as to ensure that the area of padded arcs is proportional to their value; see pie.padAngle. See the pie padding animation for illustration. If you apply a constant pad angle to the arc generator directly, it tends to subtract disproportionately from smaller arcs, introducing distortion.

arc.padRadius(radius) {#arc_padRadius} ​

源代码 · 如果指定了半径，则将焊盘半径设置为指定的函数或数字，并返回此圆弧生成器。如果未指定半径，则返回当前填充半径访问器，其默认为 null，表示填充半径应自动计算为 sqrt(innerRadius × innerRadius + outerRadius × outerRadius)。填充半径决定了相邻圆弧之间的固定线性距离，定义为 padRadius × padAngle。

¥Source · If radius is specified, sets the pad radius to the specified function or number and returns this arc generator. If radius is not specified, returns the current pad radius accessor, which defaults to null, indicating that the pad radius should be automatically computed as sqrt(innerRadius × innerRadius + outerRadius × outerRadius). The pad radius determines the fixed linear distance separating adjacent arcs, defined as padRadius × padAngle.

arc.context(context) {#arc_context} ​

源代码 · 如果指定了 context，则设置上下文并返回弧形生成器。

¥Source · If context is specified, sets the context and returns this arc generator.

js
const context = canvas.getContext("2d");
const arc = d3.arc().context(context);

如果未指定 context，则返回当前上下文，默认为 null。

¥If context is not specified, returns the current context, which defaults to null.

js
arc.context() // context

如果上下文不为空，则 生成的弧 将作为一系列 路径方法 调用渲染到此上下文。否则，返回一个表示生成的圆弧的 路径数据 字符串。

¥If the context is not null, then the generated arc is rendered to this context as a sequence of path method calls. Otherwise, a path data string representing the generated arc is returned.

arc.digits(digits) {#arc_digits} ​

源代码 · 如果指定了数字，则设置小数点后的最大位数并返回此弧生成器。

¥Source · If digits is specified, sets the maximum number of digits after the decimal separator and returns this arc generator.

js
const arc = d3.arc().digits(3);

如果未指定数字，则返回当前最大分数数字，默认为 3。

¥If digits is not specified, returns the current maximum fraction digits, which defaults to 3.

js
arc.digits() // 3

此选项仅当关联的 context 为空时适用，例如使用此圆弧生成器生成 路径数据 时。

¥This option only applies when the associated context is null, as when this arc generator is used to produce path data.