可视化定义

VizDef 是一个 XML 文件，包含要构建的可视化的定义。

托管应用程序可以从 VizDef 文件中了解到有关可视化的一些信息，例如数据的组织方式和可视化的属性。

创建的每个自定义可视化都必须在根目录中有一个 vizdef.xml 文件。 如果使用 customvis start 创建新的可视化，那么会创建初始 vizdef.xml。

槽

槽定义可视化中可保存数据的各方面。 例如，在条形图可视化中，您可能有两个槽，一个用于分类元组，一个用于值。 槽必须至少具有 name（用于内部引用）和 type（分类或连续）。 典型的槽定义可能如下所示：

<slots>
    <slot name="categories" caption="Categories" type="cat" optional="false" />
    <slot name="values" caption="Values" type="cont" optional="false" />
    <slot name="series" caption="Color" type="cat" optional="true" channel="color" />
</slots>

name 和 type 特性是必需的，用于保存槽的内部名称和类型。

caption 特性包含可在应用程序 UI 中使用的名称。 在此处可以指定文字串或对本地化字符串的引用，例如 $nls.categories。 有关更多信息，请参阅 本地化。

optional 特性指示可视化是否能够在没有任何数据映射到该槽的情况下呈现任何有意义的内容。 例如，在先前的示例中，series 槽标记为 optional。 这意味着如果用户未将数据映射到此槽，那么可视化将仅呈现一个默认序列。

最后，channel 特性指示托管应用程序可以使用特定编码来表示该槽的图例。 channel 的可能值为 color 和 size。 有关更多信息，请参阅 图注。

DataSets

数据集定义用于构成数据边缘的槽的集合。 目前，RenderBase 仅支持一个数据集，因此 VizDef.xml 中的典型 DataSets 条目如下所示：

<dataSets>
    <dataSet name="data">
        <ref slot="categories" />
        <ref slot="series" />
        <ref slot="values" />
    </dataSet>
</dataSets>

在槽部分中定义的每个槽都必须在数据集中列出。

属性

可视化可以公开属性，以允许可视化用户控制可视化行为的各个方面。 每个属性至少通过名称和类型进行定义。 根据属性类型，可以应用其他特性。 可视化可以将属性组织成逻辑组。 这取决于主机应用程序是否要在 UI 中显示属性分组。 示例：

<properties>
    <group name="general">
        <!-- Boolean property with default value = true -->
        <boolean name="labels.visible" defaultValue="true" />
        <!-- Positive numeric value; allow null to indicate 'automatic' tick count -->
        <number name="ticks.count" minValue="0" allowNull="true" />
        <!-- String property; allow null to indicate 'automatic' title -->
        <string name="title.text" allowNull="true" />
        <!-- Font property; host receives a Font structure to change individual font aspects -->
        <font name="title.font" defaultValue="10px arial" />
    </group>
</properties>
注: 使用 allowNull 需要可视化代码才能正确处理 null案例。 设置此标志表示 null 将成为属性的有效值。 如果 allowNull 为 false，那么可视化可以假定属性值绝不会为 null，并且无需在代码中进行有效性检查。

以下特性可应用于属性：

  • name：属性的名称。 用于在呈现服务代码中引用属性。
  • caption：在属性的 UI 中显示的标签。 可以是文字串，也可以是本地化标识（前缀为 $nls. 的字符串）。
  • defaultValue：属性在初始化时获取的默认值。 如果未指定 defaultValue 并且 allowNull 为 true，那么默认值将为 null。
  • allowNull：指示是否允许主机应用程序设置 null 值的标志。 通常用于指示自动值。 例如，刻度的值。
  • minValue：仅适用于 number 属性，用于定义允许的最小值。
  • maxValue：仅适用于 number 属性，用于定义允许的最大值。
  • slot：仅适用于 palette 属性，用于将调色板链接到槽。 调色板类型和槽类型必须匹配。 如果省略调色板类型，那么将采用槽类型。
  • type：仅适用于 palette 属性，用于定义调色板的类型：cat 或 cont。

以下属性类型可用：

  • string：保存文本值。
  • number：保存数字值。 可以选择通过 minValue 和 maxValue 特性指定最小值和最大值。
  • boolean：保存布尔值。
  • enum：保存值的静态列表，可视化的用户可以从中选择一个值。 可以在 <possibleValue> 元素中指定可能值的列表。 请参阅下面的示例代码。
  • color：保存颜色值。 颜色的 defaultValue 可以是颜色的级联样式表 (css) 表示，包括命名的颜色（“red”、“green”）。
  • font：保存 CSS 字体定义。
  • palette：保存调色板引用。 调色板通过名称和可能的 defaultValue 进行定义。 如果未指定 defaultValue，那么会分配内置调色板。 调色板的默认值通过分号分隔的颜色列表进行定义。
<!-- font property example -->
<font name="axis.title" defaultValue="bold 16px Arial" />

<!-- enum property example -->
<enum name="shape" caption="Shape">
    <possibleValue caption="Circle">circle</possibleValue>
    <possibleValue caption="Square">square</possibleValue>
</enum>

<!-- palette property example -->
<palette name="color" type="cat" defaultValue="red;green;blue" />
<palette name="range" type="cont" defaultValue="red 0%;green 50%;blue 100%" />

功能

如果可视化必须能够响应突出显示和选择，请在 vizdef.xml 文件中指定以下部分：

<capabilities>
    <decorations>
        <decoration name="selected" type="boolean" target="datapoint" />
        <decoration name="hasSelection" type="boolean" target="dataset" />
        <decoration name="highlighted" type="boolean" target="datapoint" />
    </decorations>
</capabilities>

此部分向主机应用程序告知可以选择和突出显示数据点。 如果您不希望可视化使用对实现突出显示和选择的内置支持，那么可以选择在 vizdef.xml 文件中不包含此部分。

本地化

vizdef.xml 文件保存主机应用程序可用于呈现用户界面的信息。 例如，vizdef.xml 文件会保存可视化公开的所有属性，主机应用程序可以读取这些属性并将它们显示在属性面板的末尾。

为了允许对属性名称和描述本地化，引入了一种特殊表示法，可将特性值映射到资源表的索引。 例如，请查看以下属性定义：

<boolean name="labels.visible" caption="$nls.labels.visible" defaultValue="true" />

文字说明是面向用户的，可以进行本地化。 不要对此特性中的值进行硬编码，请使用标识：$nls.labels.visible。 然后，使用资源表来查找此标识，并找到正确语言版本的实际文字说明。

包含这些本地化字符串的资源表的格式是根据 requirejs i18n.js 插件进行设置的。 要确保 customvis 能够正确找到并处理本地化字符串，您的文件和文件夹结构必须类似于以下示例：

./nls/de/Resources.js
./nls/nl/Resources.js
./nls/Resources.js

此示例的 ./nls 中包含基本（或根）语言，./nls/de 和 ./nls/nl 中包含德语和荷兰语翻译版本。 根 Resources.js 文件如下所示：

define(
{
    "root":
    {
        "labels.visible" : "Show Labels",
        "labels.font"    : "Label Font"
    },
    "nl": true,
    "de": true
} );

每个特定于语言的文件都具有以下内容：

define(
{
    "labels.visible" : "Toon Labels",
    "labels.font"    : "Label Lettertype"
} );

在此找到的资源条目不限于在 VizDef 中使用的字符串。 您还可以包含在呈现代码中使用的条目。 有关更多信息，请参阅 本地化。

有关 REQUIREJS API 的更多信息，请参阅 requirejs 文档。