d3.format()用法

This page describes the D3 3.x API.

Formatting numbers is one of those things you don't normally think about until an ugly "0.30000000000000004" appears on your axis labels. Also, maybe you want to group thousands to improve readability, and use fixed precision, such as "$1,240.10". Or, maybe you want to display only the significant digits of a particular number. D3 makes this easy using a standard number format. For example, to create a function that zero-fills to four digits, say:

格式化数字是您通常不会考虑的事情之一，直到您的轴标签上出现一个丑陋的“0.30000000000000004”,另外，也许你想组合成千上万以提高可读性，并使用固定的精度，如“$ 1,240.10”。或者，也许您只想显示特定数字的有效数字。D3使用标准数字格式使其变得容易。 例如，创建一个零来填充到四位数的函数。

var zero = d3.format("04d");

Now you can conveniently format numbers:

现在您可以方便地格式化数字：

zero(2); // "0002"
zero(123); // "0123"

In addition to numbers, D3 also supports formatting and parsing dates, and comma-separated values.

除了数字，D3还支持格式化和解析日期和逗号分隔值。

Numbers

<a name="d3_format" href="#d3_format">#</a> d3.<b>format</b>(<i>specifier</i>)

Returns a new format function with the given string specifier. (Equivalent to locale.numberFormat for the default U.S. English locale.) A format function takes a number as the only argument, and returns a string representing the formatted number. The format specifier is modeled after Python 3.1's built-in format specification mini-language. The general form of a specifier is:

使用给定的字符串说明符返回一个新的格式函数。 （相当于默认的美国英语语言环境的locale.numberFormat。）格式函数使用数字作为唯一的参数，并返回一个表示格式化数字的字符串。格式说明符是在Python 3.1的内置格式规范迷你语言之后建立的。说明符的一般形式是：

 [​[fill]align][sign][symbol][0][width][,][.precision][type]

The fill can be any character other than "{" or "}". The presence of a fill character is signaled by the character following it, which must be one of the align options.

填充可以是除“{”或“}”之外的任何字符。 填充字符的存在由跟随它的字符表示，它必须是对齐选项之一。

The align can be:

• ("<") Forces the field to be left-aligned within the available space.

• (">") Forces the field to be right-aligned within the available space. (This is the default).

• ("^") Forces the field to be centered within the available space.

• ("<")强制字段在可用空间内左对齐。

• (">")强制字段在可用空间内对齐。 （这是默认值）。

• ("^")强制字段以可用空间为中心。

The sign can be:

• plus ("+") - a sign should be used for both positive and negative numbers.

• minus ("-") - a sign should be used only for negative numbers. (This is the default.)

• space (" ") - a leading space should be used on positive numbers, and a minus sign on negative numbers.

• plus ("+") - 正数和负数都应该使用一个符号。

• minus ("-") - 一个符号只能用于负数。 （这是默认值。）

• space (" ") - 一个领先空间应该用于正数，负号上用负数。

The symbol can be:

• currency ("$") - indicates that a currency symbol should be prefixed (or suffixed) per the locale. See Localization for more information on how to set the locale currency symbol.

• base ("#") - for binary, octal, or hexadecimal output, prefix by "0b", "0o", or "0x", respectively.

• currency ("$") - 表示货币符号应该根据区域设置加上（或后缀）。 有关如何设置区域设置货币符号的详细信息，请参阅本地化。

• base ("#") - 用于二进制，八进制或十六进制输出，前缀分别为“0b”，“0o”或“0x”。

The "0" option enables zero-padding.

“0”选项启用零填充。

The width defines the minimum field width. If not specified, then the width will be determined by the content.

width定义最小字段宽度。 如果未指定，则宽度将由内容确定。

The comma (",") option enables the use of a comma for a thousands separator.

comma (",")选项可以为千位分隔符使用逗号。

The precision indicates how many digits should be displayed after the decimal point for a value formatted with types "f" and "%", or before and after the decimal point for a value formatted with types "g", "r" and "p".

precision表示在格式为"f"和"%"类型的格式的小数点后，小数点后面应显示多少个数字，或格式为"g"，"r"和"p"。

The available type values are:

• exponent ("e") - use Number.toExponential.

• general ("g") - use Number.toPrecision.

• fixed ("f") - use Number.toFixed.

• integer ("d") - use Number.toString, but ignore any non-integer values.

