Типы параметров

Справочник по распространённым типам параметров, которые используются в свойствах спецификации Vega.

Справочник по типам параметров

• Any
• Array
• Boolean
• Color
• Date
• Gradient
• Number
• Object
• String
• URL
• Data
• Field
• Signal
• Compare
• Expr
• Value
• ColorValue
• FieldValue
• GradientValue
• TimeMultiFormat

Литеральные значения

# Any или *

Принимает любое литеральное значение: строку, число, логическое значение или null.

# Array или Type[ ]

Принимает массивы, например [], [1, 2, 3], ["foo", "bar"]. Если элементы массива должны иметь определённый тип, он указывается перед квадратными скобками: например, Number[ ] или String[ ].

В большинстве случаев элементы массива могут быть ссылками на сигналы, например [{"signal": "width"}, {"signal": "height"}].

# Boolean

Принимает логические значения, например true и false.

# Color

Принимает корректную строку цвета CSS, например #f304d3, #ccc, rgb(253, 12, 134) или steelblue.

# Date

Корректный объект JavaScript Date или временная метка. JSON не поддерживает даты непосредственно, поэтому в спецификации Vega дату и время можно задать числовой меткой — количеством миллисекунд с начала эпохи UNIX, как возвращает Date.getTime(), — или выражением сигнала, например {"signal": "datetime(2001, 2, 3)"}.

# Gradient ≥ 5.4

Принимает объект, задающий цветовой градиент. Чтобы определить линейный градиент на основе цветовой шкалы, используйте GradientValue.

Например:

{
  "gradient": "linear",
  "stops": [
    {"offset": 0.0, "color": "red"},
    {"offset": 0.5, "color": "white"},
    {"offset": 1.0, "color": "blue"}
  ]
}

# Линейный градиент

Линейный градиент интерполирует цвета вдоль линии от начальной до конечной точки. По умолчанию он идёт горизонтально слева направо. Направление задаётся свойствами x1, y1, x2 и y2. Все координаты определяются в нормализованной системе [0, 1] относительно ограничивающей рамки окрашиваемого элемента.

# Радиальный градиент

Радиальный градиент интерполирует цвета между двумя окружностями: от границы внутренней до границы внешней. По умолчанию он идёт от центра системы координат (внутренняя окружность нулевого радиуса) к внешней окружности радиуса 0,5. Центры окружностей задаются свойствами x1, y1, x2 и y2, а радиусы — свойствами r1 и r2. Все координаты определяются в нормализованной системе [0, 1] относительно ограничивающей рамки окрашиваемого элемента. Значение 1 соответствует большему из размеров рамки — ширине или высоте.

# Цветовая точка градиента

Цветовая точка градиента состоит из значения Color и доли offset, задающей её положение.

# Number

Принимает числа, например 1, 3.14 и 1e5.

# Object

Принимает литеральные объекты, например {"left":5, "right":30, "top":5, "bottom":50}. Допустимые имена и типы свойств зависят от конкретного параметра; подробности приведены в его описании.

# String

Принимает строки, например "bold", "step-before" и "".

# URL

Принимает корректную строку URL, указывающую на внешний сайт или ресурс, например "data/stocks.csv", "images/logo.png" или "https://vega.github.io/".

Вернуться к началу

Типы данных и сигналов

# Data

Принимает строку с именем набора данных, например "table" или "nodes".

Вернуться к началу

# Field

Принимает строку с именем поля данных, например "amount", "source.x" или "target['x']".

Вместо строки можно передать объект со строковым свойством field, например {"field": "amount"} или {"field": "source.x"}. Свойство as позволяет задать другое имя выходного поля: {"field": "inputName", "as": "outputName"}.

Корректные пути доступа к свойствам объекта JavaScript с точечной (.) или скобочной (foo['bar']) записью преобразуются в обращения к вложенным объектам. Если точка входит в само имя поля и не обозначает вложенное свойство, экранируйте её ("my\\.field") или заключите имя поля в квадратные скобки ("[my.field]").

Вернуться к началу

# Signal

Принимает объект со ссылкой на значение сигнала или выражение. Свойство signal должно содержать строку с корректным именем сигнала либо строку выражения, вычисляющего значение. Например: {"signal": "width"} или {"signal": "width / 2"}.

Вернуться к началу

# Compare

Принимает объект, задающий правило сравнения для сортировки. У него могут быть два свойства: field указывает поля данных, по которым выполняется сортировка, а order — нужный порядок для каждого поля. Каждое свойство принимает строку (сортировка по одному полю) или массив строк (по нескольким полям).

Свойство order необязательно. Его значения — "ascending" (по возрастанию) или "descending" (по убыванию). Если order не задано либо в нём меньше элементов, чем в field, для оставшихся полей по умолчанию применяется сортировка по возрастанию.

Правило сравнения по одному полю:

{"field": "amount", "order": "ascending"}

Правило сравнения по нескольким полям:

{
  "field": ["amount", "date"],
  "order": ["descending", "ascending"]
}

