线性尺度

¥Linear scales

线性比例尺使用线性变换（平移和缩放）将连续定量输入 domain 映射到连续输出 range。如果范围也是数字，则映射可能是 inverted。对于连续定量数据，线性比例尺是良好的默认选择，因为它们保留了比例差异。每个范围值 y 可以表示为定义域值 x 的函数：y = mx + b。

¥Linear scales map a continuous, quantitative input domain to a continuous output range using a linear transformation (translate and scale). If the range is also numeric, the mapping may be inverted. Linear scales are a good default choice for continuous quantitative data because they preserve proportional differences. Each range value y can be expressed as a function of the domain value x: y = mx + b.

scaleLinear(domain, range)

示例 · 源代码 · 使用指定的 domain 和 range，禁用 default、interpolator 和 clamping，构造一个新的线性比例尺。

¥Examples · Source · Constructs a new linear scale with the specified domain and range, the default interpolator, and clamping disabled.

d3.scaleLinear([0, 100], ["red", "blue"])

如果指定了单个参数，则将其解释为范围。如果未指定域或范围，则每个值默认为 [0, 1]。

¥If a single argument is specified, it is interpreted as the range. If either domain or range are not specified, each defaults to [0, 1].

d3.scaleLinear(["red", "blue"]) // default domain of [0, 1]

