D3

d3-axis ​

轴组件为位置 scales 渲染人类可读的参考标记。它适用于大多数比例类型，包括如上所示的线性、对数、波段和时间比例。

¥The axis component renders human-readable reference marks for position scales. It works with most scale types, including linear, log, band, and time scales as shown above.

在 SVG 容器（通常是单个 G 元素）的 selection 上调用轴组件会填充轴。坐标轴在原点渲染。要更改轴相对于图表的位置，请在包含元素上指定 变换属性。

¥Calling the axis component on a selection of SVG containers (usually a single G element) populates the axes. Axes are rendered at the origin. To change the position of the axis with respect to the chart, specify a transform attribute on the containing element.

js
const gx = svg.append("g")
    .attr("transform", `translate(0,${height - marginBottom})`)
    .call(d3.axisBottom(x));

如果比例尺已更改，则再次调用轴组件进行更新。为了获得流畅的动画效果，你可以在 transition 上调用它。

¥If the scale has changed, call the axis component a second time to update. For smooth animations, you can call it on a transition.

js
gx.transition()
    .duration(750)
    .call(d3.axisBottom(x));

轴创建的元素被视为其公共 API 的一部分。你可以应用外部样式表或将生成的轴元素修改为 自定义轴外观。一个轴由一个“domain”类的 路径元素 组成，该类表示比例尺的域范围，后面跟着一个经过转换的“tick”类的 g 元素，该类表示比例尺的每个刻度。每个刻度都有一个 线元素 用于绘制刻度线，以及一个 文本元素 用于刻度标签。例如，这是一个典型的底部导向轴：

¥The elements created by the axis are considered part of its public API. You can apply external stylesheets or modify the generated axis elements to customize the axis appearance. An axis consists of a path element of class “domain” representing the extent of the scale’s domain, followed by transformed g elements of class “tick” representing each of the scale’s ticks. Each tick has a line element to draw the tick line, and a text element for the tick label. For example, here is a typical bottom-oriented axis:

html
<g fill="none" font-size="10" font-family="sans-serif" text-anchor="middle">
  <path class="domain" stroke="currentColor" d="M0.5,6V0.5H880.5V6"></path>
  <g class="tick" opacity="1" transform="translate(0.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.0</text>
  </g>
  <g class="tick" opacity="1" transform="translate(176.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.2</text>
  </g>
  <g class="tick" opacity="1" transform="translate(352.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.4</text>
  </g>
  <g class="tick" opacity="1" transform="translate(528.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.6</text>
  </g>
  <g class="tick" opacity="1" transform="translate(704.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.8</text>
  </g>
  <g class="tick" opacity="1" transform="translate(880.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">1.0</text>
  </g>
</g>

轴的方向是固定的；要更改方向，请移除旧轴并创建新轴。

¥The orientation of an axis is fixed; to change the orientation, remove the old axis and create a new axis.

axisTop(scale) ​

源代码 · 根据给定的 scale 构造一个新的顶部导向轴生成器，其中 刻度参数 为空，刻度大小 为 6，padding 为 3。在此方向上，刻度线绘制在水平域路径上方。

¥Source · Constructs a new top-oriented axis generator for the given scale, with empty tick arguments, a tick size of 6 and padding of 3. In this orientation, ticks are drawn above the horizontal domain path.

axisRight(scale) ​

源代码 · 根据给定的 scale 构造一个新的右向轴生成器，其中 刻度参数 为空，刻度大小 为 6，padding 为 3。在此方向上，刻度线绘制在垂直域路径的右侧。

¥Source · Constructs a new right-oriented axis generator for the given scale, with empty tick arguments, a tick size of 6 and padding of 3. In this orientation, ticks are drawn to the right of the vertical domain path.

axisBottom(scale) ​

源代码 · 根据给定的 scale 构造一个新的面向底部的轴生成器，其中 刻度参数 为空，刻度大小 为 6，padding 为 3。在此方向上，刻度线绘制在水平域路径下方。

¥Source · Constructs a new bottom-oriented axis generator for the given scale, with empty tick arguments, a tick size of 6 and padding of 3. In this orientation, ticks are drawn below the horizontal domain path.

axisLeft(scale) ​

源代码 · 根据给定的 scale 构造一个新的面向左侧的轴生成器，其中 刻度参数 为空，刻度大小 为 6，padding 为 3。在此方向上，刻度线绘制在垂直域路径的左侧。

¥Source · Constructs a new left-oriented axis generator for the given scale, with empty tick arguments, a tick size of 6 and padding of 3. In this orientation, ticks are drawn to the left of the vertical domain path.

