Выражения

Для вычислений в Vega предусмотрен собственный язык выражений, на котором можно записывать простые формулы. Например, выражения применяются в преобразованиях filter и formula для обработки данных, а также в определениях сигналов для расчёта новых значений при действиях пользователя.

Язык выражений представляет собой ограниченное подмножество JavaScript. Он поддерживает основные арифметические и логические операции, обращение к свойствам, логические, числовые и строковые литералы, объекты ({}) и массивы ([]). Также доступны тернарный оператор (ifTest ? thenValue : elseValue) и специальная функция if(test, thenValue, elseValue).

Чтобы язык оставался простым, безопасным и не вызывал нежелательных побочных эффектов, в нём запрещены операторы присваивания (=, += и другие), префиксное и постфиксное изменение (++), выражения new и большинство конструкций управления потоком (for, while, switch и другие). Нельзя также вызывать функции через вложенные свойства (foo.bar()). Вместо этого доступны функции, определённые на верхнем уровне.

Эта страница описывает язык выражений. Основная часть его реализации — разбор, генерация кода и некоторые определения констант и функций — находится в модуле vega-expression.

Справочник языка выражений

• Связанные переменные
• Константы
• Функции проверки типов
• Функции преобразования типов
• Функции управления потоком
• Математические функции
• Функции плавности
• Статистические функции
• Функции даты и времени
• Функции массивов
• Строковые функции
• Функции объектов
• Функции форматирования
• Функции регулярных выражений
• Цветовые функции
• Функции событий
• Функции данных
• Функции шкал и проекций
• Географические функции
• Функции деревьев (иерархий)
• Функции браузера
• Функции журнала

Связанные переменные

В языке выражений есть несколько именованных переменных, значения которых подставляются автоматически.

# datum

Текущий объект входных данных, доступный в выражениях преобразования данных и обработчиков событий. Для обращения к свойствам используйте обычный синтаксис JavaScript: datum.value или datum['My Value'].

# event

Если выражение вычисляется в ответ на событие, доступна переменная event. Она содержит стандартное DOM-событие JavaScript и позволяет обращаться к его свойствам, например event.metaKey или event.keyCode.

# имена сигналов

К любому доступному в текущей области видимости сигналу можно обращаться по имени. Например, сигнал hover, заданный в спецификации Vega, доступен в выражении как hover.value. Если имя свойства объекта хранится в сигнале property_name, можно обратиться к нему так: datum[property_name].

К оглавлению

Константы

Постоянные значения, к которым можно обращаться по имени в выражениях.

# NaN
«Не число». Соответствует значению NaN в JavaScript.

# E
Трансцендентное число e. Соответствует Math.E в JavaScript.

# LN2
Натуральный логарифм 2. Соответствует Math.LN2 в JavaScript.

# LN10
Натуральный логарифм 10. Соответствует Math.LN10 в JavaScript.

# LOG2E
Логарифм e по основанию 2. Соответствует Math.LOG2E в JavaScript.

# LOG10E
Логарифм e по основанию 10. Соответствует Math.LOG10E в JavaScript.

# MAX_VALUE
Наибольшее положительное числовое значение. Соответствует Number.MAX_VALUE в JavaScript.

# MIN_VALUE
Наименьшее положительное числовое значение. Соответствует Number.MIN_VALUE в JavaScript.

# PI
Трансцендентное число π. Соответствует Math.PI в JavaScript.

# SQRT1_2
Квадратный корень из 0,5. Соответствует Math.SQRT1_2 в JavaScript.

# SQRT2
Квадратный корень из 2. Соответствует Math.SQRT2 в JavaScript.

К оглавлению

Функции проверки типов

Функции-предикаты для проверки типов значений.

# isArray(value)
Возвращает true, если value — массив, иначе false.

# isBoolean(value)
Возвращает true, если value — логическое значение (true или false), иначе false.

# isDate(value)
Возвращает true, если value — объект Date, иначе false. Для числовой временной метки или строки с датой вернёт false: распознаются только объекты Date.

# isDefined(value) ≥ 5.4
Возвращает true, если value определено, и false, если value равно undefined. Для null и NaN вернёт true.

# isNumber(value)
Возвращает true, если value — число, иначе false. Значения NaN и Infinity считаются числами.

# isObject(value)
Возвращает true, если value — объект, в том числе массив или Date, иначе false.

# isRegExp(value)
Возвращает true, если value — объект RegExp (регулярное выражение), иначе false.

# isString(value)
Возвращает true, если value — строка, иначе false.

# isValid(value) ≥ 5.4
Возвращает true, если value не равно null, undefined или NaN, иначе false.

К оглавлению

Функции преобразования типов

Функции для преобразования значений к нужному типу.

# toBoolean(value)
Преобразует входное value в логическое значение. Значения null, undefined и пустая строка преобразуются в null.