linear(value) {#_linear}

示例 · 源代码 · 给定 domain 中的值，返回 range 中的对应值。例如，要应用位置编码：

¥Examples · Source · Given a value from the domain, returns the corresponding value from the range. For example, to apply a position encoding:

const x = d3.scaleLinear([10, 130], [0, 960]);
x(20); // 80
x(50); // 320

要应用颜色编码：

¥To apply a color encoding:

const color = d3.scaleLinear([10, 100], ["brown", "steelblue"]);
color(20); // "rgb(154, 52, 57)"
color(50); // "rgb(123, 81, 103)"

如果给定值超出范围，且未启用 clamping，则映射将被推断，使得返回值超出范围。

¥If the given value is outside the domain, and clamping is not enabled, the mapping will be extrapolated such that the returned value is outside the range.

linear.invert(value) {#linear_invert}

示例 · 源代码 · 给定 range 中的值，返回 domain 中的对应值。反转对于交互很有用，例如确定与鼠标位置对应的数据值。例如，反转位置编码：

¥Examples · Source · Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction, say to determine the data value corresponding to the position of the mouse. For example, to invert a position encoding:

const x = d3.scaleLinear([10, 130], [0, 960]);
x.invert(80); // 20
x.invert(320); // 50

如果给定值超出范围，且未启用 clamping，则映射可能会被推断，使得返回值超出范围。此方法仅在范围为数字时才受支持。如果范围不是数字，则返回 NaN。

¥If the given value is outside the range, and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the domain. This method is only supported if the range is numeric. If the range is not numeric, returns NaN.

对于范围内的有效值 y，linear(linear.invert(y)) 约等于 y；类似地，对于定义域中的有效值 x，linear.invert(linear(x)) 约等于 x。由于浮点精度的限制，比例及其倒数可能不精确。

¥For a valid value y in the range, linear(linear.invert(y)) approximately equals y; similarly, for a valid value x in the domain, linear.invert(linear(x)) approximately equals x. The scale and its inverse may not be exact due to the limitations of floating point precision.

linear.domain(domain) {#linear_domain}

示例 · 源代码 · 如果指定了域，则将比例尺的域设置为指定的数字数组并返回此比例尺。

¥Examples · Source · If domain is specified, sets the scale’s domain to the specified array of numbers and returns this scale.

const x = d3.scaleLinear().domain([10, 130]);

数组必须包含两个或更多元素。如果给定数组中的元素不是数字，则它们将被强制转换为数字。

¥The array must contain two or more elements. If the elements in the given array are not numbers, they will be coerced to numbers.

虽然连续尺度通常在其定义域和值域中各有两个值，但指定两个以上的值会产生分段尺度。例如，要创建一个 不同的颜色比例，使其在白色和红色之间插入负值，在白色和绿色之间插入正值，如下所示：

¥Although continuous scales typically have two values each in their domain and range, specifying more than two values produces a piecewise scale. For example, to create a diverging color scale that interpolates between white and red for negative values, and white and green for positive values, say:

const color = d3.scaleLinear([-1, 0, 1], ["red", "white", "green"]);
color(-0.5); // "rgb(255, 128, 128)"
color(+0.5); // "rgb(128, 192, 128)"

在内部，分段缩放对与给定域值对应的范围插值器执行 二分查找。因此，域必须按升序或降序排列。如果域和范围的长度分别为 N 和 M，则仅观察每个域中的前 min(N,M) 个元素。

¥Internally, a piecewise scale performs a binary search for the range interpolator corresponding to the given domain value. Thus, the domain must be in ascending or descending order. If the domain and range have different lengths N and M, only the first min(N,M) elements in each are observed.

如果未指定域，则返回比例尺当前域的副本。

¥If domain is not specified, returns a copy of the scale’s current domain.

color.domain() // [-1, 0, 1]

linear.range(range) {#linear_range}

示例 · 源代码 · 如果指定了 range，则将比例尺的范围设置为指定的值数组并返回此比例尺。

¥Examples · Source · If range is specified, sets the scale’s range to the specified array of values and returns this scale.

const x = d3.scaleLinear().range([0, 960]);

数组必须包含两个或更多元素。Unlike the domain, elements in the given array need not be numbers;底层 interpolator 支持的任何值都可以，但请注意，invert 需要数值范围。

¥The array must contain two or more elements. Unlike the domain, elements in the given array need not be numbers; any value that is supported by the underlying interpolator will work, though note that numeric ranges are required for invert.

如果未指定范围，则返回比例尺当前范围的副本。

¥If range is not specified, returns a copy of the scale’s current range.

x.range() // [0, 960]

有关更多示例，请参阅 linear.interpolate。

¥See linear.interpolate for more examples.

linear.rangeRound(range) {#linear_rangeRound}

示例 · 源代码 · 将比例尺的 range 设置为指定的值数组，同时将比例尺的 interpolator 设置为 interpolateRound；返回此比例尺。

¥Examples · Source · Sets the scale’s range to the specified array of values while also setting the scale’s interpolator to interpolateRound; returns this scale.

const x = d3.scaleLinear().rangeRound([0, 960]);

这是一个便捷的方法，相当于：

¥This is a convenience method equivalent to:

linear.range(range).interpolate(d3.interpolateRound)

舍入插值器有时有助于避免抗锯齿伪影，但也要考虑 shape-rendering 的“crispEdges”样式。请注意，此插值器只能用于数值范围。

¥The rounding interpolator is sometimes useful for avoiding antialiasing artifacts, though also consider the shape-rendering “crispEdges” styles. Note that this interpolator can only be used with numeric ranges.

linear.clamp(clamp) {#linear_clamp}

示例 · 源代码 · 如果指定了 clip，则相应地启用或禁用 clamp；返回此比例尺。

¥Examples · Source · If clamp is specified, enables or disables clamping accordingly; returns this scale.

const x = d3.scaleLinear([0, 960]).clamp(true);

如果禁用限制，并且向比例尺传递了 domain 范围之外的值，则比例尺可能会通过外推返回 range 范围之外的值。如果启用限制，比例尺的返回值始终在比例尺的范围内。类似地，钳制也适用于 linear.invert。例如：

¥If clamping is disabled and the scale is passed a value outside the domain, the scale may return a value outside the range through extrapolation. If clamping is enabled, the return value of the scale is always within the scale’s range. Clamping similarly applies to linear.invert. For example:

const x = d3.scaleLinear([10, 130], [0, 960]); // clamping disabled by default
x(-10); // -160, outside range
x.invert(-160); // -10, outside domain
x.clamp(true); // enable clamping
x(-10); // 0, clamped to range
x.invert(-160); // 10, clamped to domain

如果未指定 clip，则返回比例尺当前是否将值限制在范围内。

¥If clamp is not specified, returns whether or not the scale currently clamps values to within the range.

x.clamp() // true, perhaps

linear.unknown(value) {#linear_unknown}

示例 · 源代码 · 如果指定了值，则设置比例尺在输入值未定义或为 NaN 时的输出值并返回该比例尺。这对于指定如何显示缺失或无效数据很有用。

¥Examples · Source · If value is specified, sets the output value of the scale for undefined or NaN input values and returns this scale. This is useful for specifying how missing or invalid data is displayed.

const color = d3.scaleLinear([0, 100], ["red", "blue"]).unknown("#ccc");
color(NaN); // "#ccc"

如果未指定值，则返回当前未知值，默认为 undefined。

¥If value is not specified, returns the current unknown value, which defaults to undefined.

color.unknown() // "#ccc"

linear.interpolate(interpolate) {#linear_interpolate}

示例 · 源代码 · 如果指定了 interpolate 参数，则设置比例尺的 range 插值器工厂。

¥Examples · Source · If interpolate is specified, sets the scale’s range interpolator factory.

const color = d3.scaleLinear(["red", "blue"]).interpolate(d3.interpolateHcl);

比例的插值器工厂用于为范围中每对相邻的值创建插值器；然后，这些插值器将 [0, 1] 范围内的规范化域参数 t 映射到该范围内的相应值。如果未指定 factory，则返回比例尺的当前插值器工厂，默认为 d3.interpolate。有关更多插值器，请参阅 d3-interpolate。

¥The scale’s interpolator factory is used to create interpolators for each adjacent pair of values from the range; these interpolators then map a normalized domain parameter t in [0, 1] to the corresponding value in the range. If factory is not specified, returns the scale’s current interpolator factory, which defaults to d3.interpolate. See d3-interpolate for more interpolators.

例如，考虑一个范围内有三种颜色的发散色标：

¥For example, consider a diverging color scale with three colors in the range:

const color = d3.scaleLinear([-100, 0, +100], ["red", "white", "green"]);

Two interpolators are created internally by the scale, equivalent to:

const i0 = d3.interpolate("red", "white");
const i1 = d3.interpolate("white", "green");

指定自定义插值器的一个常见原因是更改插值的颜色空间。例如，要使用 HCL：

¥A common reason to specify a custom interpolator is to change the color space of interpolation. For example, to use HCL:

const color = d3.scaleLinear()
    .domain([10, 100])
    .range(["brown", "steelblue"])
    .interpolate(d3.interpolateHcl);

或者针对 Cubehelix 自定义伽玛值：

¥Or for Cubehelix with a custom gamma:

const color = d3.scaleLinear()
    .domain([10, 100])
    .range(["brown", "steelblue"])
    .interpolate(d3.interpolateCubehelix.gamma(3));

CAUTION

默认插值器 可以重用返回值。例如，如果范围值是对象，则值插值器始终返回相同的对象，并对其进行就地修改。如果比例尺用于设置属性或样式，这通常是可以接受的（并且有利于提高性能）；但是，如果需要存储比例尺的返回值，则必须指定自己的插值器或根据需要进行复制。

¥The default interpolator may reuse return values. For example, if the range values are objects, then the value interpolator always returns the same object, modifying it in-place. If the scale is used to set an attribute or style, this is typically acceptable (and desirable for performance); however, if you need to store the scale’s return value, you must specify your own interpolator or make a copy as appropriate.

linear.ticks(count) {#linear_ticks}

示例 · 源代码 · 从比例尺的 domain 中返回大约 count 个代表值。

¥Examples · Source · Returns approximately count representative values from the scale’s domain.

const x = d3.scaleLinear([10, 100], ["red", "blue"]);
x.ticks(); // [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]

如果未指定 count，则默认为 10。返回的刻度值间距均匀，具有人类可读的值（例如 10 的幂的倍数），并且保证在域范围内。刻度通常用于与可视化数据结合显示参考线或刻度标记。指定的计数只是一个提示；比例尺可能会根据域返回更多或更少的值。另请参阅 d3-array 的 ticks。

¥If count is not specified, it defaults to 10. The returned tick values are uniformly spaced, have human-readable values (such as multiples of powers of 10), and are guaranteed to be within the extent of the domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data. The specified count is only a hint; the scale may return more or fewer values depending on the domain. See also d3-array’s ticks.

linear.tickFormat(count, specifier) {#linear_tickFormat}

示例 · 源代码 · 返回一个适用于显示刻度值的 数字格式 函数，该函数会自动根据刻度值之间的固定间隔计算适当的精度。指定的计数应与用于生成 刻度值 的计数具有相同的值。

¥Examples · Source · Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values. The specified count should have the same value as the count that is used to generate the tick values.

const x = d3.scaleLinear([0.1, 1], ["red", "blue"]);
const f = x.tickFormat();
f(0.1); // "0.1"
f(1); // "1.0"

一个可选的说明符允许使用 自定义格式，其中格式的精度由比例尺根据刻度间隔自动设置。例如，要格式化百分比变化，你可以这样写：

¥An optional specifier allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval. For example, to format percentage change, you might say:

const x = d3.scaleLinear([-1, 1], [0, 960]);
const T = x.ticks(5); // [-1, -0.5, 0, 0.5, 1]
const f = x.tickFormat(5, "+%");
T.map(f); // ["−100%", "−50%", "+0%", "+50%", "+100%"]

如果说明符使用 s 格式类型，则比例尺将根据域中的最大值返回 SI 前缀格式。如果说明符已指定精度，则此方法等同于 locale.format。

¥If specifier uses the format type s, the scale will return a SI-prefix format based on the largest value in the domain. If the specifier already specifies a precision, this method is equivalent to locale.format.

另请参阅 d3.tickFormat。

¥See also d3.tickFormat.

linear.nice(count) {#linear_nice}

示例 · 源代码 · 扩展 domain，使其以整数值开始和结束。

¥Examples · Source · Extends the domain so that it starts and ends on nice round values.

const x = d3.scaleLinear([0.241079, 0.969679], [0, 960]).nice();
x.domain(); // [0.2, 1]

此方法通常会修改比例尺的取值范围，并且可能只会将边界扩展到最接近的整数值。如果域是根据数据计算出来的（比如使用 extent），并且可能不规则，那么 Nicing 就很有用。如果域包含两个以上的值，则对域进行细化处理仅影响第一个和最后一个值。

¥This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value. Nicing is useful if the domain is computed from data, say using extent, and may be irregular. If the domain has more than two values, nicing the domain only affects the first and last value.

可选的刻度计数参数允许更好地控制用于扩展边界的步长，从而保证返回的 ticks 精确覆盖域。

¥An optional tick count argument allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain.

const x = d3.scaleLinear([0.241079, 0.969679], [0, 960]).nice(40);
x.domain(); // [0.24, 0.98]

对比例尺进行细化只会修改当前域；它不会自动优化随后使用 linear.domain 设置的域。如果需要，必须在设置新域后重新调整比例。

¥Nicing a scale only modifies the current domain; it does not automatically nice domains that are subsequently set using linear.domain. You must re-nice the scale after setting the new domain, if desired.

linear.copy() {#linear_copy}

示例 · 源代码 · 返回此比例尺的精确副本。

¥Examples · Source · Returns an exact copy of this scale.

const x1 = d3.scaleLinear([0, 100], ["red", "blue"]);
const x2 = x1.copy();

更改此比例不会影响返回的比例，反之亦然。

¥Changes to this scale will not affect the returned scale, and vice versa.

tickFormat(start, stop, count, specifier)

示例 · 源代码 · 返回一个适用于自动显示刻度值的 数字格式 函数根据 d3.tickStep 确定的刻度值之间的固定间隔计算适当的精度。

¥Examples · Source · Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values, as determined by d3.tickStep.

const f = d3.tickFormat(0, 1, 20);
f(1); // "1.00"

一个可选的说明符允许使用 自定义格式，其中格式的精度由比例尺根据刻度间隔自动设置。例如，要格式化百分比变化，你可以这样写：

¥An optional specifier allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval. For example, to format percentage change, you might say:

const f = d3.tickFormat(-1, 1, 5, "+%");
f(-0.5); // "-50%"

如果 specifier 使用格式类型 s，则比例尺将根据 start 和 stop 中较大的绝对值返回 SI 前缀格式。如果说明符已指定精度，则此方法等同于 locale.format。

¥If specifier uses the format type s, the scale will return a SI-prefix format based on the larger absolute value of start and stop. If the specifier already specifies a precision, this method is equivalent to locale.format.

scaleIdentity(range)

示例 · 源代码 · 使用指定的 range（以及扩展的 domain）构造一个新的恒等比例尺。

¥Examples · Source · Constructs a new identity scale with the specified range (and by extension, domain).

const x = d3.scaleIdentity([0, 960]);

恒等比例尺是 线性比例尺 的一个特例，其定义域和值域相同；因此，比例尺及其反转方法是恒等函数。这些比例尺在使用像素坐标时偶尔会用到，例如与轴结合使用时。恒等比例尺不支持 rangeRound、clamp 或 interpolate。

¥Identity scales are a special case of linear scales where the domain and range are identical; the scale and its invert method are thus the identity function. These scales are occasionally useful when working with pixel coordinates, say in conjunction with an axis. Identity scales do not support rangeRound, clamp or interpolate.

如果未指定范围，则默认为 [0, 1]。

¥If range is not specified, it defaults to [0, 1].

scaleRadial(domain, range)

示例 · 源代码 · 使用指定的 domain 和 range 构造一个新的径向比例尺。

¥Examples · Source · Constructs a new radial scale with the specified domain and range.

const r = d3.scaleRadial([100, 200], [0, 480]);

径向比例是 线性比例尺 的一种变体，其范围在内部进行平方，因此输入值与平方后的输出值线性对应。当你希望输入值与图形标记的面积相对应，并且标记由半径指定时（例如在径向条形图中），这些比例尺非常有用。径向比例不支持 interpolate。

¥Radial scales are a variant of linear scales where the range is internally squared so that an input value corresponds linearly to the squared output value. These scales are useful when you want the input value to correspond to the area of a graphical mark and the mark is specified by radius, as in a radial bar chart. Radial scales do not support interpolate.

如果未指定域或范围，则每个值默认为 [0, 1]。

¥If domain or range is not specified, each defaults to [0, 1].