区域

¥Areas

示例 · 面积生成器生成由顶线和基线定义的区域，类似于面积图。Typically, the two lines share the same x-values (x0 = x1), differing only in y-value (y0 and y1);最常见的情况是，y0 被定义为表示零的常量（y 刻度的零输出）。顶线由 x1 和 y1 定义，并首先渲染；基线由 x0 和 y0 定义，并以相反的顺序渲染第二个基线。使用 curveLinear curve 时，这将生成一个顺时针多边形。另请参阅 径向区域。

¥Examples · The area generator produces an area defined by a topline and a baseline as in an area chart. Typically, the two lines share the same x-values (x0 = x1), differing only in y-value (y0 and y1); most commonly, y0 is defined as a constant representing zero (the y scale’s output for zero). The topline is defined by x1 and y1 and is rendered first; the baseline is defined by x0 and y0 and is rendered second with the points in reverse order. With a curveLinear curve, this produces a clockwise polygon. See also radial areas.

area(x, y0, y1)

源代码 · 使用给定的 x、y0 和 y1 访问器或数字构造一个新的面积生成器。

¥Source · Constructs a new area generator with the given x, y0, and y1 accessors or numbers.

const area = d3.area((d) => x(d.Date), y(0), (d) => y(d.Close));

如果未指定 x、y0 或 y1，则将使用相应的默认值。以上内容可以更明确地表达为：

¥If x, y0 or y1 are not specified, the respective defaults will be used. The above can be expressed more explicitly as:

const area = d3.area()
    .x((d) => x(d.Date))
    .y0(y(0))
    .y1((d) => y(d.Close));

