Параметры и интерактивное поведение

// Спецификация отдельного представления
{
  ...,
  "params": [  // Массив именованных параметров
    {"name": ..., ...}
  ],
  "mark": ...,
  "encoding": ...,
  ...
}

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

Содержание страницы

• Определение параметра
  • Переменные параметры
    • Выражение expr
    • Встроенные и зарезервированные имена
  • Параметры выделения
• Использование параметров
  • В строках выражений
  • Как предикаты
  • Области значений данных
• Настройка выделений по умолчанию

Определение параметра

И переменные, и выделения поддерживают следующие свойства:

Переменные параметры

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

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

Выражение expr

Помимо задания начального value, параметр можно создать с помощью выражения (expr).

В этой диаграмме ширина внутренних полос зависит от высоты представления:

height — встроенный параметр. Другие встроенные имена перечислены ниже.

Встроенные и зарезервированные имена

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

Параметры выделения

Выделение превращает действия пользователя — например щелчок или перетаскивание — в запрос к данным. Параметр становится выделением, когда у него есть свойство select. Оно определяет тип выделения и его поведение.

Попробуйте оба типа на примере выделения с именем pts ниже:

Тип выделения: точечное — point интервальное — interval

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

Использование параметров

В строках выражений

В выражении к параметру обращаются непосредственно по имени. Имя выделения обозначает объект со свойствами, соответствующими полям данных, участвующим в нём. Эти поля задаются свойствами encodings или fields.

Здесь прозрачность точек определяется привязанной переменной, а размер — значением Miles_per_Gallon выбранной щелчком точки:

Как предикаты

Предикат возвращает true или false. Его можно записать выражением, например opacityVar == 25 или sel.Miles_per_Gallon > 75, но зачастую удобнее использовать сам параметр.

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

В следующем примере переменная меняет цвет точек, а выделение увеличивает их при наведении. Переключатель меняет свойство empty: при false пустому выделению не соответствует ни одна точка.

Пустое выделение: true — все точки (по умолчанию) false — ни одной точки

Подробнее об этом приёме — на странице «Условное кодирование».

Параметр можно использовать и для фильтрации одного представления с помощью другого. Ниже интервальное выделение brush задаётся на верхней диаграмме, а нижняя диаграмма рассеяния «Ускорение × Рабочий объём» (Acceleration × Displacement) показывает только точки, попавшие в выбранную область:

Области значений данных

Интервальное выделение может управлять границами интервалов группировки или областью значений шкалы. Оба приёма показаны на диаграммах «обзор и детали».

В первом примере область на нижнем графике изменяет интервалы группировки данных на верхнем и тем самым приближает выбранный диапазон:

Во втором примере выделение brush на нижнем графике меняет область значений шкалы x верхнего:

Похожий результат можно получить предварительной фильтрацией данных:

{
  "vconcat": [{
    "transform": [{"filter": {"param": "brush"}}],
    ...
  }]
}

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

Если выделение проецируется на несколько полей или каналов, в определении области значений нужно указать один из них. При проекции только на одно поле Vega-Lite определяет его автоматически. Например, для шкалы можно явно записать:

• "scale": {"domain": {"param": "brush", "encoding": "x"}}; или
• "scale": {"domain": {"param": "brush", "field": "date"}}.

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

Настройка выделений по умолчанию

// Спецификация представления верхнего уровня
{
  ...,
  "config": { // Объект конфигурации
    "selection": { ... }, // Конфигурация выделений
    ...
  }
}

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

Их можно переопределить в конкретном параметре выделения.