Легенды

Категориальные легенды

Категориальная легенда показывает список образцов, каждый из которых представляет кортеж из набора данных. У каждого образца может быть цветная форма и заголовок. Список образцов основан на списке кортежей для слота, который представляет легенда.

У легенды также может быть заголовок, как показано в примере сезона. Заголовок часто получается из элемента данных, который представляет легенда.

Непрерывные легенды

Непрерывная легенда показывает диапазон значения. Диапазон может быть выражен как диапазон размеров или цветовая гамма. Свойство слота channel позволяет их различить.

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

Как включить легенду

В общем случае, единственно, что вам нужно сделать как разработчику пакета - это предоставить Определение визуализации визуализации. В файле Vizdef.xml требуется несколько записей, позволяющих RenderBase определить, следует ли и каким образом создавать легенду. Если в Определение визуализации будут требуемые записи, RenderBase создаст правильные структуры данных и передаст их в прикладную программу хоста.

Легенды связаны с записями слота в Определение визуализации. У каждого слота в vizdef есть необязательный атрибут channel. Канал (channel) определяет тип кодировки легенды, и у его значений может быть цвет и размер. Тип цвета может использоваться как для категориальных легенд (цветных образцов), так и для непрерывных легенд (гаммы цветов). Тип размера используется только для непрерывных легенд (диапазона размеров). Если у слота один из известных типов каналов, будет выводиться легенда именно для этого слота.

<slot name="series" type="cat" channel="color" />
<slot name="values" type="cont" channel="size,color" />

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

<slots>
    <slot name="categories" type="cat" />
    <!-- Кортежи рядов (series) будут выводиться в легенде в виде образцов цвета -->
    <slot name="series" type="cat" channel="color" />

    <!-- Значения будут выводиться в легенде и как диапазон размеров, и как цветовая гамма -->
    <slot name="values" type="cont" channel="size,color" />
</slots>

<properties>
    <!-- Категориальная палитра, связанная со слотом 'series' -- >
    <palette name="series_colors" slot="series" />
    <!-- Непрерывная палитра, связанная со слотом 'values' -- >
    <palette name="values_colors" slot="values" />
</properties>

Изменение легенд

В некоторых конкретных ситуациях вы захотите изменить выводящуюся в легенде информацию. Например, можно решить, что на основе определенного условия легенда будет видимой или невидимой. У RenderBase есть метод updateLegend, переопределив который, можно задать такое поведение. Можно либо изменить созданную легенду автоматически, либо задать новую легенду.

protected updateLegend( _data: DataSet ) : Encoding[]
{
    Показать легенду только для 'heat' или 'categories', но не для того и другого.
    const filterSlot = _data.cols[ HEAT ].mapped ? "heat" : "categories";

    // Показать легенду, только соответствующую `filterSlot`.
    return super.updateLegend( _data ).filter( _e => _e.slot === filterSlot );
}

Следующий пример показывает, как задать элементы в категориальной легенде в обратном порядке и заголовок легенды в верхнем регистре:

public updateLegend( _data: DataSet ) : Encoding[]
{
    // Создать информацию легенды по умолчанию.
    const legend = super.updateLegend( _data );

    // Если легенда категориальная, изменить регистр заголовка на верхний, а порядок элементов на обратный.
    legend.forEach( _e =>
    {
        if ( _e instanceof CatEncoding )
        {
            _e.caption = _e.caption.toUpperCase();
            _e.entries.reverse();
        }
    } );
    return legend;
}

API для создания и изменения легенды требуется следующий импорт:

import { Encoding, CatEncoding, ContEncoding } from "@businessanalytics/customvis-lib";