d3-format

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

for (var 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, 42к). Валюты должны иметь фиксированную точность ($3,50). Сообщенные числовые результаты должны быть округлены до значащих цифр (4021 становится 4000). Форматы чисел должны соответствовать региону пользователя (42.000,00 или 42 000,00). Список можно продолжать.

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

var f = d3.format(".1f");
for (var 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-format — это гораздо больше, чем псевдоним для 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. В противном случае загрузите последнюю версию. Вы также можете загрузить напрямую с d3js.org, либо как самостоятельную библиотеку, либо как часть D3 4.0. Поддерживаются среды AMD, CommonJS и vanilla. В vanilla экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-format.v1.min.js"></script>
<script>

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

</script>

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

d3.json("https://unpkg.com/d3-format@1/locale/ru-RU.json", function(error, locale) {
  if (error) throw error;

  d3.formatDefaultLocale(locale);

  var format = d3.format("$,");

  console.log(format(1234.56)); // 1 234,56 руб.
});

Попробуйте d3-format в вашем браузере.

Справочник по 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 для помощи в выборе подходящей точности.

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

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

Тип 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 фиксированной записи), а не количество значащих цифр. Например:

var 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") возвращает:

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

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

var s = d3.formatSpecifier("f");
s.precision = precisionFixed(0.01);
var f = d3.format(s);
f(42); // "42.00";

d3.precisionFixed(step) Источник

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

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

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

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

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

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

d3.precisionPrefix(шаг, значение) Источник

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

var p = d3.precisionPrefix(1e5, 1.3e6),
    f = d3.formatPrefix("." + p, 1.3e6);
f(1.1e6); // "1.1M"
f(1.2e6); // "1.2M"
f(1.3e6); // "1.3M"

d3.precisionRound(шаг, макс) Источник

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

var p = d3.precisionRound(0.01, 1.01),
    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:

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

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

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

Локали

d3.formatLocale(определение) Источник

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

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

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

d3.formatDefaultLocale(определение) Источник

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