如何注册组件

在注册一个新的组件（Layer）之前，请先了解前置概念，如Layer 概念、协议层设计、数据规范、Hook APIs 等。

组件的实现

要注册一个外部的组件，首先你需要知道如何定义一个组件，以及如何实现一个组件。此部分的实现与组件库内开发组件类似。

我会以第三方库-D3.js 为例，介绍如何实现并注册一个 D3 的组件。

创建组件文件

组件文件的创建可以是业务方项目中的任意位置，由业务方自己定义。

协议层定义

首先，引入 AIGC 组件库的打包产物:

import * as AIGCDataVis from './path/bundle.esm.js';

备注

若是由CDN资源导入的 AIGC 组件库，则无需引入，可以直接从 window 获取 AIGCDataVis。

提示

注册的组件统一都是基于业务方第三方库实现的自定义组件，所以组件的层类型为ExternalLayer

声明基本信息和定义：

// 组件的可视化信息，部分信息用来做训练
const DEFINE = AIGCDataVis.DEFINE;

const visInfo = {
  id: 'd3Bar',
  name_en: 'd3 柱状图',
  name_zh: 'd3 Bar',
  types_en: [],
  purpose_en: [],
  purpose_zh: [],
  standers: '',
  /** 保证和 Spec.encoding 字段一致 */
  parameters: {
    x: {
      itemType: [DEFINE.STR],
      category: DEFINE.SINGLE
    },
    y: {
      itemType: [DEFINE.NUMBER],
      category: DEFINE.SINGLE
    }
  }
};

// 组件的定义和实现
export const d3Bar = AIGCDataVis.defineExternalLayer({
  type: visInfo.id,
  // cdn 为需要的第三方CDN资源，为可选参数，支持字符串或数组形式
  cdn: ['https://cdn.jsdelivr.net/npm/d3@7']
  visInfo,
  // 渲染函数
  render(api, spec, $dom) {}
});

这里需要注意的是，id 作为组件的唯一标识，在所有组件中必须唯一，cdn 字段目前只支持字符串或数组形式的链接资源（具体可参考组件库'./example/d3Example.js'）。

提示

打包产物中暴露了 DEFINE 常量对象，方便业务方定义可视化信息的类型，需要注意的是 parameters 中对数据的特征提取需要业务方针对业务数据进行自定义。另外，打包产物中还暴露了 defineExternalLayer、defineHXKLineLayer、defineNormalLayer、defineStandardChartLayer 等方法，方便业务方定义组件信息，具体定义可见源码中 ./src/core/layer。

实现组件渲染逻辑

定义中的 render() 函数字段是用来实现具体的渲染逻辑。

备注

其中，render() 函数有 3 个参数：

• 参数 api 为一些公共的 APIs 能力，例如工具函数（util）、Hook API（hook）、UI 组件（ui）等；
• 参数 spec 为组件规范定义的参数，例如数据相关字段（数据集的索引 dataIndex、数据编码参数 encoding）；
• 参数 $dom 为渲染图表的 DOM 元素实例。
• 返回 需要返回一个回调函数，函数中应该包含当前组件的销毁逻辑。

render() 函数中并没有过多的限制，业务方可以根据自己的习惯或者参考组件库中的实现方式，自行实现。

注册组件

import {d3Bar} from './path/to/d3Example.js';

AIGCDataVis.registerLayer(d3Bar);

注册后即可通过之前定义的 id 访问到组件，例如：

export default () => ({
  title: '第三方资源注册使用示例-d3',
  data: [
    {
      values: data
    }
  ],
  view: {
    main: {
      layers: [
        {
          type: 'd3Bar',
          encoding: {
            x: 'letter',
            y: 'frequency',
          },
        }
      ]
    }
  }
});

具体可以参考组件库中'./example/case/d3Bar.js'。