第 4 部分：高级功能

步骤 1：可选槽

在 部件 1 中: 创建定制可视化 ，您在 vizdef.xml 文件中添加了条目以定义可视化的槽。 通过将 optional 特性设置为 false，所有槽都会标记为必需。 这表示用户必须在所有槽中提供数据后，可视化才能呈现数据。

在此步骤中，将添加可选的 color 槽。 槽类型为连续，这表示用户可以将数字数据映射到槽。 如果映射了槽，那么该槽中的值将确定点的颜色。 如果未映射槽，那么散点图使用 color 调色板的工作方式与现在一样。

下面是需要的 vizdef.xml 文件更改。 请注意，在 slots 部分（第 3 行）和 dataSet 部分（第 9 行）中都需要进行更改。

1
2
3
4
5
6
7
8
9
10
11

<slots>
    ...
    <slot name="color" type="cont" optional="true" channel="color" />
</slots>

<dataSets>
    <dataSet>
        ...
        <ref slot="color" />
    </dataSet>
</dataSets>

除了添加槽外，还需要添加将在新槽映射到数据时使用的连续调色板：

1
2
3
4
5

<properties>
    <group name="general">
        <palette name="color_cat" slot="categories" />
        <palette name="color_cont" slot="color" />
        ...

请参阅第 3 行和第 4 行。 请注意，您已将现有属性 "color" 重命名为 "color_cat" ，以更清楚地区分这两个调色板属性。

在 Main.ts 文件中，添加一个用于识别颜色槽的常量：

const CAT = 0, XPOS = 1, YPOS = 2, COLOR = 3; // slot indices

最后修改 Main.ts 文件中的代码，以从新槽中选取颜色和数据：

1
2
3
4
5

<// Determine color palette and shape from the properties.
const hasColor = data.cols[ COLOR ].mapped;
const palette = props.get( hasColor ? "color_cont" : "color_cat" );
const shape = d3.symbol().size( 256 );
...

在第 3 行上，可以看到根据列的 mapped 状态，会检索连续或分类调色板以用于确定颜色。

现在，自定义可视化的用户只需执行这些操作，就能将数据映射到新槽。 这些数据将确定散点的颜色。 如果没有数据，那么将根据分类槽来确定颜色。

步骤 2：自定义图例

完成上一步并对其进行测试后，您可能已经注意到，如果已有数据映射到新的“color”槽，那么仍会显示分类图例。 这是因为“categories”槽和“color”槽都具有“color”通道，并且这两个通道都已映射。 自动图例算法无法确定实际使用的是两个调色板中的哪一个。

要覆盖自动图例的行为，可以覆盖 updateLegend 函数。 在此函数中，可以添加、移除或修改单个图例和图例项。

首先，请如下所示更新“imports”部分：

import { RenderBase, UpdateInfo } from "@businessanalytics/customvis-lib";
import { Encoding, DataSet } from "@businessanalytics/customvis-lib";
import * as d3 from "d3";

然后，向可视化类添加 updateLegend 方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

protected updateLegend( _data: DataSet ): Encoding[]
{
    // Call base class implementation to setup initial encodings.
    const encodings = super.updateLegend( _data );
    const hasColor = _data.cols[ COLOR ].mapped;

    // Filter encodings: if color slot is mapped, skip categorical legend.
    return encodings.filter( _encoding =>
    {
        if ( hasColor && _encoding.type === "cat" )
            return false;
        return true;
    } );
}

RenderBase.updateLegend 实现会创建一个数组，用于保存图例编码（第 4 行）。 此数组可保存绘制图例所需的所有信息。 通过覆盖 updateLegend，您能够对在 RenderBase 中创建的编码进行更改。 在第 8 行中调用的 filter 函数将返回满足函数主体中所定义条件的编码。

步骤 3：本地化

在 Part 3: 定制图注和属性 中，您向 vizdef.xml 文件添加了文字说明，因此用户界面显示了属性和槽的正确标签。 在此步骤中，您将看到如何将这些文字说明本地化，以便它们适应您在 IBM® Cognos Analytics中选择的 UI 语言。

要使可视化支持已翻译的字符串，请在可视化所在的根目录中添加名为 nls 的新目录（作为 vizdef.xml 文件的同代）。 然后，在此 nls 目录中添加文件 Resources.js，其中包含以下内容：

define(
{
    "root": {
        "prop_color_cat":       "Point Color",
        "prop_color_cont":      "Color Range",
        "prop_shape":           "Shape",
        "prop_shape_circle":    "Circle",
        "prop_shape_square":    "Square",
        "prop_background":      "Background",
        "prop_show_background": "Show Background",
        "prop_xmax":            "X-axis max",
        "prop_ymax":            "Y-axis max",
        "prop_axis":            "Axis"
    },

    "nl": true
} );

最后一个条目 "nl": true 指示在 nl 子文件夹中有此文件的荷兰语版本。 因此，请在 nls 文件夹中创建子文件夹 nl。 然后，在此 nl 子文件夹中添加另一个 Resources.js 文件，其中包含以下内容：

define(
{
    "prop_color_cat":       "Puntkleur",
    "prop_color_cont":      "Kleurbereik",
    "prop_shape":           "Vorm",
    "prop_shape_circle":    "Cirkel",
    "prop_shape_square":    "Vierkant",
    "prop_background":      "Achtergrond",
    "prop_show_background": "Toon Achtergrond",
    "prop_xmax":            "X-as max",
    "prop_ymax":            "Y-as max",
    "prop_axis":            "As"
} );

现在，您的文件和目录结构应该如下所示:

最后，将 vizdef.xml 文件中的硬编码文字说明替换为刚才在 nls 文件中定义的变量 (以 $nls.为前缀):

<properties>
    <group name="general">
        <palette name="color_cat" caption="$nls.prop_color_cat" slot="categories" />
        <palette name="color_cont" caption="$nls.prop_color_cont" slot="color" />
        <enum name="pointShape" caption="$nls.prop_shape" defaultValue="circle">
            <possibleValue caption="$nls.prop_shape_circle">circle</possibleValue>
            <possibleValue caption="$nls.prop_shape_square">square</possibleValue>
        </enum>
        <string name="background" caption="$nls.prop_background" defaultValue="" />
        <boolean name="showBackground" caption="$nls.prop_show_background" defaultValue="true" />
    </group>
    <group name="axis" caption="$nls.prop_axis">
        <number name="xmax" caption="$nls.prop_xmax" allowNull="true" />
        <number name="ymax" caption="$nls.prop_ymax" allowNull="true" />
    </group>
</properties>

步骤 4：运行和测试可视化

在 Cognos Analytics 中创建新的仪表板或报告，并添加 "预览可视化"。 添加一些数据后，应该会在操作中看到散点图可视化。 添加一些数据后，应该会在操作中看到散点图可视化。 请尝试将数据添加到“color”槽，然后再次将其移除。 您将会注意到针对可视化显示的图例中的差异。