# toDate(value)
Преобразует входное value в числовую временную метку — число миллисекунд с начала эпохи Unix. Значения null, undefined и пустая строка преобразуются в null. Строки разбираются через Date.parse, реализация которого различается между браузерами. Для создания объекта Date используйте datetime.

# toNumber(value)
Преобразует входное value в число. Значения null, undefined и пустая строка преобразуются в null.

# toString(value)
Преобразует входное value в строку. Значения null, undefined и пустая строка преобразуются в null.

Функции управления потоком

# if(test, thenValue, elseValue)
Если test истинно, возвращает thenValue, иначе — elseValue. Функция if эквивалентна тернарному оператору a ? b : c.

К оглавлению

Математические функции

Основные математические функции.

# isNaN(value)
Возвращает true, только если value — числовое значение NaN. Не преобразует аргумент в число: например, для строки "abc" возвращает false. Соответствует Number.isNaN в JavaScript.

# isFinite(value)
Возвращает true, если value — конечное число. Соответствует Number.isFinite в JavaScript.

# abs(value)
Возвращает абсолютное значение value. Соответствует Math.abs в JavaScript.

# acos(value)
Арккосинус. Соответствует Math.acos в JavaScript.

# asin(value)
Арксинус. Соответствует Math.asin в JavaScript.

# atan(value)
Арктангенс. Соответствует Math.atan в JavaScript.

# atan2(dy, dx)
Возвращает угол в радианах для координат dy и dx, учитывая квадрант. Соответствует Math.atan2 в JavaScript.

# ceil(value)
Округляет value вверх до ближайшего целого. Соответствует Math.ceil в JavaScript.

# clamp(value, min, max)
Ограничивает value заданным диапазоном от min до max.

# cos(value)
Косинус. Соответствует Math.cos в JavaScript.

# exp(exponent)
Возвращает e в степени exponent. Соответствует Math.exp в JavaScript.

# floor(value)
Округляет value вниз до ближайшего целого. Соответствует Math.floor в JavaScript.

# hypot(value1, value2, …)
Возвращает квадратный корень из суммы квадратов аргументов. Соответствует Math.hypot в JavaScript.

# log(value)
Возвращает натуральный логарифм value. Соответствует Math.log в JavaScript.

# max(value1, value2, …)
Возвращает наибольшее из переданных значений. Соответствует Math.max в JavaScript.

# min(value1, value2, …)
Возвращает наименьшее из переданных значений. Соответствует Math.min в JavaScript.

# pow(value, exponent)
Возвращает value в степени exponent. Соответствует Math.pow в JavaScript.

# random()
Возвращает псевдослучайное число в диапазоне [0, 1). Соответствует Math.random в JavaScript.

# round(value)
Округляет value до ближайшего целого. Соответствует Math.round в JavaScript.

# sin(value)
Синус. Соответствует Math.sin в JavaScript.

# sqrt(value)
Квадратный корень. Соответствует Math.sqrt в JavaScript.

# tan(value)
Тангенс. Соответствует Math.tan в JavaScript.

К оглавлению

Функции плавности

Функции плавности управляют скоростью анимации во времени. Каждая принимает нормализованное время t в диапазоне [0, 1] и возвращает положение с учётом кривой плавности, причём f(0) === 0 и f(1) === 1. Используются реализации d3-ease с их исходными именами.

Большинство семейств возвращает значения в диапазоне [0, 1], но easeBack и easeElastic намеренно выходят за эти пределы. Если дальнейшему вычислению нужно значение внутри единичного интервала, ограничьте результат, например clamp(easeElastic(t), 0, 1).

Для каждого семейства ниже доступны три варианта: In (медленное начало), Out (медленное завершение) и InOut (медленное начало и завершение). Имя без суффикса обозначает вариант InOut, кроме easeBounce и easeElastic, которые обозначают Out. У easeLinear вариантов нет.

# easeLinear(t)
Тождественная функция: анимация идёт с постоянной скоростью.

# easeQuad(t), easeQuadIn(t), easeQuadOut(t), easeQuadInOut(t)
Квадратичная функция плавности (t²).

# easeCubic(t), easeCubicIn(t), easeCubicOut(t), easeCubicInOut(t)
Кубическая функция плавности (t³).

# easePoly(t), easePolyIn(t), easePolyOut(t), easePolyInOut(t)
Полиномиальная функция плавности; показатель степени по умолчанию в d3 равен 3.

# easeSin(t), easeSinIn(t), easeSinOut(t), easeSinInOut(t)
Синусоидальная функция плавности.

# easeExp(t), easeExpIn(t), easeExpOut(t), easeExpInOut(t)
Экспоненциальная функция плавности (2^t).

# easeCircle(t), easeCircleIn(t), easeCircleOut(t), easeCircleInOut(t)
Круговая функция плавности.

# easeBounce(t), easeBounceIn(t), easeBounceOut(t), easeBounceInOut(t)
Функция плавности с отскоком, как у мяча при падении на твёрдую поверхность. Как и в d3, easeBounce соответствует easeBounceOut.