axis(context) {#_axis} ​

源代码 · 将轴渲染到给定的上下文，该上下文可以是 SVG 容器（SVG 或 G 元素）的 selection 或相应的 transition。

¥Source · Render the axis to the given context, which may be either a selection of SVG containers (either SVG or G elements) or a corresponding transition.

js
svg.append("g")
    .attr("transform", `translate(0,${height - marginBottom})`)
    .call(d3.axisBottom(x));

axis.scale(scale) {#axis_scale} ​

源代码 · 如果指定了 scale ，则将投影的比例因子设置为指定的值，并返回投影。如果未指定 scale，则返回当前的比例。

¥Source · If scale is specified, sets the scale and returns the axis. If scale is not specified, returns the current scale.

js
const xAxis = d3.axisBottom().scale(x);

axis.ticks(...arguments) {#axis_ticks} ​

设置当轴为 rendered 时传递给 scale.ticks 和 scale.tickFormat 的参数，并返回轴生成器。

¥Sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator.

参数的含义取决于 轴缩放 类型：最常见的情况是，参数是建议的刻度计数（或时间刻度的 时间间隔），以及一个可选的 格式说明符，用于自定义刻度值的格式。例如，要以线性刻度生成带有 SI 前缀格式的 20 个刻度，可以使用以下语句：

¥The meaning of the arguments depends on the axis’ scale type: most commonly, the arguments are a suggested count for the number of ticks (or a time interval for time scales), and an optional format specifier to customize how the tick values are formatted. For example, to generate twenty ticks with SI-prefix formatting on a linear scale, say:

js
axis.ticks(20, "s");

要每十五分钟生成一次带有时间刻度的刻度，例如：

¥To generate ticks every fifteen minutes with a time scale, say:

js
axis.ticks(d3.timeMinute.every(15));

此方法是 axis.tickArguments 的一个便捷函数。例如，如下：

¥This method is a convenience function for axis.tickArguments. For example, this:

js
axis.ticks(10);

等同于：

¥Is equivalent to:

js
axis.tickArguments([10]);

如果比例尺未实现 scale.ticks 接口，则此方法无效，就像 band 和 point 比例尺一样。要明确设置刻度值，请使用 axis.tickValues。要明确设置刻度格式，请使用 axis.tickFormat。要直接生成刻度值，请使用 scale.ticks。

¥This method has no effect if the scale does not implement scale.ticks, as with band and point scales. To set the tick values explicitly, use axis.tickValues. To set the tick format explicitly, use axis.tickFormat. To generate tick values directly, use scale.ticks.

axis.tickArguments(arguments) {#axis_tickArguments} ​

源代码 · 如果指定了参数，则设置在轴为 rendered 时将传递给 scale.ticks 和 scale.tickFormat 的参数，并返回轴生成器。另请参阅 axis.ticks，它更为常用。

¥Source · If arguments is specified, sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator. See also axis.ticks, which is used more commonly.

参数的含义取决于 轴缩放 类型：最常见的情况是，参数是建议的刻度计数（或时间刻度的 时间间隔），以及一个可选的 格式说明符，用于自定义刻度值的格式。例如，要以线性刻度生成带有 SI 前缀格式的 20 个刻度，可以使用以下语句：

¥The meaning of the arguments depends on the axis’ scale type: most commonly, the arguments are a suggested count for the number of ticks (or a time interval for time scales), and an optional format specifier to customize how the tick values are formatted. For example, to generate twenty ticks with SI-prefix formatting on a linear scale, say:

js
axis.tickArguments([20, "s"]);

要每十五分钟生成一次带有时间刻度的刻度，例如：

¥To generate ticks every fifteen minutes with a time scale, say:

js
axis.tickArguments([d3.timeMinute.every(15)]);

如果未指定参数，则返回当前刻度参数，默认为空数组。如果指定了参数，且比例尺未实现 scale.ticks 接口，则此方法无效，就像 band 和 point 比例尺一样。要明确设置刻度值，请使用 axis.tickValues。要明确设置刻度格式，请使用 axis.tickFormat。

¥If arguments is not specified, returns the current tick arguments, which defaults to the empty array. If arguments is specified, this method has no effect if the scale does not implement scale.ticks, as with band and point scales. To set the tick values explicitly, use axis.tickValues. To set the tick format explicitly, use axis.tickFormat.

axis.tickValues(values) {#axis_tickValues} ​

源代码 · 如果指定了可迭代值，则指定的值将用于刻度，而不是比例尺的自动刻度生成器。例如，要以特定值生成刻度：

¥Source · If a values iterable is specified, the specified values are used for ticks rather than the scale’s automatic tick generator. For example, to generate ticks at specific values:

js
const axis = d3.axisBottom(x).tickValues([1, 2, 3, 5, 8, 13, 21]);

显式的刻度值优先于 axis.tickArguments 设置的刻度参数。但是，如果未设置刻度格式，任何刻度参数仍将传递给比例尺的 tickFormat 函数。

¥The explicit tick values take precedence over the tick arguments set by axis.tickArguments. However, any tick arguments will still be passed to the scale’s tickFormat function if a tick format is not also set.

如果值为 null，则清除所有先前设置的显式刻度值，并恢复为比例尺的刻度生成器。如果未指定值，则返回当前刻度值，默认为 null。

¥If values is null, clears any previously-set explicit tick values and reverts back to the scale’s tick generator. If values is not specified, returns the current tick values, which defaults to null.

axis.tickFormat(format) {#axis_tickFormat} ​

源代码 · 如果指定了 format，则设置 tick 格式函数并返回轴。例如，要显示以逗号分组的千位整数：

¥Source · If format is specified, sets the tick format function and returns the axis. For example, to display integers with comma-grouping for thousands:

js
axis.tickFormat(d3.format(",.0f"));

更常见的是，将格式说明符传递给 axis.ticks，其优点是根据刻度间隔自动设置格式精度：

¥More commonly, a format specifier is passed to axis.ticks, which has the advantage of setting the format precision automatically based on the tick interval:

js
axis.ticks(10, ",f");

有关创建格式化程序的帮助，请参阅 d3-format 和 d3-time-format。

¥See d3-format and d3-time-format for help creating formatters.

如果未指定 format，则返回当前的 format 函数，默认为 null。格式为 null 表示应使用刻度的默认格式化程序，该格式化程序通过调用 scale.tickFormat 生成。在这种情况下，axis.tickArguments 指定的参数同样会传递给 scale.tickFormat。

¥If format is not specified, returns the current format function, which defaults to null. A null format indicates that the scale’s default formatter should be used, which is generated by calling scale.tickFormat. In this case, the arguments specified by axis.tickArguments are likewise passed to scale.tickFormat.

axis.tickSize(size) {#axis_tickSize} ​

源代码 · 如果指定了 size，则将输入值网格的预期大小设置为 inner 并返回轮廓生成器。

¥Source · If size is specified, sets the inner and outer tick size to the specified value and returns the axis.

js
const axis = d3.axisBottom(x).tickSize(0);

如果未指定大小，则返回当前内部刻度大小，默认为 6。

¥If size is not specified, returns the current inner tick size, which defaults to 6.

js
axis.tickSize() // 0, as specified above

axis.tickSizeInner(size) {#axis_tickSizeInner} ​

源代码 · 如果指定了 size，则将外部刻度大小设置为指定的值并返回轴。

¥Source · If size is specified, sets the inner tick size to the specified value and returns the axis.

js
const axis = d3.axisBottom(x).tickSizeInner(0);

如果未指定大小，则返回当前内部刻度大小，默认为 6。

¥If size is not specified, returns the current inner tick size, which defaults to 6.

js
axis.tickSizeInner() // 0, as specified above

内刻度大小控制刻度线的长度，相对于轴的原始位置偏移。

¥The inner tick size controls the length of the tick lines, offset from the native position of the axis.

axis.tickSizeOuter(size) {#axis_tickSizeOuter} ​

源代码 · 如果指定了 size，则将画笔句柄的大小设置为指定的数字并返回画笔。

¥Source · If size is specified, sets the outer tick size to the specified value and returns the axis.

js
const axis = d3.axisBottom(x).tickSizeOuter(0);

如果未指定大小，则返回当前外部刻度大小，默认为 6。

¥If size is not specified, returns the current outer tick size, which defaults to 6.

js
axis.tickSizeOuter() // 0, as specified above

外部刻度大小控制域路径方形端点的长度，相对于轴的原始位置偏移。因此，“外部刻度”实际上不是刻度，而是域路径的一部分，它们的位置由关联比例尺的域范围决定。因此，外层刻度可能与第一个或最后一个内层刻度重叠。外部刻度大小为 0 会抑制域路径的方形端点，而是生成一条直线。

¥The outer tick size controls the length of the square ends of the domain path, offset from the native position of the axis. Thus, the “outer ticks” are not actually ticks but part of the domain path, and their position is determined by the associated scale’s domain extent. Thus, outer ticks may overlap with the first or last inner tick. An outer tick size of 0 suppresses the square ends of the domain path, instead producing a straight line.

axis.tickPadding(padding) {#axis_tickPadding} ​

源代码 · 如果指定了 padding，则将 padding 设置为指定的像素值，并返回轴。

¥Source · If padding is specified, sets the padding to the specified value in pixels and returns the axis.

js
const axis = d3.axisBottom(x).tickPadding(0);

如果未指定 padding，则返回当前 padding，默认为 3 像素。

¥If padding is not specified, returns the current padding which defaults to 3 pixels.

js
axis.tickPadding() // 0, as specified above

axis.offset(offset) {#axis_offset} ​

源代码 · 如果指定了 offset，则将像素偏移设置为指定的像素值，并返回轴。

¥Source · If offset is specified, sets the pixel offset to the specified value in pixels and returns the axis.

js
const axis = d3.axisBottom(x).offset(0);

如果未指定 offset，则返回当前像素偏移量。

¥If offset is not specified, returns the current pixel offset.

js
axis.offset() // 0

在 devicePixelRatio 大于 1 的设备上，像素偏移默认为 0，否则为 0.5。此默认像素偏移可确保在低分辨率设备上呈现清晰的边缘。

¥The pixel offset defaults to 0 on devices with a devicePixelRatio greater than 1, and 0.5 otherwise. This default pixel offset ensures crisp edges on low-resolution devices.