Spec-Zone.ru › D3.js 7

d3-формат

Заметили ли вы, как иногда JavaScript не отображает числа так, как вы ожидаете? Например, вы пытались вывести десятые доли с помощью простого цикла:

for (let i = 0; i < 10; ++i) {
  console.log(0.1 * i);
}

И получили вот это:

0
0.1
0.2
0.30000000000000004
0.4
0.5
0.6000000000000001
0.7000000000000001
0.8
0.9

Добро пожаловать в двойную точность с плавающей запятой! ಠ_ಠ

Тем не менее, ошибка округления – не единственная причина для настройки форматирования чисел. Таблица чисел должна быть отформатирована последовательно для сравнения; выше, 0.0 было бы лучше, чем 0. Большие числа должны иметь сгруппированные цифры (например, 42 000) или быть в научной или метрической нотации (4,2e+4, 42k). Валюты должны иметь фиксированную точность ($3,50). Сообщаемые числовые результаты должны быть округлены до значащих цифр (4021 становится 4000). Форматы чисел должны соответствовать локали пользователя (42.000,00 или 42 000,00). И так далее.

Форматирование чисел для восприятия человеком – цель d3-формат, которая моделируется по мини-языку спецификации формата Python 3 (PEP 3101). Рассмотрим пример выше:

const f = d3.format(".1f");
for (let i = 0; i < 10; ++i) {
  console.log(f(0.1 * i));
}

Теперь вы получите это:

0.0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9

Но d3-формат – намного больше, чем просто псевдоним для number.toFixed! Вот еще несколько примеров:

d3.format(".0%")(0.123);  // rounded percentage, "12%"
d3.format("($.2f")(-3.5); // localized fixed-point currency, "(£3.50)"
d3.format("+20")(42);     // space-filled and signed, "                 +42"
d3.format(".^20")(42);    // dot-filled and centered, ".........42........."
d3.format(".2s")(42e6);   // SI-prefix with two significant digits, "42M"
d3.format("#x")(48879);   // prefixed lowercase hexadecimal, "0xbeef"
d3.format(",.2r")(4223);  // grouped thousands with two significant digits, "4,200"

См. locale.format для подробной спецификации и попробуйте запустить d3.formatSpecifier для указанных выше форматов, чтобы расшифровать их смысл.

Установка

Если вы используете npm, npm install d3-format. Вы также можете загрузить последнюю версию с GitHub. В современных браузерах вы можете импортировать d3-формат из Skypack:

<script type="module">

import {format} from "https://cdn.skypack.dev/d3-format@3";

const f = format(".2s");

</script>

Для устаревших сред вы можете загрузить пакет UMD d3-формат с CDN на основе npm, такого как jsDelivr; экспортируется глобальная переменная d3: 

<script src="https://cdn.jsdelivr.net/npm/d3-format@3"></script>
<script>

var f = d3.format(".2s");

</script>

Файлы локали публикуются в npm и могут быть загружены с помощью d3.json. Например, чтобы установить русский язык как язык по умолчанию:

const locale = await d3.json("https://cdn.jsdelivr.net/npm/d3-format@3/locale/ru-RU.json");
d3.formatDefaultLocale(locale);
const f = d3.format("$,");
console.log(f(1234.56)); // 1 234,56 руб.

Попробуйте d3-формат в своём браузере.

Справочник по API

d3.format(specifier) Источник

Псевдоним для locale.format в языке по умолчанию.

d3.formatPrefix(specifier, value) Источник

Псевдоним для locale.formatPrefix в языке по умолчанию.

locale.format(specifier) Источник

Возвращает новую функцию форматирования для заданного строкового specifier. Возвращаемая функция принимает число в качестве единственного аргумента и возвращает строку, представляющую отформатированное число. Общий вид спецификатора:

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

fill может быть любым символом. Наличие символа заполнения сигнализируется символом align, который следует за ним и должен быть одним из следующих:

  • > - Выравнивает поле справа в доступном пространстве. (Поведение по умолчанию).
  • < - Выравнивает поле слева в доступном пространстве.
  • ^ - Выравнивает поле по центру в доступном пространстве.
  • = - как >, но со знаком и символом слева от любого заполнения.