# easeBack(t), easeBackIn(t), easeBackOut(t), easeBackInOut(t)
Функция плавности с предварительным движением в обратную сторону. Используется стандартный для d3 выход за границы; разные варианты возвращают значения примерно от −0,1 до 1,1.

# easeElastic(t), easeElasticIn(t), easeElasticOut(t), easeElasticInOut(t)
Упругая функция плавности, подобная колебанию резиновой ленты, со стандартными для d3 амплитудой и периодом. Разные варианты возвращают значения примерно от −0,373 до 1,373. Как и в d3, easeElastic соответствует easeElasticOut.

К оглавлению

Статистические функции

Функции для получения выборок и вычисления значений вероятностных распределений.

# sampleNormal([mean, stdev]) ≥ 5.7
Возвращает случайное значение из одномерного нормального распределения (распределения Гаусса) с заданным средним mean и стандартным отклонением stdev. По умолчанию среднее равно 0, стандартное отклонение — 1.

# cumulativeNormal(value[, mean, stdev]) ≥ 5.7
Возвращает значение функции распределения в точке value для нормального распределения со средним mean и стандартным отклонением stdev. По умолчанию среднее равно 0, стандартное отклонение — 1.

# densityNormal(value[, mean, stdev]) ≥ 5.7
Возвращает значение плотности вероятности в точке value для нормального распределения со средним mean и стандартным отклонением stdev. По умолчанию среднее равно 0, стандартное отклонение — 1.

# quantileNormal(probability[, mean, stdev]) ≥ 5.7
Возвращает квантиль (обратную функцию распределения) для вероятности probability при нормальном распределении со средним mean и стандартным отклонением stdev. По умолчанию среднее равно 0, стандартное отклонение — 1.

# sampleLogNormal([mean, stdev]) ≥ 5.7
Возвращает случайное значение из одномерного логнормального распределения с заданными средним логарифма mean и стандартным отклонением логарифма stdev. По умолчанию они равны 0 и 1 соответственно.

# cumulativeLogNormal(value[, mean, stdev]) ≥ 5.7
Возвращает значение функции распределения в точке value для логнормального распределения со средним логарифма mean и стандартным отклонением логарифма stdev. По умолчанию они равны 0 и 1 соответственно.

# densityLogNormal(value[, mean, stdev]) ≥ 5.7
Возвращает значение плотности вероятности в точке value для логнормального распределения со средним логарифма mean и стандартным отклонением логарифма stdev. По умолчанию они равны 0 и 1 соответственно.

# quantileLogNormal(probability[, mean, stdev]) ≥ 5.7
Возвращает квантиль (обратную функцию распределения) для вероятности probability при логнормальном распределении со средним логарифма mean и стандартным отклонением логарифма stdev. По умолчанию они равны 0 и 1 соответственно.

# sampleUniform([min, max]) ≥ 5.7
Возвращает случайное значение из одномерного непрерывного равномерного распределения на интервале [min, max). По умолчанию min равно 0, а max — 1. Если передан один аргумент, он считается значением max.

# cumulativeUniform(value[, min, max]) ≥ 5.7
Возвращает значение функции распределения в точке value для равномерного распределения на интервале [min, max). По умолчанию min равно 0, а max — 1. Если задана только одна необязательная граница, она считается значением max, а min равно 0.

# densityUniform(value[, min, max]) ≥ 5.7
Возвращает значение плотности вероятности в точке value для равномерного распределения на интервале [min, max). По умолчанию min равно 0, а max — 1. Если задана только одна необязательная граница, она считается значением max, а min равно 0.

# quantileUniform(probability[, min, max]) ≥ 5.7
Возвращает квантиль (обратную функцию распределения) для вероятности probability при равномерном распределении на интервале [min, max). По умолчанию min равно 0, а max — 1. Если задана только одна необязательная граница, она считается значением max, а min равно 0.

К оглавлению

Функции даты и времени

Функции для работы с датой и временем.

# now()
Возвращает временную метку текущего момента.

# datetime(year, month[, day, hour, min, sec, millisec])
Возвращает новый объект Date. Нумерация месяцев начинается с нуля, поэтому month = 1 означает февраль.

# date(datetime)
Возвращает день месяца для datetime по местному времени.

# day(datetime)
Возвращает день недели для datetime по местному времени: 0 — воскресенье, 6 — суббота.

# dayofyear(datetime) ≥ 5.11
Возвращает номер дня года для datetime по местному времени; отсчёт начинается с единицы.

# year(datetime)
Возвращает год для datetime по местному времени.

# quarter(datetime)
Возвращает квартал года (от 1 до 4) для datetime по местному времени.

# month(datetime)
Возвращает месяц для datetime по местному времени; отсчёт начинается с нуля.

# week(date) ≥ 5.11
Возвращает номер недели года для datetime по местному времени. Неделя начинается в воскресенье. Дни до первого воскресенья года относятся к нулевой неделе; с первого воскресенья начинается первая неделя, со второго — вторая и так далее.