• rounded ("r") - round to precision significant digits, padding with zeroes where necessary in similar fashion to fixed ("f"). If no precision is specified, falls back to general notation.

• percentage ("%") - like fixed, but multiply by 100 and suffix with "%".

• rounded percentage ("p") - like rounded, but multiply by 100 and suffix with "%".

• binary ("b") - outputs the number in base 2.

• octal ("o") - outputs the number in base 8.

• hexadecimal ("x") - outputs the number in base 16, using lower-case letters for the digits above 9.

• hexadecimal ("X") - outputs the number in base 16, using upper-case letters for the digits above 9.

• character ("c") - converts the integer to the corresponding unicode character before printing.

• SI-prefix ("s") - like rounded, but with a unit suffixed such as "9.5M" for mega, or "1.00µ" for micro.

• exponent（“e”） - 使用Number.toExponential。

• general（“g”） - 使用Number.toPrecision。

• fixed（“f”） - 使用Number.toFixed。

• integer（“d”） - 使用Number.toString，但忽略任何非整数值。

• 四舍五入（“r”） - 舍入到精确有效数字，必要时用零填充固定（“f”）。如果没有指定精度，则返回到一般符号。

• 百分比（“％”） - 如固定，但乘以100，后缀为“％”。

• 舍入百分比（“p”） - 如圆形，但乘以100，后缀为“％”。

• 二进制（“b”） - 输出基数2中的数字。

• 八进制（“o”） - 输出基数8中的数字。

• 十六进制（“x”） - 输出基数16中的数字，使用9以上数字的小写字母。

• 十六进制（“X”） - 输出基数16中的数字，使用9以上数字的大写字母。

• 字符（“c”） - 在打印之前将整数转换为相应的unicode字符。

• SI前缀（“s”） - 像圆形，但单位后缀如“9.5M”为大，或“1.00μ”为微。

The type "n" is also supported as shorthand for ",g".

类型“n”也被支持作为“，g”的缩写。

<a name="d3_formatPrefix" href="#d3_formatPrefix">#</a> d3.<b>formatPrefix</b>(<i>value</i>[, <i>precision</i>])

Returns the SI prefix for the specified value. If an optional precision is specified, the value is rounded accordingly using d3.round before computing the prefix. The returned prefix object has two properties:

返回指定值的SI前缀。 如果指定了可选精度，则在计算前缀之前，相应地使用d3.round进行舍入。 返回的前缀对象有两个属性：

• symbol - the prefix symbol, such as "M" for millions.

• scale - the scale function, for converting numbers to the appropriate prefixed scale.

• 符号 - 前缀符号，例如数百万的“M”。

• 缩放 - 缩放函数，用于将数字转换为适当的前缀标尺。

For example:

var prefix = d3.formatPrefix(1.21e9);
console.log(prefix.symbol); // "G"
console.log(prefix.scale(1.21e9)); // 1.21

This method is used by d3.format for the s format.

<a name="d3_round" href="#d3_round">#</a> d3.<b>round</b>(<i>x</i>[, <i>n</i>])

Returns the value x rounded to n digits after the decimal point. If n is omitted, it defaults to zero. The result is a number. Values are rounded to the closest multiple of 10 to the power minus n; if two multiples are equally close, the value is rounded up in accordance with the built-in round function. For example:

返回小数点后舍入为n位数的值x。 如果省略n，则默认为零。 结果是一个数字。 值被四舍五入到功率减去n的10的最接近的倍数; 如果两个倍数相等，则该值根据内置的回合函数进行四舍五入。 例如：

d3.round(1.23); // 1
d3.round(1.23, 1); // 1.2
d3.round(1.25, 1); // 1.3
d3.round(12.5, 0); // 13
d3.round(12, -1); // 10

Note that the resulting number when converted to a string may be imprecise due to IEEE floating point precision; to format a number to a string with a fixed number of decimal points, use d3.format instead.

Strings

<a name="d3_requote" href="#d3_requote">#</a> d3.<b>requote</b>(<i>string</i>)

Returns a quoted (escaped) version of the specified string such that the string may be embedded in a regular expression as a string literal.

请注意，由于IEEE浮点精度，转换为字符串时的结果数可能不精确; 要将数字格式化为具有固定小数点数的字符串，请改用d3.format。

d3.requote("[]"); // "\[\]"

Dates

See the d3.time module.