Правило сравнения нельзя целиком задать одним экземпляром сигнала. Однако свойства field и order по отдельности могут использовать сигналы:

{
  "field": {"signal": "sortField"},
  "order": {"signal": "sortOrder"}
}

Если поле сортировки равно null, оно и соответствующее значение порядка игнорируются, словно такого элемента нет.

Вернуться к началу

# Expr

Принимает объект с выражением, применяемым к каждому объекту данных. У некоторых преобразований, например wordcloud, есть параметры, которые принимают постоянную строку или число либо вычисляют значение отдельно для каждой записи.

Значения этого типа задаются двумя способами: ссылкой field или ссылкой expr.

Ссылка field находит значение поля так же, как параметр типа Field:

{
  "type": "wordcloud",
  ...
  "rotate": {"field": "angle"} // поиск поля "angle" для каждой записи
}

Ссылка expr содержит строку выражения, вычисляемого один раз для каждой записи:

{
  "type": "wordcloud",
  ...
  "rotate": {"expr": "datum.minAngle + round(90*random() - 45)"} // вычислить для каждой записи
}

В отличие от ссылок на сигналы, вычисляемых один раз для параметра, ссылки expr работают как анонимные (лямбда-) функции и вычисляются отдельно для каждого объекта данных. И сигналы, и выражения expr пересчитываются при изменении предшествующей зависимости.

Ссылки field и expr могут содержать свойство as, задающее имя выходного поля.

Вернуться к началу

# Value

Принимает объект со ссылкой на значение, обычно применяемой для визуального кодирования. Такая ссылка состоит из базового значения, необязательного преобразования шкалой и модификаторов.

Базовое значение

Базовое значение задаётся одним из следующих свойств:

Свойства перечислены в порядке приоритета. Например, если задано signal, свойства color, field и value игнорируются. Для некоторых значений scale базовое значение можно не задавать; его также можно опустить для представления null.

Преобразования шкалой

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

Модификаторы значения

После преобразования шкалой результат можно дополнительно изменить следующими свойствами. Общая формула ссылки на значение: pow(scale(baseValue), exponent) * mult + offset. Модификаторы предназначены только для числовых значений.

Примеры

• {"value": 5} — постоянное значение 5.
• {"field": "price"} — значение поля price текущей записи.
• {"field": "index", "mult": 20} — значение поля index текущей записи, умноженное на 20.
• {"scale": "x", "value": 0} — результат преобразования значения 0 шкалой x.
• {"scale": "y", "field": "price"} — результат преобразования поля price текущей записи шкалой y.
• {"scale": "x", "band": 1} — ширина интервала шкалы x. Шкала должна иметь тип band.
• {"scale": "x", "band": 1, "offset": -1} — ширина интервала шкалы x, уменьшенная на один пиксель.

Вернуться к началу

# ColorValue

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

Обычно цвет задаётся одним значением RGB. Но иногда нужно обратиться к отдельным каналам или использовать другое цветовое пространство. В следующем примере красный и синий каналы RGB заданы константами, а зелёный определяется преобразованием шкалой.

{
  "fill": {
    "color": {
      "r": {"value": 255},
      "g": {"scale": "green", "field": "g"},
      "b": {"value": 0}
    }
  }
}

Vega поддерживает следующие цветовые пространства:

Вернуться к началу

# FieldValue

Принимает строку или объект, указывающий поле данных. Если передана строка, она используется как имя поля. Для объекта доступны следующие свойства:

Эти свойства можно вкладывать друг в друга для косвенного поиска полей. Например, {"parent": {"datum": "f"}} сначала получит значение поля f текущего объекта данных примитива. Затем это значение будет использовано как имя свойства в объекте данных охватывающего группового примитива.

Кроме того, ссылки group и parent могут содержать необязательное свойство level для обращения к группам более высокого уровня. Например, {"parent": "f", "level": 2} использует значение поля f из данных группы на два уровня выше. По умолчанию level = 1, то есть непосредственная родительская группа.

Вернуться к началу

# GradientValue

Определяет линейный градиент на основе диапазона шкалы для каналов кодирования fill и stroke. Чтобы задать градиент напрямую, без ссылки на шкалу, укажите определение Gradient в свойстве value кодирования.

Пример

{
  "encode": {
    "fill": {
      "gradient": "colorScale",
      "start": [0, 1],
      "stop": [0, 0],
      "count": 10
    }
  }
}

Вернуться к началу

# TimeMultiFormat

Объект, задающий собственные форматы для значений даты и времени разной точности. Он должен подходить для передачи методу API timeFormat:

• Ключи объекта должны быть допустимыми единицами времени, например year или month.
• Значения объекта должны быть допустимыми строками формата d3-time-format.

Эти значения вместе с форматами по умолчанию для неуказанных единиц создают функцию динамического форматирования. Она выбирает формат в зависимости от точности входной даты: например, от того, совпадает ли дата с началом года, месяца, дня или часа. Подробнее см. документацию API timeFormat.

Вернуться к началу