# isoweek(date) ≥ 6.4
Возвращает номер недели по ISO 8601 для datetime по местному времени. Недели начинаются в понедельник, а первая неделя содержит 4 января. Результат находится в диапазоне от 1 до 53 и относится к недельному году, который может отличаться от календарного.

# hours(datetime)
Возвращает часы для datetime по местному времени.

# minutes(datetime)
Возвращает минуты для datetime по местному времени.

# seconds(datetime)
Возвращает секунды для datetime по местному времени.

# milliseconds(datetime)
Возвращает миллисекунды для datetime по местному времени.

# time(datetime)
Возвращает временную метку для datetime, отсчитываемую от начала эпохи Unix.

# timezoneoffset(datetime)
Возвращает разницу в минутах между UTC и местным временем для datetime (UTC минус местное время).

# timeOffset(unit, date[, step]) ≥ 5.8
Возвращает новый объект Date, полученный смещением date на указанную единицу времени unit в местном часовом поясе. Необязательный аргумент step задаёт число таких шагов (по умолчанию 1).

# timeSequence(unit, start, stop[, step]) ≥ 5.8
Возвращает массив объектов Date от start включительно до stop не включительно с интервалом в указанную единицу времени unit в местном часовом поясе. Необязательный аргумент step задаёт число единиц времени между соседними элементами (по умолчанию 1).

# utc(year, month[, day, hour, min, sec, millisec])
Возвращает временную метку для заданной даты UTC. Нумерация месяцев начинается с нуля, поэтому month = 1 означает февраль.

# utcdate(datetime)
Возвращает день месяца для datetime по времени UTC.

# utcday(datetime)
Возвращает день недели для datetime по времени UTC: 0 — воскресенье, 6 — суббота.

# utcdayofyear(datetime) ≥ 5.11
Возвращает номер дня года для datetime по времени UTC; отсчёт начинается с единицы.

# utcyear(datetime)
Возвращает год для datetime по времени UTC.

# utcquarter(datetime)
Возвращает квартал года (от 1 до 4) для datetime по времени UTC.

# utcmonth(datetime)
Возвращает месяц для datetime по времени UTC; отсчёт начинается с нуля.

# utcweek(date) ≥ 5.11
Возвращает номер недели года для datetime по времени UTC. Неделя начинается в воскресенье. Дни до первого воскресенья года относятся к нулевой неделе; с первого воскресенья начинается первая неделя, со второго — вторая и так далее.

# utcisoweek(date) ≥ 6.4
Возвращает номер недели по ISO 8601 для datetime по времени UTC. Недели начинаются в понедельник, а первая неделя содержит 4 января. Результат находится в диапазоне от 1 до 53 и относится к недельному году, который может отличаться от календарного.

# utchours(datetime)
Возвращает часы для datetime по времени UTC.

# utcminutes(datetime)
Возвращает минуты для datetime по времени UTC.

# utcseconds(datetime)
Возвращает секунды для datetime по времени UTC.

# utcmilliseconds(datetime)
Возвращает миллисекунды для datetime по времени UTC.

# utcOffset(unit, date[, step]) ≥ 5.8
Возвращает новый объект Date, полученный смещением date на указанную единицу времени unit по времени UTC. Необязательный аргумент step задаёт число таких шагов (по умолчанию 1).

# utcSequence(unit, start, stop[, step]) ≥ 5.8
Возвращает массив объектов Date от start включительно до stop не включительно с интервалом в указанную единицу времени unit по времени UTC. Необязательный аргумент step задаёт число единиц времени между соседними элементами (по умолчанию 1).

К оглавлению

Функции массивов

Функции для работы с массивами значений.

# extent(array) ≥ 4.0
Возвращает новый массив [min, max] с минимальным и максимальным значениями исходного массива. Значения null, undefined и NaN игнорируются.

# clampRange(range, min, max)
Ограничивает двухэлементный массив range, сохраняя его ширину. Если ширина исходного диапазона меньше (max - min), но один из его концов выходит за границу min или max, диапазон сдвигается так, чтобы сохранить ширину и коснуться соответствующей границы [min, max]. Если ширина исходного диапазона превышает (max - min), возвращается [min, max].

# indexof(array, value)
Возвращает индекс первого вхождения value в массив array.

# inrange(value, range)
Проверяет, находится ли value между первым и последним значениями массива range, включая границы.

# join(array[, separator]) ≥ 5.3
Возвращает строку из элементов массива array, разделённых запятыми или заданной строкой separator.

# lastindexof(array, value)
Возвращает индекс последнего вхождения value в массив array.

# length(array)
Возвращает длину массива array.

# lerp(array, fraction)
Возвращает результат линейной интерполяции между первым и последним элементами array для доли fraction (обычно от 0 до 1). Например, lerp([0, 50], 0.5) возвращает 25.