area(data) {#_area}

源代码 · 根据给定的数据数组生成一个区域。

¥Source · Generates an area for the given array of data.

svg.append("path").attr("d", area(data));

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

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

CAUTION

根据此区域生成器关联的 curve，给定的输入数据可能需要按 x 值排序后才能传递给区域生成器。

¥Depending on this area generator’s associated curve, the given input data may need to be sorted by x-value before being passed to the area generator.

area.x(x) {#area_x}

源代码 · 如果指定了 x，则将 x0 设置为 x，将 x1 设置为 null，并返回区域生成器。

¥Source · If x is specified, sets x0 to x and x1 to null and returns this area generator.

const area = d3.area().x((d) => x(d.Date));

如果未指定 x，则返回当前的 x0 访问器。

¥If x is not specified, returns the current x0 accessor.

area.x() // (d) => x(d.Date)

area.x0(x) {#area_x0}

提示

此方法适用于垂直方向的区域，例如时间向下移动↓而不是向右移动→；对于更常见的水平方向区域，请使用 area.x 代替。

¥This method is intended for vertically-oriented areas, as when time goes down↓ rather than right→; for the more common horizontally-oriented areas, use area.x instead.

源代码 · 如果指定了 x，则将 x0 访问器设置为指定的函数或数字并返回此区域生成器。

¥Source · If x is specified, sets the x0 accessor to the specified function or number and returns this area generator.

const area = d3.area().x0(x(0));

当区域为 generated 时，将针对输入数据数组中的每个 defined 元素调用 x0 访问器，并传递元素 d、索引 i 和数组 data 作为三个参数。

¥When an area is generated, the x0 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments.

如果未指定 x，则返回当前的 x0 访问器。

¥If x is not specified, returns the current x0 accessor.

area.x0() // () => 20

x0 访问器默认为：

¥The x0 accessor defaults to:

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

默认的 x0 访问器假定输入数据是包含两个元素的数字数组 [[x0, y0], [x1, y1], …]。如果你的数据采用不同的格式，或者你希望在渲染之前转换数据，则应指定如上所示的自定义访问器。

¥The default x0 accessor assumes that the input data are two-element arrays of numbers [[x0, y0], [x1, y1], …]. If your data are in a different format, or if you wish to transform the data before rendering, then you should specify a custom accessor as shown above.

area.x1(x) {#area_x1}

提示

此方法适用于垂直方向的区域，例如时间向下移动↓而不是向右移动→；对于更常见的水平方向区域，请使用 area.x 代替。

¥This method is intended for vertically-oriented areas, as when time goes down↓ rather than right→; for the more common horizontally-oriented areas, use area.x instead.

源代码 · 如果指定了 x，则将 x1 访问器设置为指定的函数或数字并返回此区域生成器。

¥Source · If x is specified, sets the x1 accessor to the specified function or number and returns this area generator.

const area = d3.area().x1((d) => x(d.Close));

当区域为 generated 时，将针对输入数据数组中的每个 defined 元素调用 x1 访问器，并传递元素 d、索引 i 和数组 data 作为三个参数。

¥When an area is generated, the x1 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments.

如果未指定 x，则返回当前的 x1 访问器。

¥If x is not specified, returns the current x1 accessor.

area.x1() // (d) => x(d.Close)

x1 访问器默认为 null，表示先前计算的 x0 值应重用于 x1 值；此默认值适用于水平方向的区域。

¥The x1 accessor defaults to null, indicating that the previously-computed x0 value should be reused for the x1 value; this default is intended for horizontally-oriented areas.

area.y(y) {#area_y}

提示

此方法适用于垂直方向的区域，例如时间向下移动↓而不是向右移动→；对于更常见的水平方向区域，请使用 area.y0 和 area.y1 代替。

¥This method is intended for vertically-oriented areas, as when time goes down↓ rather than right→; for the more common horizontally-oriented areas, use area.y0 and area.y1 instead.

源代码 · 如果指定了 y，则将 y0 设置为 y，将 y1 设置为 null，并返回此区域生成器。

¥Source · If y is specified, sets y0 to y and y1 to null and returns this area generator.

const area = d3.area().y((d) => y(d.Date));

如果未指定 y，则返回当前的 y0 访问器。

¥If y is not specified, returns the current y0 accessor.

area.y() // (d) => y(d.Date)

area.y0(y) {#area_y0}

源代码 · 如果指定了 y，则将 y0 访问器设置为指定的函数或数字，并返回此区域生成器。

¥Source · If y is specified, sets the y0 accessor to the specified function or number and returns this area generator.

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

当区域为 generated 时，将针对输入数据数组中的每个 defined 元素调用 y0 访问器，并传递元素 d、索引 i 和数组 data 作为三个参数。对于具有恒定基线的水平方向区域（即非堆叠区域，也不是带状区域），y0 通常设置为 y 轴比例尺的输出，即零值。

¥When an area is generated, the y0 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments. For a horizontally-oriented area with a constant baseline (i.e., an area that is not stacked, and not a ribbon or band), y0 is typically set to the output of the y scale for zero.

如果未指定 y，则返回当前的 y0 访问器。

¥If y is not specified, returns the current y0 accessor.

area.y0() // () => 360

y0 访问器默认为：

¥The y0 accessor defaults to:

function y() {
  return 0;
}

请注意，在默认的 SVG 坐标系中，默认零代表图表的顶部而不是底部，从而产生翻转（或“悬挂”）区域。

¥In the default SVG coordinate system, note that the default zero represents the top of the chart rather than the bottom, producing a flipped (or “hanging”) area.

area.y1(y) {#area_y1}

源代码 · 如果指定了 y，则将 y1 访问器设置为指定的函数或数字，并返回此区域生成器。

¥Source · If y is specified, sets the y1 accessor to the specified function or number and returns this area generator.

const area = d3.area().y1((d) => y(d.Close));

当区域为 generated 时，将针对输入数据数组中的每个 defined 元素调用 y1 访问器，并传递元素 d、索引 i 和数组 data 作为三个参数。

¥When an area is generated, the y1 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments.

如果未指定 y，则返回当前的 y1 访问器。

¥If y is not specified, returns the current y1 accessor.

area.y1() // (d) => y(d.Close)

y1 访问器默认为：

¥The y1 accessor defaults to:

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

默认的 y1 访问器假定输入数据是包含两个元素的数字数组 [[x0, y0], [x1, y1], …]。如果你的数据采用不同的格式，或者你希望在渲染之前转换数据，则应指定如上所示的自定义访问器。也允许使用 null 访问器，表示应将先前计算的 y0 值重用于 y1 值；这可以用于垂直方向的区域，例如时间向下↓而不是向右→。

¥The default y1 accessor assumes that the input data are two-element arrays of numbers [[x0, y0], [x1, y1], …]. If your data are in a different format, or if you wish to transform the data before rendering, then you should specify a custom accessor as shown above. A null accessor is also allowed, indicating that the previously-computed y0 value should be reused for the y1 value; this can be used for a vertically-oriented area, as when time goes down↓ instead of right→.

area.defined(defined) {#area_defined}

示例 · 源代码 · 如果指定了定义，则将定义的访问器设置为指定的函数或布尔值，并返回此区域生成器。

¥Examples · Source · If defined is specified, sets the defined accessor to the specified function or boolean and returns this area generator.

const area = d3.area().defined((d) => !isNaN(d.Close));

当区域为 generated 时，将为输入数据数组中的每个元素调用定义的访问器，并传递元素 d、索引 i 和数组 data 作为三个参数。如果给定元素已定义（即，如果定义的访问器返回该元素的真值），则随后将评估 x0、x1、y0 和 y1 访问器，并将该点添加到当前区域段。否则，将跳过该元素，结束当前区域段，并为下一个定义点生成新的区域段。因此，生成的区域可能包含多个离散的段。

¥When an area is generated, the defined accessor will be invoked for each element in the input data array, being passed the element d, the index i, and the array data as three arguments. If the given element is defined (i.e., if the defined accessor returns a truthy value for this element), the x0, x1, y0 and y1 accessors will subsequently be evaluated and the point will be added to the current area segment. Otherwise, the element will be skipped, the current area segment will be ended, and a new area segment will be generated for the next defined point. As a result, the generated area may have several discrete segments.

如果未指定 Defined，则返回当前 Defined 的访问器。

¥If defined is not specified, returns the current defined accessor.

area.defined() // (d) => !isNaN(d.Close)

定义的访问器默认为常量 true，并假定输入数据始终已定义：

¥The defined accessor defaults to the constant true, and assumes that the input data is always defined:

function defined() {
  return true;
}

请注意，如果区域段仅包含一个点，除非使用圆角或方形 线帽 渲染，否则它可能不可见。此外，某些曲线（例如 curveCardinalOpen）仅当包含多个点时才会渲染可见的线段。

¥Note that if an area segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps. In addition, some curves such as curveCardinalOpen only render a visible segment if it contains multiple points.

area.curve(curve) {#area_curve}

源代码 · 如果指定了 curve，则设置 曲线工厂 并返回区域生成器。

¥Source · If curve is specified, sets the curve factory and returns this area generator.

const area = d3.area().curve(d3.curveStep);

如果未指定 curve，则返回当前曲线工厂，默认为 curveLinear。

¥If curve is not specified, returns the current curve factory, which defaults to curveLinear.

area.curve() // d3.curveStep

area.context(context) {#area_context}

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

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

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

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

¥If context is not specified, returns the current context.

area.context() // context

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

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

area.digits(digits) {#area_digits}

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

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

const area = d3.area().digits(3);

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

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

area.digits() // 3

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

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

area.lineX0() {#area_lineX0}

area.lineY0 的别名。

¥An alias for area.lineY0.

area.lineY0() {#area_lineY0}

源代码 · 返回一个新的 线生成器，其中包含此区域生成器当前的 定义的访问器、curve 和 context。线的 x-accessor 对应该区域的 x0-accessor，线的 y-accessor 对应该区域的 y0-accessor。

¥Source · Returns a new line generator that has this area generator’s current defined accessor, curve and context. The line’s x-accessor is this area’s x0-accessor, and the line’s y-accessor is this area’s y0-accessor.

area.lineX1() {#area_lineX1}

源代码 · 返回一个新的 线生成器，其中包含此区域生成器当前的 定义的访问器、curve 和 context。线的 x-accessor 对应该区域的 x1-accessor，线的 y-accessor 对应该区域的 y0-accessor。

¥Source · Returns a new line generator that has this area generator’s current defined accessor, curve and context. The line’s x-accessor is this area’s x1-accessor, and the line’s y-accessor is this area’s y0-accessor.

area.lineY1() {#area_lineY1}

源代码 · 返回一个新的 线生成器，其中包含此区域生成器当前的 定义的访问器、curve 和 context。线的 x-accessor 对应该区域的 x0-accessor，线的 y-accessor 对应该区域的 y1-accessor。

¥Source · Returns a new line generator that has this area generator’s current defined accessor, curve and context. The line’s x-accessor is this area’s x0-accessor, and the line’s y-accessor is this area’s y1-accessor.