sign может быть:

  • - - ничего для нуля или положительного и знак минус для отрицательного. (Поведение по умолчанию).
  • + - знак плюс для нуля или положительного и знак минус для отрицательного.
  • ( - ничего для нуля или положительного и скобки для отрицательного.
  • (пробел) - пробел для нуля или положительного и знак минус для отрицательного.

symbol может быть:

  • $ - применять символы валют в соответствии с определением локали.
  • # - для двоичной, восьмеричной или шестнадцатеричной нотации, префикс соответственно 0b, 0o, или 0x.

Опция zero (0) включает нулевое заполнение; это неявно устанавливает fill на 0 и align на =. width определяет минимальную ширину поля; если не указано, ширина определяется содержанием. Опция comma (,) включает использование разделителя групп, такого как запятая для тысяч.

В зависимости от type, precision указывает либо количество цифр после десятичной точки (типы f и %), либо количество значащих цифр (типы ​, e, g, r, s и p). Если точность не указана, она по умолчанию равна 6 для всех типов, кроме ​ (нет), которое по умолчанию равно 12. Точность игнорируется для целочисленных форматов (типы b, o, d, x, и X) и символьных данных (тип c). См. precisionFixed и precisionRound для выбора подходящей точности.

Опция ~ обрезает незначащие конечные нули во всех типах форматов. Это чаще всего используется в сочетании с типами r, e, s и %. Например:

d3.format("s")(1500);  // "1.50000k"
d3.format("~s")(1500); // "1.5k"

Доступные значения type:

  • e - экспоненциальная запись.
  • f - запись с фиксированной точкой.
  • g - либо десятичная, либо экспоненциальная запись, округленная до значащих цифр.
  • r - десятичная запись, округленная до значащих цифр.
  • s - десятичная запись с префиксом СИ, округленная до значащих цифр.
  • % - умножить на 100, а затем десятичная запись со знаком процента.
  • p - умножить на 100, округлить до значащих цифр, а затем десятичная запись со знаком процента.
  • b - двоичная нотация, округлённая до целого числа.
  • o - восьмеричная нотация, округлённая до целого числа.
  • d - десятичная нотация, округлённая до целого числа.
  • x - шестнадцатеричная нотация с использованием строчных букв, округлённая до целого числа.
  • X - шестнадцатеричная нотация с использованием прописных букв, округлённая до целого числа.
  • c - символьные данные для строкового текста.

Тип ​ (нет) также поддерживается как сокращение для ~g (с точностью по умолчанию 12 вместо 6), а тип n — сокращение для ,g. Для типов g, n и ​ (нет) используется десятичная запись, если полученная строка будет содержать precision или меньше цифр; в противном случае используется экспоненциальная запись. Например:

d3.format(".2")(42);  // "42"
d3.format(".2")(4.2); // "4.2"
d3.format(".1")(42);  // "4e+1"
d3.format(".1")(4.2); // "4"
locale.formatPrefix(specifier, value) Источник

Эквивалентно locale.format, за исключением того, что возвращаемая функция преобразует значения в единицы соответствующего префикса СИ для заданного числового значения value перед форматированием в записи с фиксированной точкой. Поддерживаются следующие префиксы:

  • y - йокто, 10⁻²⁴
  • z - зепто, 10⁻²¹
  • a - атто, 10⁻¹⁸
  • f - фемто, 10⁻¹⁵
  • p - пико, 10⁻¹²
  • n - нано, 10⁻⁹
  • µ - микро, 10⁻⁶
  • m - милли, 10⁻³
  • ​ (нет) - 10⁰
  • k - кило, 10³
  • M - мега, 10⁶
  • G - гига, 10⁹
  • T - тера, 10¹²
  • P - пета, 10¹⁵
  • E - экса, 10¹⁸
  • Z - зетта, 10²¹
  • Y - йота, 10²⁴

В отличие от locale.format с форматом s, этот метод возвращает форматировщик с постоянным префиксом СИ, а не вычисляет префикс динамически для каждого числа. Кроме того, precision для данного specifier представляет собой количество цифр после десятичной точки (как в f записи с фиксированной точкой), а не количество значащих цифр. Например:

const f = d3.formatPrefix(",.0", 1e-6);
f(0.00042); // "420µ"
f(0.0042); // "4,200µ"

Этот метод полезен при форматировании нескольких чисел в одних и тех же единицах для удобства сравнения. См. precisionPrefix для выбора подходящей точности и bl.ocks.org/9764126 для примера.

d3.formatSpecifier(specifier) Источник

Парсит указанный specifier, возвращая объект с открытыми полями, соответствующими мини-языку спецификации формата, и методом toString, который восстанавливает спецификатор. Например, formatSpecifier("s") возвращает:

FormatSpecifier {
  "fill": " ",
  "align": ">",
  "sign": "-",
  "symbol": "",
  "zero": false,
  "width": undefined,
  "comma": false,
  "precision": undefined,
  "trim": false,
  "type": "s"
}

Этот метод полезен для понимания того, как обрабатываются спецификаторы формата, и для получения новых спецификаторов. Например, вы можете вычислить подходящую точность на основе чисел, которые вы хотите отформатировать, используя precisionFixed, а затем создать новый формат:

const s = d3.formatSpecifier("f");
s.precision = d3.precisionFixed(0.01);
const f = d3.format(s);
f(42); // "42.00";
new d3.FormatSpecifier(specifier) Source

Принимая заданный объект specifier, возвращает объект с открытыми полями, которые соответствуют мини-языку спецификации формата, и методом toString, который восстанавливает спецификатор. Например, new FormatSpecifier({type: "s"}) возвращает:

FormatSpecifier {
  "fill": " ",
  "align": ">",
  "sign": "-",
  "symbol": "",
  "zero": false,
  "width": undefined,
  "comma": false,
  "precision": undefined,
  "trim": false,
  "type": "s"
}
d3.precisionFixed(step) Source

Возвращает рекомендуемую десятичную точность для обозначения с фиксированной точкой, учитывая заданное числовое значение step. Значение step представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы. (Предполагается, что значения, которые будут отформатированы, также являются кратными step.) Например, для чисел 1, 1.5 и 2 значение step должно быть 0.5, а рекомендуемая точность — 1:

const p = d3.precisionFixed(0.5);
const f = d3.format("." + p + "f");
f(1);   // "1.0"
f(1.5); // "1.5"
f(2);   // "2.0"

В то время как для чисел 1, 2 и 3 значение step должно быть 1, а рекомендуемая точность — 0:

const p = d3.precisionFixed(1);
const f = d3.format("." + p + "f");
f(1); // "1"
f(2); // "2"
f(3); // "3"

Примечание: для формата % отнимите два:

const p = Math.max(0, d3.precisionFixed(0.05) - 2);
const f = d3.format("." + p + "%");
f(0.45); // "45%"
f(0.50); // "50%"
f(0.55); // "55%"
d3.precisionPrefix(step, value) Source

Возвращает рекомендуемую десятичную точность для использования с locale.formatPrefix, учитывая заданные числовое значение step и опорное значение value. Значение step представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы, а value определяет, какой префикс СИ будет использован. (Предполагается, что значения, которые будут отформатированы, также являются кратными step.) Например, для чисел 1.1e6, 1.2e6 и 1.3e6 значение step должно быть 1e5, значение value может быть 1.3e6, а рекомендуемая точность — 1:

const p = d3.precisionPrefix(1e5, 1.3e6);
const f = d3.formatPrefix("." + p, 1.3e6);
f(1.1e6); // "1.1M"
f(1.2e6); // "1.2M"
f(1.3e6); // "1.3M"
d3.precisionRound(step, max) Source

Возвращает рекомендуемую десятичную точность для типов формата, которые округляются до значащих цифр, учитывая заданные числовые значения step и max. Значение step представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы, а max представляет наибольшее абсолютное значение, которое будет отформатировано. (Предполагается, что значения, которые будут отформатированы, также являются кратными step.) Например, для чисел 0.99, 1.0 и 1.01 значение step должно быть 0.01, значение max должно быть 1.01, а рекомендуемая точность — 3:

const p = d3.precisionRound(0.01, 1.01);
const f = d3.format("." + p + "r");
f(0.99); // "0.990"
f(1.0);  // "1.00"
f(1.01); // "1.01"

В то время как для чисел 0.9, 1.0 и 1.1 значение step должно быть 0.1, значение max должно быть 1.1, а рекомендуемая точность — 2:

const p = d3.precisionRound(0.1, 1.1);
const f = d3.format("." + p + "r");
f(0.9); // "0.90"
f(1.0); // "1.0"
f(1.1); // "1.1"

Примечание: для формата e отнимите один:

const p = Math.max(0, d3.precisionRound(0.01, 1.01) - 1);
const f = d3.format("." + p + "e");
f(0.01); // "1.00e-2"
f(1.01); // "1.01e+0"

Локали

d3.formatLocale(definition) Source

Возвращает объект locale для указанного definition с методами locale.format и locale.formatPrefix. definition должен включать следующие свойства:

  • decimal - десятичная точка (например, ".").
  • thousands - разделитель групп (например, ",").
  • grouping - массив размеров групп (например, [3]), циклически используемый по мере необходимости.
  • currency - префикс и суффикс валюты (например, ["$", ""]).
  • numerals - необязательно; массив из десяти строк для замены цифр 0-9.
  • percent - необязательно; знак процента (по умолчанию "%").
  • minus - необязательно; знак минус (по умолчанию "−").
  • nan - необязательно; значение "не число" (по умолчанию "NaN").

Обратите внимание, что свойство thousands является неточным, так как определение группировки позволяет группировать значения не только по тысячам.

d3.formatDefaultLocale(definition) Source

Эквивалентно d3.formatLocale, за исключением того, что оно также переопределяет d3.format и d3.formatPrefix на locale.format и locale.formatPrefix новой локали. Если вы не установили локаль по умолчанию, она устанавливается по умолчанию в американский английский.

© 2010–2023 Michael Bostock
Licensed under the BSD License.
https://github.com/d3/d3-format

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API