Сигналы

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

Значения сигналов реактивны: они могут изменяться при поступлении событий ввода, вызовах внешнего API или изменении других сигналов. Потоки событий собирают и упорядочивают события ввода, например mousedown и touchmove. При возникновении события связанные с ним сигналы вычисляются заново в порядке их определения в спецификации. Затем новые значения передаются остальным частям спецификации, и визуализация автоматически перерисовывается.

Пример определения сигнала и его использования в спецификации:

{
  "signals": [
    {
      "name": "indexDate",
      "description": "Дата, которая обновляется при перемещении указателя мыши.",
      "update": "datetime(2005, 0, 1)",
      "on": [{"events": "mousemove", "update": "invert('x', x())"}]
    }
  ],
  "data": [
    { "name": "stocks", ... },
    {
      "name": "index",
      "source": "stocks",
      "transform": [
        {
          "type": "filter",
          "expr": "month(datum.date) === month(indexDate)"
        }
      ]
    }
  ],
  "scales": [
    { "name": "x", "type": "time", ... }
  ],
  "marks": [
    {
      "type": "rule",
      "encode": {
        "update": {
          "x": {"scale": "x", "signal": "indexDate"}
        }
      }
    }
  ]
}

Свойства сигнала

При определении сигнала можно использовать следующие свойства.

Встроенные сигналы

Некоторые имена сигналов обрабатываются автоматически или зарезервированы:

• Сигналы для свойств спецификации width, height, padding, autosize, а начиная с версии ≥ 5.10 и background, определяются автоматически. Их можно также определить в массиве signals верхнего уровня. В этом случае определения объединяются со значениями одноимённых свойств спецификации, причём приоритет имеют свойства из массива signals.
• Экземпляры групповых примитивов автоматически содержат сигнал parent, связанный с объектом данных группы. Определять в спецификации сигнал с именем parent нельзя.
• Имена datum, item и event зарезервированы для переменных верхнего уровня в выражениях. Определять сигналы с этими именами нельзя.
• Если определить сигнал cursor, его значение будет управлять CSS-видом указателя мыши в представлении Vega. Подробнее см. описание сигнала cursor ниже.

Сигнал cursor

По умолчанию Vega меняет вид указателя мыши, когда он находится над примитивом со свойством cursor. Но при некоторых взаимодействиях курсор должен сохранять свой вид до их завершения: например, во время перетаскивания, даже если указатель ушёл с исходного примитива. Для этого служит отдельный сигнал cursor. Если ему задано значение, Vega использует его вместо свойств cursor отдельных примитивов. Значение "default" возвращает управление курсором свойствам примитивов.

Вложенные сигналы

Сигналы можно определять на верхнем уровне спецификации или внутри группового примитива. Сигнал, определённый во вложенной группе, доступен только в её области видимости: все примитивы, оси, легенды и другие элементы, которые на него ссылаются, должны находиться внутри этой группы. Если имя вложенного сигнала совпадает с именем сигнала во внешней области видимости, вложенное определение переопределяет внешнее.

Помимо новых определений, вложенный групповой примитив может содержать обновления сигналов из внешней области видимости. Свойство "push": "outer" означает, что обновление относится к уже существующему сигналу, а не создаёт новый. Во вложенном обновлении сигнала нельзя использовать свойства value и update. Доступны следующие свойства:

Обработчики событий

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

Этот сигнал увеличивает своё значение при событии mouseover на элементах rect:

{
  "name": "count",
  "value": 0,
  "on": [
    {"events": "rect:mouseover", "update": "count + 1"}
  ]
}

Этот сигнал применяет специальные наборы свойств кодирования при событиях mousedown и mouseup на элементах примитивов. Определение примитива должно содержать наборы "select" и "release" в свойстве "encode".

{
  "name": "clickEncode",
  "on": [
    {"events": "*:mousedown", "encode": "select"},
    {"events": "*:mouseup", "encode": "release"}
  ]
}

Привязка к элементу ввода

Свойство bind привязывает сигнал к элементу ввода вне визуализации. Vega создаёт элементы HTML-формы и устанавливает двустороннюю связь: изменение элемента обновляет сигнал, а изменение сигнала — элемент. Предусмотрена поддержка типов checkbox (флажок с логическим значением), radio (группа переключателей), select (раскрывающийся список) и range (ползунок). Сигнал также можно привязать к существующему внешнему элементу.

Свойства элементов radio и select

Свойства элемента range

Другие типы элементов ввода

Свойству input можно присвоить любой допустимый тип элемента ввода HTML, например "text" (однострочное текстовое поле), "color" (выбор цвета) или "date" (ввод года, месяца и дня). В этих случаях дополнительные свойства, например placeholder для "text", добавляются как атрибуты создаваемого элемента HTML-формы.

Прямая привязка к внешним элементам

Вместо создания нового элемента ввода Vega может привязать сигнал к уже существующему внешнему элементу. Для этого свойство input не задаётся, а свойство element ссылается на существующий элемент.