# interpolateLinear(array, fraction)
Возвращает результат кусочно-линейной интерполяции по всем элементам array для доли fraction (обычно от 0 до 1). Элементы считаются равноудалёнными опорными точками; интерполяция выполняется внутри соответствующего доле отрезка. В отличие от lerp, здесь учитываются промежуточные значения: interpolateLinear([0, 100, 10], 0.5) возвращает 100, а lerp([0, 100, 10], 0.5) — 5.

# peek(array)
Возвращает последний элемент массива array, не удаляя его. Это удобная замена записи array[array.length - 1], похожая на Array.pop без удаления элемента.

# pluck(array, field) ≥ 5.19
Извлекает значения указанного field из массива объектов array. Строка field может содержать путь к вложенному свойству, например foo.bar.bz.

# reverse(array) ≥ 5.3
Возвращает новый массив с элементами array в обратном порядке: первый становится последним, а последний — первым.

# sequence([start, ]stop[, step])
Возвращает массив с арифметической последовательностью чисел. По умолчанию step равно 1, а start — 0. Значение stop в результат не включается. При положительном step последний элемент — наибольшее значение start + i * step, меньшее stop; при отрицательном — наименьшее значение, большее stop. Если последовательность содержала бы бесконечно много значений, возвращается пустой массив. Аргументы могут быть дробными.

# slice(array, start[, end])
Возвращает часть массива array между индексами start и end. Отрицательное end считается смещением от конца массива (length(array) + end).

# sort(array)
≥ 5.31
Возвращает новый массив, отсортированный в естественном порядке с помощью функции ascending из Vega Utils.

# span(array)
Возвращает размах массива array: разность последнего и первого элементов, то есть array[array.length-1] - array[0].

К оглавлению

Строковые функции

Функции для обработки текстовых строк.

# indexof(string, substring)
Возвращает индекс первого вхождения substring в строку string.

# lastindexof(string, substring)
Возвращает индекс последнего вхождения substring в строку string.

# length(string)
Возвращает длину строки string.

# lower(string)
Преобразует string в нижний регистр.

# pad(string, length[, character, align])
Дополняет строку string повторениями символа character до длины length. Если символ не указан, используется пробел (' '). По умолчанию символы добавляются в конец. Необязательный параметр align задаёт сторону дополнения: 'left' (начало), 'center' (с обеих сторон) или 'right' (конец) строки.

# parseFloat(string)
Преобразует string в число с плавающей точкой. Соответствует parseFloat в JavaScript.

# parseInt(string[, radix])
Разбирает string как целое число. Необязательный radix задаёт основание системы счисления, например 16 для шестнадцатеричной. Соответствует parseInt в JavaScript.

# replace(string, pattern, replacement)
Возвращает новую строку, в которой некоторые или все совпадения с pattern заменены на replacement. Шаблон pattern может быть строкой или регулярным выражением. Для строкового шаблона заменяется только первое совпадение. Соответствует String.replace в JavaScript.

# slice(string, start[, end])
Возвращает часть строки string между индексами start и end. Отрицательное end считается смещением от конца строки (length(string) + end).

# split(string, separator[, limit]) ≥ 4.3
Разбивает строку string по шаблону separator и возвращает массив частей. Необязательный параметр limit ограничивает число возвращаемых частей.

# substring(string, start[, end])
Возвращает часть строки string между индексами start и end.

# trim(string) ≥ 5.3
Возвращает строку без пробельных символов в начале и конце.

# truncate(string, length[, align, ellipsis])
Обрезает строку string до длины length. Необязательный аргумент align определяет, какую часть убрать: 'left' (начало), 'center' (центр) или 'right' (конец). По умолчанию обрезается конец. Аргумент ellipsis задаёт обозначение пропущенного текста; по умолчанию используется многоточие … (\u2026).

# upper(string)
Преобразует string в верхний регистр.

# btoa(string) ≥ 5.32.0
Кодирует двоичную строку (каждый символ с кодом от 0 до 255) в ASCII-строку Base64. Соответствует Window.btoa() в JavaScript.

# atob(string) ≥ 5.32.0
Декодирует ASCII-строку Base64 в двоичную строку. Соответствует Window.atob() в JavaScript.

# encodeURIComponent(string)
Кодирует компонент URI, заменяя некоторые символы их представлением в UTF-8. Соответствует encodeURIComponent() в JavaScript.

К оглавлению

Функции объектов

Функции для работы с объектами.

# merge(object1[, object2, …]) ≥ 4.0
Объединяет объекты object1, object2 и другие в новый объект. Аргументы обрабатываются по порядку: значения свойств из более поздних объектов перезаписывают предыдущие. Пример: merge({a:1, b:2}, {a:3}) -> {a:3, b:2}.

К оглавлению

Функции форматирования

Функции для представления чисел, дат и времени в виде строк.

