D3

d3-color ​

即使你的浏览器能够理解很多颜色知识，它也无法通过 JavaScript 提供太多颜色操作方面的帮助。因此，d3-color 模块提供了各种颜色空间的表示，允许指定、转换和操作。（有关颜色插值，另请参阅 d3-interpolate。）

¥Even though your browser understands a lot about colors, it doesn’t offer much help in manipulating colors through JavaScript. The d3-color module therefore provides representations for various color spaces, allowing specification, conversion and manipulation. (Also see d3-interpolate for color interpolation.)

例如，以命名颜色 steelblue 为例，其 RGB 格式为 rgb(70, 130, 180)：

¥For example, take the named color steelblue, which is rgb(70, 130, 180) in RGB:

js
let c = d3.color("steelblue"); // {r: 70, g: 130, b: 180, opacity: 1}

要转换为 HSL hsl(207.3, 44%, 49%)：

¥To convert to HSL hsl(207.3, 44%, 49%):

js
c = d3.hsl(c); // {h: 207.27…, s: 0.44, l: 0.4902…, opacity: 1}

然后，要将色相旋转 90° hsl(297.3, 44%, 49%)，将饱和度增加 20% hsl(297.3, 64%, 49%)，并将其格式化为 RGB 字符串 rgb(198, 45, 205)：

¥To then rotate the hue by 90° hsl(297.3, 44%, 49%), increase the saturation by 20% hsl(297.3, 64%, 49%), and format as an RGB string rgb(198, 45, 205):

js
c.h += 90;
c.s += 0.2;
c + ""; // rgb(198, 45, 205)

要稍微淡化颜色 rgba(198, 45, 205, 0.8)：

¥To fade the color slightly rgba(198, 45, 205, 0.8):

js
c.opacity = 0.8;
c + ""; // rgba(198, 45, 205, 0.8)

除了普遍适用且机器友好的 RGB 和 HSL 颜色空间外，d3-color 还支持专为人类设计的以下颜色空间：

¥In addition to the ubiquitous and machine-friendly RGB and HSL color space, d3-color supports color spaces that are designed for humans:

Cubehelix 具有单调亮度，而 CIELAB 及其极坐标形式 CIELChab 在感知上是均匀的。

¥Cubehelix features monotonic lightness, while CIELAB and its polar form CIELChab are perceptually uniform.

有关其他颜色空间，请参阅：

¥For additional color spaces, see:

要测量色差，请参阅：

¥To measure color differences, see:

color(specifier) ​

js
d3.color("steelblue") // {r: 70, g: 130, b: 180, opacity: 1}

源代码 · 解析指定的 CSS 颜色模块 3 级 说明符字符串，返回 RGB 或 HSL 颜色，以及 CSS 颜色模块 4 级十六进制 说明符字符串。如果说明符无效，则返回 null。一些示例：

¥Source · Parses the specified CSS Color Module Level 3 specifier string, returning an RGB or HSL color, along with CSS Color Module Level 4 hex specifier strings. If the specifier was not valid, null is returned. Some examples:

  • rgb(255, 255, 255)
  • rgb(10%, 20%, 30%)
  • rgba(255, 255, 255, 0.4)
  • rgba(10%, 20%, 30%, 0.4)
  • hsl(120, 50%, 20%)
  • hsla(120, 50%, 20%, 0.4)
  • #ffeeaa
  • #fea
  • #ffeeaa22
  • #fea2
  • steelblue

支持的 命名颜色 列表由 CSS 指定。

¥The list of supported named colors is specified by CSS.

注意：此函数也可以与 instanceof 一起使用，以测试对象是否为颜色实例。颜色子类也是如此，允许你测试颜色是否位于特定的颜色空间中。

¥Note: this function may also be used with instanceof to test if an object is a color instance. The same is true of color subclasses, allowing you to test whether a color is in a particular color space.

