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.формат для подробной спецификации и попробуйте запустить 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.формат(спецификатор) Источник

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

d3.форматПрефикс(спецификатор, значение) Источник

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

locale.формат(спецификатор) Источник

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

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

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

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

Знак может быть:

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

Символ может быть:

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

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

В зависимости от типа, точность либо указывает количество цифр после десятичной точки (типы 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"

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

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

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

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.форматПрефикс(спецификатор, значение) Источник

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

• 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.формат с типом формата s, этот метод возвращает форматировщик с согласованным префиксом СИ, а не вычисляет префикс динамически для каждого числа. Кроме того, точность для данного спецификатора представляет количество цифр после десятичной точки (как и с f записью с фиксированной точкой), а не количество значащих цифр. Например:

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

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

d3.форматСпецификатор(спецификатор) Источник

Разбирает указанный спецификатор, возвращая объект с открытыми полями, которые соответствуют мини-языку спецификации формата, и методом 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.ФорматныйОпределяющий(спецификатор) Источник

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

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

d3.точностьФиксированная(шаг) Источник

Возвращает рекомендуемую десятичную точность для фиксированной точки, заданной числовым значением шаг. Шаг представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы. (Предполагается, что значения, которые будут отформатированы, также являются кратными шагу.) Например, для чисел 1, 1,5 и 2, шаг должен быть 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, шаг должен быть 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.точностьПрефиксная(шаг, значение) Источник

Возвращает рекомендуемую десятичную точность для использования с locale.formatPrefix, заданными числовым значением шаг и эталонным значением значение. Шаг представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы, а значение определяет, какой префикс СИ будет использоваться. (Предполагается, что значения, которые будут отформатированы, также являются кратными шагу.) Например, для чисел 1.1e6, 1.2e6 и 1.3e6, шаг должен быть 1e5, значение может быть 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.точностьОкругление(шаг, макс) Источник

Возвращает рекомендуемую десятичную точность для типов формата, которые округляют до значащих цифр, заданных числовыми значениями шаг и макс. Шаг представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы, а макс представляет собой наибольшее абсолютное значение, которое будет отформатировано. (Предполагается, что значения, которые будут отформатированы, также являются кратными шагу.) Например, для чисел 0,99, 1,0 и 1,01, шаг должен быть 0,01, макс должен быть 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, шаг должен быть 0,1, макс должен быть 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.форматЛокали(определение) Источник

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

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

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

d3.форматЛокалиПоУмолчанию(определение) Источник

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