# dayFormat(day)
Преобразует номер дня недели (от 0 до 6) в полное название согласно текущей локали. Например: dayFormat(0) -> "Sunday" для английской локали.

# dayAbbrevFormat(day)
Преобразует номер дня недели (от 0 до 6) в сокращённое название согласно текущей локали. Например: dayAbbrevFormat(0) -> "Sun" для английской локали.

# format(value, specifier)
Преобразует число value в строку. Параметр specifier должен быть допустимой строкой формата d3-format, например format(value, ',.2f'). Значения null форматируются как "null".

# monthFormat(month)
Преобразует номер месяца (начиная с нуля) в полное название согласно текущей локали. Например: monthFormat(0) -> "January" для английской локали.

# monthAbbrevFormat(month)
Преобразует номер месяца (начиная с нуля) в сокращённое название согласно текущей локали. Например: monthAbbrevFormat(0) -> "Jan" для английской локали.

# timeUnitSpecifier(units[, specifiers]) ≥ 5.8
Возвращает строку формата времени для заданных единиц units. Необязательный объект specifiers содержит части строки формата для её настройки; подробнее см. описание API timeUnitSpecifier. Полученную строку можно передать функциям timeFormat и utcFormat либо использовать как параметр format оси или легенды. Например: timeFormat(date, timeUnitSpecifier('year')) или timeFormat(date, timeUnitSpecifier(['hours', 'minutes'])).

# timeFormat(value, specifier)
Форматирует дату и время value (объект Date или временную метку) как строку по местному времени. Параметр specifier должен быть допустимой строкой формата d3-time-format или объектом TimeMultiFormat ≥ 5.8. Например: timeFormat(timestamp, '%A'). Значения null форматируются как "null".

# timeParse(string, specifier)
Преобразует строку string в объект Date по местному времени. Параметр specifier должен быть допустимой строкой формата d3-time-format. Например: timeParse('June 30, 2015', '%B %d, %Y').

# utcFormat(value, specifier)
Форматирует дату и время value (объект Date или временную метку) как строку по времени UTC. Параметр specifier должен быть допустимой строкой формата d3-time-format или объектом TimeMultiFormat ≥ 5.8. Например: utcFormat(timestamp, '%A'). Значения null форматируются как "null".

# utcParse(value, specifier)
Преобразует строку string в объект Date по времени UTC. Параметр specifier должен быть допустимой строкой формата d3-time-format. Например: utcParse('June 30, 2015', '%B %d, %Y').

К оглавлению

Функции регулярных выражений

Функции для создания и применения регулярных выражений.

# regexp(pattern[, flags]) - Создаёт регулярное выражение из строки pattern и необязательных флагов flags. Соответствует RegExp в JavaScript.

# test(regexp[, string]) - Проверяет строку string регулярным выражением regexp. Возвращает true при совпадении и false в противном случае. Например: test(/\d{3}/, "32-21-9483") -> true.

К оглавлению

Цветовые функции

Функции для представления цветов в разных цветовых пространствах. Они возвращают объекты, которые при преобразовании в строку дают допустимые CSS-цвета RGB.

# rgb(r, g, b[, opacity]) | rgb(specifier)
Создаёт цвет RGB. Аргументы r, g и b задают значения каналов; можно также указать opacity. Если передана строка specifier в формате CSS Color Module Level 3, она разбирается и преобразуется в пространство RGB. Используется функция rgb из d3-color.

# hsl(h, s, l[, opacity]) | hsl(specifier)
Создаёт цвет HSL. Аргументы h, s и l задают значения каналов; можно также указать opacity. Если передана строка specifier в формате CSS Color Module Level 3, она разбирается и преобразуется в пространство HSL. Используется функция hsl из d3-color.

# lab(l, a, b[, opacity]) | lab(specifier)
Создаёт цвет CIE LAB. Аргументы l, a и b задают значения каналов; можно также указать opacity. Если передана строка specifier в формате CSS Color Module Level 3, она разбирается и преобразуется в пространство LAB. Используется функция lab из d3-color.

# hcl(h, c, l[, opacity]) | hcl(specifier)
Создаёт цвет HCL (цветовой тон, цветность, светлота). Аргументы h, c и l задают значения каналов; можно также указать opacity. Если передана строка specifier в формате CSS Color Module Level 3, она разбирается и преобразуется в пространство HCL. Используется функция hcl из d3-color.

# luminance(specifier) ≥ 5.7
Возвращает относительную яркость цвета specifier (совместимого с функцией rgb из d3-color). Яркость рассчитывается по рекомендациям W3C по доступности веб-контента.

# contrast(specifier1, specifier2) ≥ 5.7
Возвращает контрастность между двумя цветами в виде числа от 1 до 21. Расчёт соответствует рекомендациям W3C по доступности веб-контента.

К оглавлению

Функции событий

Функции для обработки входных событий. Их можно вызывать только в выражениях, вычисляемых в ответ на событие, например в обработчике события сигнала. В другом контексте вызов может привести к ошибке.