color.opacity {#color_opacity} ​

js
d3.color("steelblue").opacity // 1

此颜色的不透明度，通常在 [0, 1] 范围内。

¥This color’s opacity, typically in the range [0, 1].

color.rgb() {#color_rgb} ​

js
d3.color("hsl(120, 50%, 20%)").rgb() // {r: 25.5, g: 76.5, b: 25.5, opacity: 1}

源代码 · 返回此颜色的 RGB 等效值。对于 RGB 颜色，即 this。

¥Source · Returns the RGB equivalent of this color. For RGB colors, that’s this.

color.copy(values) {#color_copy} ​

js
d3.color("steelblue").copy({opacity: 0.5}) // {r: 70, g: 130, b: 180, opacity: 0.5}

源代码 · 返回此颜色的副本。如果指定了值，则将值的任何可枚举的自身属性分配给新返回的颜色。

¥Source · Returns a copy of this color. If values is specified, any enumerable own properties of values are assigned to the new returned color.

color.brighter(k) {#color_brighter} ​

js
d3.color("steelblue").brighter(1) // {r: 100, g: 185.71428571428572, b: 257.14285714285717, opacity: 1}

源代码 · 返回此颜色的更亮副本。例如，如果 k 为 1，RGB 颜色空间中的 steelblue 将变为 rgb(100, 186, 255)。参数 k 控制返回颜色的亮度（任意单位）；如果未指定 k，则默认为 1。此方法的行为取决于实现的颜色空间。

¥Source · Returns a brighter copy of this color. For example, if k is 1, steelblue in RGB color space becomes rgb(100, 186, 255). The parameter k controls how much brighter the returned color should be (in arbitrary units); if k is not specified, it defaults to 1. The behavior of this method is dependent on the implementing color space.

color.darker(k) {#color_darker} ​

js
d3.color("steelblue").darker(1) // {r: 49, g: 91, b: 126, opacity: 1}

源代码 · 返回此颜色的更暗副本。例如，如果 k 为 1，RGB 颜色空间中的 steelblue 将变为 rgb(49, 91, 126)。参数 k 控制返回颜色的暗度（任意单位）；如果未指定 k，则默认为 1。此方法的行为取决于实现的颜色空间。

¥Source · Returns a darker copy of this color. For example, if k is 1, steelblue in RGB color space becomes rgb(49, 91, 126). The parameter k controls how much darker the returned color should be (in arbitrary units); if k is not specified, it defaults to 1. The behavior of this method is dependent on the implementing color space.

color.displayable() {#color_displayable} ​

js
d3.color("steelblue").displayable(1) // true

源代码 · 当且仅当颜色在标准硬件上可显示时，返回 true。例如，如果任何通道值在四舍五入后小于零或大于 255，或者不透明度不在 [0, 1] 范围内，则对于 RGB 颜色，此方法返回 false。

¥Source · Returns true if and only if the color is displayable on standard hardware. For example, this returns false for an RGB color if any channel value is less than zero or greater than 255 when rounded, or if the opacity is not in the range [0, 1].

color.formatHex() {#color_formatHex} ​

js
d3.color("steelblue").formatHex() // "#4682b4"

源代码 · 返回一个十六进制字符串，在 RGB 空间中表示此颜色，例如 #4682b4。如果此颜色不可显示，则返回合适的可显示颜色。例如，大于 255 的 RGB 通道值将被限制为 255。

¥Source · Returns a hexadecimal string representing this color in RGB space, such as #4682b4. If this color is not displayable, a suitable displayable color is returned instead. For example, RGB channel values greater than 255 are clamped to 255.

color.formatHex8() {#color_formatHex8} ​

js
d3.color("steelblue").formatHex8() // "#4682b4ff"

源代码 · 返回一个十六进制字符串，该字符串在 RGBA 空间中表示此颜色，例如 #4682b4cc。如果此颜色不可显示，则返回合适的可显示颜色。例如，大于 255 的 RGB 通道值将被限制为 255。

¥Source · Returns a hexadecimal string representing this color in RGBA space, such as #4682b4cc. If this color is not displayable, a suitable displayable color is returned instead. For example, RGB channel values greater than 255 are clamped to 255.

color.formatHsl() {#color_formatHsl} ​

js
d3.color("yellow").formatHsl() // "hsl(60, 100%, 50%)"

源代码 · 返回一个根据 CSS 颜色模块 3 级规范 表示此颜色的字符串，例如 hsl(257, 50%, 80%) 或 hsla(257, 50%, 80%, 0.2)。如果此颜色不可显示，则通过将 S 和 L 通道值限制在 [0, 100] 区间内来返回合适的可显示颜色。

¥Source · Returns a string representing this color according to the CSS Color Module Level 3 specification, such as hsl(257, 50%, 80%) or hsla(257, 50%, 80%, 0.2). If this color is not displayable, a suitable displayable color is returned instead by clamping S and L channel values to the interval [0, 100].

color.formatRgb() {#color_formatRgb} ​

js
d3.color("yellow").formatRgb() // "rgb(255, 255, 0)"

源代码 · 返回一个根据 CSS 对象模型规范 表示此颜色的字符串，例如 rgb(247, 234, 186) 或 rgba(247, 234, 186, 0.2)。如果此颜色不可显示，则通过将 RGB 通道值限制在区间 [0, 255] 内来返回合适的可显示颜色。

¥Source · Returns a string representing this color according to the CSS Object Model specification, such as rgb(247, 234, 186) or rgba(247, 234, 186, 0.2). If this color is not displayable, a suitable displayable color is returned instead by clamping RGB channel values to the interval [0, 255].

color.toString() {#color_toString} ​

js
d3.color("yellow").toString() // "rgb(255, 255, 0)"

源代码 · color.formatRgb 的别名。

¥Source · An alias for color.formatRgb.

rgb(color) ​

js
d3.rgb("hsl(60, 100%, 50%)") // {r: 255, g: 255, b: 0, opacity: 1}

源代码 · 构造一个新的 RGB 颜色。通道值在返回的实例上显示为 r、g 和 b 属性。Use the RGB 颜色选择器 to explore this color space.

¥Source · Constructs a new RGB color. The channel values are exposed as r, g and b properties on the returned instance. Use the RGB color picker to explore this color space.

如果指定了 r、g 和 b，则它们代表返回颜色的通道值；还可以指定不透明度。如果指定了 CSS 颜色模块 3 级说明符字符串，则会对其进行解析，然后将其转换为 RGB 颜色空间。示例请参阅 color。如果指定了 color 实例，则会使用 color.rgb 将其转换为 RGB 颜色空间。请注意，与 color.rgb 不同，此方法始终返回一个新实例，即使 color 已经是 RGB 颜色。

¥If r, g and b are specified, these represent the channel values of the returned color; an opacity may also be specified. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the RGB color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb. Note that unlike color.rgb this method always returns a new instance, even if color is already an RGB color.

rgb.clamp() {#rgb_clamp} ​

js
d3.rgb(300, 200, 100).clamp() // {r: 255, g: 200, b: 100, opacity: 1}

源代码 · 返回一个新的 RGB 颜色，其中 r、g 和 b 通道的值被限制在 [0, 255] 范围内并四舍五入为最接近的整数值，opacity 的值被限制在 [0, 1] 范围内。

¥Source · Returns a new RGB color where the r, g, and b channels are clamped to the range [0, 255] and rounded to the nearest integer value, and the opacity is clamped to the range [0, 1].

hsl(color) ​

js
d3.hsl("yellow") // {h: 60, s: 1, l: 0.5, opacity: 1}

源代码 · 构造一个新的 HSL 颜色。通道值在返回的实例上显示为 h、s 和 l 属性。Use the HSL 颜色选择器 to explore this color space.

¥Source · Constructs a new HSL color. The channel values are exposed as h, s and l properties on the returned instance. Use the HSL color picker to explore this color space.

如果指定了 h、s 和 l，则它们表示返回颜色的通道值；还可以指定不透明度。如果指定了 CSS 颜色模块 3 级说明符字符串，则会对其进行解析，然后转换为 HSL 颜色空间。示例请参阅 color。如果指定了 color 实例，则会使用 color.rgb 将其转换为 RGB 颜色空间，然后再转换为 HSL。（HSL 颜色空间中已有的颜色将跳过转换为 RGB。）

¥If h, s and l are specified, these represent the channel values of the returned color; an opacity may also be specified. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the HSL color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to HSL. (Colors already in the HSL color space skip the conversion to RGB.)

hsl.clamp() {#hsl_clamp} ​

js
d3.hsl(400, 2, 0.5).clamp() // {h: 40, s: 1, l: 0.5, opacity: 1}

源代码 · 返回一个新的 HSL 颜色，其中 h 通道限制在 [0, 360) 范围内，s、l 和 opacity 通道限制在 [0, 1] 范围内。

¥Source · Returns a new HSL color where the h channel is clamped to the range [0, 360), and the s, l, and opacity channels are clamped to the range [0, 1].

lab(color) ​

js
d3.lab("red") // {l: 54.29173376861782, a: 80.8124553179771, b: 69.88504032350531, opacity: 1}

源代码 · 构造一个新的 CIELAB 颜色。通道值在返回的实例上显示为 l、a 和 b 属性。Use the CIELAB 颜色选择器 to explore this color space.l 的值通常在 [0, 100] 范围内，而 a 和 b 通常在 [-160, +160] 范围内。

¥Source · Constructs a new CIELAB color. The channel values are exposed as l, a and b properties on the returned instance. Use the CIELAB color picker to explore this color space. The value of l is typically in the range [0, 100], while a and b are typically in [-160, +160].

如果指定了 l、a 和 b，则它们代表返回颜色的通道值；还可以指定不透明度。如果指定了 CSS 颜色模块 3 级说明符字符串，则会对其进行解析，然后转换为 CIELAB 颜色空间。示例请参阅 color。如果指定了 color 实例，则会使用 color.rgb 将其转换为 RGB 颜色空间，然后转换为 CIELAB。（CIELAB 颜色空间中的颜色会跳过到 RGB 的转换，HCL 颜色空间中的颜色会直接转换为 CIELAB。）

¥If l, a and b are specified, these represent the channel values of the returned color; an opacity may also be specified. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the CIELAB color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to CIELAB. (Colors already in the CIELAB color space skip the conversion to RGB, and colors in the HCL color space are converted directly to CIELAB.)

gray(l, opacity) ​

js
d3.gray(50) // {l: 50, a: 0, b: 0, opacity: 1}

源代码 · 使用指定的 l 值和 a = b = 0 构造一个新的 CIELAB 颜色。

¥Source · Constructs a new CIELAB color with the specified l value and a = b = 0.

hcl(color) ​

js
d3.hcl("yellow") // {h: 99.57458688693687, c: 94.70776566727464, l: 97.60712516622824, opacity: 1}

源代码 · 等同于 d3.lch，但参数顺序相反。

¥Source · Equivalent to d3.lch, but with reversed argument order.

lch(color) ​

js
d3.lch("yellow") // {h: 99.57458688693687, c: 94.70776566727464, l: 97.60712516622824, opacity: 1}

源代码 · 构造一个新的 CIELChab 颜色。通道值在返回的实例上显示为 l、c 和 h 属性。Use the CIELChab 颜色选择器 to explore this color space.l 的值通常在 [0, 100] 范围内，c 通常在 [0, 230] 范围内，h 通常在 [0, 360] 范围内。

¥Source · Constructs a new CIELChab color. The channel values are exposed as l, c and h properties on the returned instance. Use the CIELChab color picker to explore this color space. The value of l is typically in the range [0, 100], c is typically in [0, 230], and h is typically in [0, 360).

如果指定了 l、c 和 h，则它们代表返回颜色的通道值；还可以指定不透明度。如果指定了 CSS 颜色模块 3 级说明符字符串，则会对其进行解析，然后转换为 CIELChab 颜色空间。示例请参阅 color。如果指定了 color 实例，则会使用 color.rgb 将其转换为 RGB 颜色空间，然后转换为 CIELChab。（CIELChab 颜色空间中的颜色会跳过到 RGB 的转换，CIELAB 颜色空间中的颜色会直接转换为 CIELChab。）

¥If l, c, and h are specified, these represent the channel values of the returned color; an opacity may also be specified. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to CIELChab color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to CIELChab. (Colors already in CIELChab color space skip the conversion to RGB, and colors in CIELAB color space are converted directly to CIELChab.)

cubehelix(color) ​

js
d3.cubehelix("yellow") // {h: 56.942171677321085, s: 4.614386868039714, l: 0.8900004504279901, opacity: 1}

源代码 · 构造一个新的 Cubehelix 颜色。通道值在返回的实例上显示为 h、s 和 l 属性。

¥Source · Constructs a new Cubehelix color. The channel values are exposed as h, s and l properties on the returned instance.

如果指定了 h、s 和 l，则它们表示返回颜色的通道值；还可以指定不透明度。如果指定了 CSS 颜色模块 3 级说明符字符串，则会对其进行解析，然后转换为 Cubehelix 颜色空间。示例请参阅 color。如果指定了 color 实例，则会使用 color.rgb 将其转换为 RGB 颜色空间，然后转换为 Cubehelix。（Cubehelix 颜色空间中的颜色会跳过到 RGB。）

¥If h, s and l are specified, these represent the channel values of the returned color; an opacity may also be specified. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the Cubehelix color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to Cubehelix. (Colors already in the Cubehelix color space skip the conversion to RGB.)