第 1 部分：创建自定义可视化

在这第一部分中，您将使用某个内置模板来创建新的可视化并添加数据定义。 您还将提供初始实现，为提供的数据中的每一行呈现 X 轴、Y 轴和散点。 在此部分结束时，您将获得（非常基本的）散点图可视化的正常运作的示样。

开始之前

确保已设置开发环境并安装定制可视化 CLI 工具，如 设置开发环境中所述。

步骤 1：创建可视化

打开命令终端，浏览至在其中创建可视化的目录，然后通过运行以下命令来创建新的可视化：

折线图 代码 
1
2
3

customvis create MyScatter
cd MyScatter
customvis start
 
customvis create MyScatter
cd MyScatter
customvis start
第一个命令会在名为 MyScatter 的新目录中创建模板可视化。 第二个命令会将您转至创建以下文件的目录：
  • package.json

    在此处可以更改 IBM Cognos Analytics 中显示的捆绑软件的名称和图标。

        "meta": {
        "name": "Fred",
        "icon": "bundle.svg"

    名称和图标已填写，但是您可以选择其他名称或其他图标文件格式（.png 或 .jpg）。

  • vizdef.xml

    可视化定义 文件，描述可视化的各个方面，例如槽，数据组织和外部属性。 在步骤 2 中，将编辑此文件，并为新可视化添加槽和属性。

  • externals.d.ts

    如果可视化需要引用外部库，那么可以在此处添加这些库。 但是，在此示例中，您无需对此文件进行更改。

  • customvis-lib.tgz

    此文件包含将用于开发可视化的 API ，包括名为 RenderBase 的基类，您将从中派生可视化类。

  • renderer/Main.ts

    主实现文件。 .ts 扩展名指示这是 typescript 文件。 在步骤 3 中，将开始在此文件中添加一些代码。

第三个也是最后一个命令启动可视化，并使其在 IBM Cognos Analytics中可用。 可视化还没有太多功能，因此在接下来的步骤中，您将开始对 vizdef.xml 文件和 Main.ts 文件进行更改并添加一些功能。 您所做的所有更改都将由 CLI 工具持续选取并编译成正常运作的可视化。 有关更多信息，请参阅步骤 4。

注: 运行 customvis start 后，您将看到创建了一些额外的文件和文件夹。 这是运行可视化所需的构建输出。 如果要重新从干净的文件夹开始，请运行 customvis clean。 这将移除这些生成的文件。

步骤 2：编辑 vizdef.xml

可视化的两个最重要的文件是 vizdef.xml 和 Main.ts。 在此步骤中，我们将重点关注 可视化定义。 vizdef 是可视化特征的正式 XML 定义。 此定义可由主机应用程序用于执行多种操作，例如创建用于管理属性的用户界面，实现突出显示和选择，以及执行高效数据查询。

首先请在文本编辑器中编辑已创建的 vizdef.xml。 您将看到以下内容：


<?xml version="1.0" encoding="UTF-8"?>
<visualizationDefinition version="3.1" xmlns="http://www.ibm.com/xmlns/prod/ba/vipr/vizBundle/vizdef.3">
</visualizationDefinition>

对于散点图可视化，需要添加槽、数据集和功能。

槽和数据集

首先要添加的内容是用于定义可视化中使用的数据的槽和数据集。 散点图可视化将有三个槽：
  • 分类槽，用于保存将要绘制的每个点的元组。
  • 连续槽，用于保存点的 X 轴位置的值。
  • 连续槽，用于保存点的 Y 轴位置的值。
有关槽和数据集的更多信息，请参阅 数据模型。

在此示例中，所有槽都被视为是必需的。 如果没有用于任何槽的数据，那么不会呈现可视化。 考虑到这些需求，请编辑 vizdef.xml，使其如下所示：

折线图 代码 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
<?xml version="1.0" encoding="UTF-8"?>
<visualizationDefinition version="3.1" xmlns="http://www.ibm.com/xmlns/prod/ba/vipr/vizBundle/vizdef.3">
    <slots>
        <slot name="categories" type="cat" optional="false" channel="color" />
        <slot name="xpos" type="cont" optional="false" />
        <slot name="ypos" type="cont" optional="false" />
    </slots>

    <dataSets>
        <dataSet>
            <ref slot="categories" />
            <ref slot="xpos" />
            <ref slot="ypos" />
        </dataSet>
    </dataSets>
</visualizationDefinition>

请务必添加引用每个槽的单个 dataSet 条目。

需要第 4 行上的类别槽中的 channel="color" 属性，才能根据该槽的数据绘制基于 Cognos Analytics 产品的图注。 请参阅 图注 以获取更多信息。

属性

可视化可以公开公共属性，这些属性允许作者在 Cognos Analytics 中修改可视化的外观。 您可以考虑字体属性，颜色，页边距等。 现在，您将仅添加一个属性: 调色板。

可视化可以使用调色板来确定用于数据元素的颜色。 对于散点图可视化，我们希望为每个呈现的圆圈显示不同的颜色。 下面是 vizdef 中需要的 XML：

    ...
    <properties>
        <palette name="color" slot="categories" />
    </properties>
</visualizationDefinition>

选择和突出显示功能

如果您希望可视化数据元素指示选择和突出显示，那么需要向 vizdef 添加一些功能。 这些功能可确保主机应用程序提供有关数据中元素的突出显示和选择状态的信息：


    ...
     <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>
</visualizationDefinition>

target 字段指示我们只关注数据点装饰。 在其他可视化中，您可能除了指定 datapoint 外，还要指定 tuple（以逗号分隔）。 但现在我们仍将使用上面显示的定义。 可以在 数据模型 文档中找到有关元组和数据点的更多信息。

步骤 3：在 Main.ts 中开始编码

既然 vizdef.xml 文件已准备就绪，接下来就可以开始对可视化的行为进行编码。 首先，打开 renderer 目录中的 Main.ts 文件。 文件如下所示：

import { RenderBase } from "@businessanalytics/customvis-lib";

export default class extends RenderBase
{
    protected create( _node: HTMLElement ): HTMLElement
    {
        _node.textContent = "Basic VizBundle";
        return _node;
    }
}

接下来，您将了解如何添加 d3 引用，如何执行可视化的初始设置，以及如何处理更新。

引用 d3

由于可视化将基于 d3，因此需要导入 d3 类型。 此外，还将处理呈现更新，因此还需要 UpdateInfo。 最后，可定义稍后引用槽时非常有用的若干常量：

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

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

执行初始化

在创建可视化期间，每个可视化都有会调用一次的 create 方法。 在此可以添加用于执行初始设置的代码，下面我们来创建将用于在其中呈现内容的 svg 画布。 更改现有 create 函数，如下所示：

protected create( _node: HTMLElement ): Element
{
    // Create an svg canvas that sizes to its parent.
    const svg = d3.select( _node ).append( "svg" )
        .attr( "width", "100%" )
        .attr( "height", "100%" );

    // Create groups for axes and elements.
    const chart = svg.append( "g" ).attr( "class", "chart" );
    chart.append( "g" ).attr( "class", "xaxis data" );
    chart.append( "g" ).attr( "class", "yaxis data" );
    chart.append( "g" ).attr( "class", "elem data" );

    // Return the svg node as the visualization root node.
    return svg.node();
}
注: create 函数的返回值已从 HTMLElement 更改为 Element!

create 函数具有一个参数：_node。 这是一个 HTML 元素，也是可视化的容器元素。 您可以直接在此节点上或在此节点的子节点上呈现所有内容。

最后一个命令 return svg.node(); 使 svg 节点成为可视化的根节点。 根节点将传递到 update 函数，此函数将在下一步中实现。

处理更新

大部分呈现在 update 函数中完成。 将调用此函数以防出现以下情况：

  • 新数据到达。
  • 属性值已更改。
  • 可视化大小已更改。
  • 选择或突出显示已更改。

下面是 update 的完整代码。 您可以将其粘贴到刚才修改的 create 函数正后方。 大部分代码都与 d3 相关。 详细说明如下。

折线图 代码 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
protected update( _info: UpdateInfo ): void
{
    // Get data, properties and svg node.
    const data = _info.data;
    const props = _info.props;
    const svg = d3.select( _info.node );

    // If there is no data, remove all axes and elements.
    if ( !data )
    {
        svg.selectAll( ".data>*" ).remove(); // remove children of '.data' elements
        return;
    }

    const margin = 20; // use a 20-pixel margin
    const xHeight = 20; // assume an x-axis height of 20px.

    // 创建 Y 轴。
    const yHeight = _info.node.clientHeight - 2 * margin - xHeight;
    const yDomain = data.cols[ YPOS ].domain.asArray(); // [min, max]
    const yScale = d3.scaleLinear().range( [ yHeight, 0 ] ).domain( yDomain ).nice();
    const yAxis = svg.select<SVGGElement>( ".yaxis" ).call( d3.axisLeft( yScale ) );
    const yWidth = yAxis.node().getBBox().width;

    // Create the x-axis and position at bottom of y-axis.
    const xWidth = _info.node.clientWidth - yWidth - 2 * margin;
    const xDomain = data.cols[ XPOS ].domain.asArray(); // [min, max]
    const xScale = d3.scaleLinear().range( [ 0, xWidth ] ).domain( xDomain ).nice();
    const xAxis = svg.select( ".xaxis" ).call( d3.axisBottom( xScale ) );
    xAxis.attr( "transform", `translate(0,${yHeight})` );

    // Position the chart (axes and elements).
    svg.select( ".chart" ).attr( "transform", `translate(${yWidth+margin},${margin})` );

    // Determine color palette from the properties and create a Circle shape.
    const palette = props.get( "color" );
    const shape = d3.symbol().size( 256 ).type( d3.symbolCircle );

    // For every row in the data, create and position a circle element.
    svg.select( ".elem" )
        .selectAll( "path" )
        .data( data.rows, ( row: any ) => row.key )
        .join( "path" )
            .attr( "d", shape )
            .attr( "transform", row => `translate(${xScale(row.value(XPOS))},${yScale(row.value(YPOS))})` )
            .attr( "stroke-width", 3 )
            .attr( "stroke", row => palette.getOutlineColor( row ) )
            .attr( "fill", row => palette.getFillColor( row ) );
}

第 9-13 行：处理没有数据时的情况。 这意味着 _info.data 为 null，并且唯一要执行的操作是从屏幕中移除三个 g 组中任一组的所有元素。

第 15-16 行：为边距、轴高度和列索引定义若干常量。 这些常量用于后续代码的可读性。

第 19-30 行：创建 Y 轴和 X 轴。 对于轴，需要具有 scale，scale 基于数据值域（最小值和最大值）和范围（以像素为单位）。 添加到轴的 transform 特性用于确保轴正确定位。

第 36 行 确定您在步骤 2 中定义的选用板。 您将需要第 48 和 49 行中的此调色板来确定所呈现的圆圈的填充和轮廓颜色。

第 40-48 行：对散点图执行创建、更新和移除点的操作。 d3 数据基于 data.rows。 key 函数确保为每个符号分配唯一标识。 请注意，在第 47 行和第 48 行上使用调色板。 您可以在选用板中查询给定数据点 d的特定颜色。 实际上，这两条线使可视化中的圆圈响应于突出显示 (鼠标悬停) 和选择 (鼠标单击)。 每个圆圈的实际定位在第 43 行上使用 translate 变换来执行。

注: 您可能注意到没有用于处理鼠标事件，工具提示和绘图图的代码。 虽然在非常具体的情况下，可为这些内容添加自定义代码，但刚才创建的可视化已支持突出显示、选择、过滤和交互式图例！ 所有这些都通过 RenderBase 基类和运行可视化的环境向您提供。 这使您能够以最小的工作量来创建功能强大、一致的可视化。

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

在步骤 1 中，您已通过运行 customvis start 来启动可视化。 这意味着您现在可以启动 Cognos Analytics ，并在仪表板或报告中试用可视化。 有关这方面的详细信息，请参阅 定制可视化的逐步指南。

链接
  • 下载 部件 1 的源代码。