# item()
Возвращает текущий элемент графа сцены, на который направлено событие.

# group([name])
Возвращает элемент группы графа сцены, в которой произошло событие. Без аргументов возвращается непосредственная родительская группа. Если указано имя, возвращается соответствующая вышестоящая группа.

# xy([item])
Возвращает координаты x и y текущего события в виде массива из двух элементов. Без аргументов используются координаты верхнего уровня представления. Если передан элемент графа сцены item или имя группы, используются координаты этой группы.

# x([item])
Возвращает координату x текущего события. Без аргументов используются координаты верхнего уровня представления. Если передан элемент графа сцены item или имя группы, используются координаты этой группы.

# y([item])
Возвращает координату y текущего события. Без аргументов используются координаты верхнего уровня представления. Если передан элемент графа сцены item или имя группы, используются координаты этой группы.

# pinchDistance(event)
Возвращает расстояние в пикселях между первыми двумя точками касания события с несколькими касаниями.

# pinchAngle(event)
Возвращает угол линии между первыми двумя точками касания события с несколькими касаниями.

# inScope(item)
Возвращает true, если элемент графа сцены item является потомком группы, в которой определён обработчик события, иначе false.

К оглавлению

Функции данных

Функции для доступа к наборам данных Vega.

# data(name)
Возвращает массив объектов набора данных Vega с именем name. Если набор не найден, возвращает пустой массив.

# indata(name, field, value)
Проверяет, содержит ли набор данных name запись, у которой значение поля field совпадает с value. Например: indata('table', 'category', value).

К оглавлению

Функции шкал и проекций

Функции для работы со шкалами Vega и картографическими проекциями.

# scale(name, value[, group])
Применяет шкалу (или проекцию) с заданным именем к value. Необязательный аргумент group принимает элемент группы графа сцены и задаёт область поиска шкалы или проекции.

# invert(name, value[, group])
Выполняет обратное преобразование шкалы (или проекции) с заданным именем для value. Необязательный аргумент group принимает элемент группы графа сцены и задаёт область поиска шкалы или проекции.

# copy(name[, group])
Возвращает копию (новый экземпляр) шкалы или проекции с заданным именем либо undefined, если объект не найден. Необязательный аргумент group принимает элемент группы графа сцены и задаёт область поиска.

# domain(name[, group])
Возвращает массив области определения шкалы с заданным именем либо пустой массив, если шкала не найдена. Необязательный аргумент group принимает элемент группы графа сцены и задаёт область поиска.

# range(name[, group])
Возвращает массив диапазона шкалы с заданным именем либо пустой массив, если шкала не найдена. Необязательный аргумент group принимает элемент группы графа сцены и задаёт область поиска.

# bandwidth(name[, group])
Возвращает текущую ширину полосы шкалы с заданным именем либо ноль, если шкала не найдена или не является полосовой. Необязательный аргумент group принимает элемент группы графа сцены и задаёт область поиска.

# bandspace(count[, paddingInner, paddingOuter])
Возвращает число шагов полосовой шкалы с учётом числа элементов области определения count и внутренних и внешних отступов. Обычно оно вычисляется самой шкалой, но функция полезна при расчёте размеров диаграммы.

# gradient(scale[, p0, p1, count])
Возвращает линейный цветовой градиент для шкалы scale (её диапазон должен быть непрерывной цветовой схемой) между точками p0 и p1, каждая из которых задаётся массивом [x, y]. Координаты точек должны быть заданы в диапазоне [0, 1] относительно границ окрашиваемого элемента. По умолчанию p0 = [0, 0], а p1 = [1, 0]: горизонтальный градиент на всю ширину элемента. Необязательный аргумент count задаёт желаемое число образцов цветовой шкалы.

# panLinear(domain, delta)
Для линейной шкалы с числовой или временной областью определения domain возвращает новый двухэлементный массив после сдвига на долю delta диапазона шкалы. Например, 0.5 означает сдвиг вправо на половину диапазона.

# panLog(domain, delta)
Для логарифмической шкалы с числовой или временной областью определения domain возвращает новый двухэлементный массив после сдвига на долю delta диапазона шкалы. Например, 0.5 означает сдвиг вправо на половину диапазона.

# panPow(domain, delta, exponent)
Для степенной шкалы с числовой или временной областью определения domain и показателем exponent возвращает новый двухэлементный массив после сдвига на долю delta диапазона шкалы. Например, 0.5 означает сдвиг вправо на половину диапазона.

# panSymlog(domain, delta, constant)
Для симметричной логарифмической шкалы с числовой или временной областью определения domain и параметром constant возвращает новый двухэлементный массив после сдвига на долю delta диапазона шкалы. Например, 0.5 означает сдвиг вправо на половину диапазона.

# zoomLinear(domain, anchor, scaleFactor)
Для линейной шкалы с числовой или временной областью определения domain возвращает новый двухэлементный массив после масштабирования с коэффициентом scaleFactor вокруг точки anchor. Точка anchor задаётся значением из области определения шкалы. При null используется середина области в преобразованных координатах; например, для логарифмической шкалы это геометрическое среднее границ.

# zoomLog(domain, anchor, scaleFactor)
Для логарифмической шкалы с числовой или временной областью определения domain возвращает новый двухэлементный массив после масштабирования с коэффициентом scaleFactor вокруг точки anchor. Точка anchor задаётся значением из области определения шкалы. При null используется середина области в преобразованных координатах; например, для логарифмической шкалы это геометрическое среднее границ.

# zoomPow(domain, anchor, scaleFactor, exponent)
Для степенной шкалы с числовой или временной областью определения domain и показателем exponent возвращает новый двухэлементный массив после масштабирования с коэффициентом scaleFactor вокруг точки anchor. Точка anchor задаётся значением из области определения шкалы. При null используется середина области в преобразованных координатах; например, для логарифмической шкалы это геометрическое среднее границ.

# zoomSymlog(domain, anchor, scaleFactor, constant)
Для симметричной логарифмической шкалы с числовой или временной областью определения domain и параметром constant возвращает новый двухэлементный массив после масштабирования с коэффициентом scaleFactor вокруг точки anchor. Точка anchor задаётся значением из области определения шкалы. При null используется середина области в преобразованных координатах; например, для логарифмической шкалы это геометрическое среднее границ.

К оглавлению

Географические функции

Функции для анализа географических областей, представленных объектами GeoJSON.

# geoArea(projection, feature[, group])
Возвращает площадь объекта GeoJSON feature после применения проекции projection (обычно в квадратных пикселях). Если projection равно null, вычисляется сферическая площадь в стерадианах по исходным координатам долготы и широты. Необязательный аргумент group задаёт группу графа сцены, в которой нужно искать проекцию. Используются методы geoArea и path.area из d3-geo.

# geoBounds(projection, feature[, group])
Возвращает ограничивающий прямоугольник объекта GeoJSON feature после применения проекции projection (обычно в пикселях). Он задаётся массивом [[x₀, y₀], [x₁, y₁]], где первые координаты — минимальные, а вторые — максимальные. Если projection равно null, сферические границы вычисляются по исходным долготе и широте. Необязательный аргумент group задаёт группу графа сцены для поиска проекции. Используются методы geoBounds и path.bounds из d3-geo.

# geoCentroid(projection, feature[, group])
Возвращает центроид объекта GeoJSON feature после применения проекции projection (обычно в пикселях). Если projection равно null, сферический центроид вычисляется по исходным долготе и широте. Необязательный аргумент group задаёт группу графа сцены для поиска проекции. Используются методы geoCentroid и path.centroid из d3-geo.

# geoScale(projection[, group])
Возвращает коэффициент масштаба проекции projection. Необязательный аргумент group задаёт группу графа сцены, в которой нужно искать проекцию.

# geoTranslate(projection[, group])
Возвращает двухэлементный массив смещения проекции projection. Необязательный аргумент group задаёт группу графа сцены, в которой нужно искать проекцию.

К оглавлению

Функции деревьев (иерархий)

Функции для обработки иерархических наборов данных, созданных преобразованиями stratify или nest.

# treePath(name, source, target)
Для иерархического набора данных name возвращает кратчайший путь от узла source до узла target. Путь поднимается от source к ближайшему общему предку обоих узлов, а затем спускается к target.

# treeAncestors(name, node)
Для иерархического набора данных name возвращает массив предков узла node: сначала сам узел, затем его родители вплоть до корня.

К оглавлению

Функции браузера

Функции для доступа к возможностям браузера.

# containerSize()
Возвращает текущий размер CSS-блока ([el.clientWidth, el.clientHeight]) родительского DOM-элемента, содержащего представление Vega. Если контейнера нет, возвращает [undefined, undefined]. Чтобы размер представления следовал за контейнером, обновляйте сигнал размера при событии container:resize. ≥ 6.4

# screen()
Возвращает объект window.screen либо {}, если Vega работает вне браузера.

# windowSize()
Возвращает текущий размер окна ([window.innerWidth, window.innerHeight]) либо [undefined, undefined], если Vega работает вне браузера.

К оглавлению

Функции журнала

Функции для вывода сообщений в консоль. Они помогают при отладке выражений.

# warn(value1[, value2, …])
Записывает предупреждение и возвращает последний аргумент. Для вывода сообщения в консоль в представлении должен быть задан подходящий уровень журналирования.

# info(value1[, value2, …])
Записывает информационное сообщение и возвращает последний аргумент. Для вывода сообщения в консоль в представлении должен быть задан подходящий уровень журналирования.

# debug(value1[, value2, …])
Записывает отладочное сообщение и возвращает последний аргумент. Для вывода сообщения в консоль в представлении должен быть задан подходящий уровень журналирования.

К оглавлению