如何接入业务 💡
通常，AIGC 可视化业务需要同时对接前端（组件库）和后端（AI 可视化推荐模型算法服务，@韩东明 handongming2@myhexin.com），该页面文档主要涉及的是前端组件库相关内容。
了解 AIGC 可视化组件库的局限性。
了解 AI 可视化推荐模型算法服务数据协议
如果涉及到对接后端 AI 可视化推荐模型算法服务，新旧业务建议以当前统一字段名称后的数据协议版本为基础，降低后续维护成本。（已上线业务 AI-F10、iFind、AIME）
为了增强可扩展性，组件库进行了重构，目前同时支持两种参数格式：基于 view 和 layer 的新格式（后端 AI 可视化推荐模型算法服务暂不支持输出该格式）和兼容格式（当前最新版本 AI 可视化推荐模型算法服务输出的格式，即上文提到的统一字段名称后的数据协议版本）。
下面给出两种格式示例：
// 兼容格式（AI 可视化推荐模型算法服务支持的格式）
{
legacy: true,
type: 'bar',
data: dataset,
xAxisAttribute: 'date',
yAxisAttribute: 'y',
}
// 基于 `view` 和 `layer` 的新格式
{
data: [
{
values: dataset
}
],
view: {
main: {
layers: [
{
type: 'bar',
encoding: {
x: 'date',
y: 'y'
}
}
]
},
}
}
以上两种格式组件库目前均支持，业务侧如果对接 AI 可视化推荐模型算法服务，业务前端无需将参数格式转换为基于 view 和 layer 的新格式。（更多用例可在组件库项目的 examples/case 目录下查看）
使用组件库
AIGC 可视化组件库基于传统的范式图表组件库进行了高度抽象封装，建议了解一些前置概念，例如规范设计和数据规范。
构建主题风格
业务开发通常更多时间关注的是如何实现当前业务场景的样式风格，组件库提供了设计 Token 机制来实现主题风格配置。
由于 UED Token 规范不能完全覆盖可视化组件的所有配置，所以 token 参数实际上可以包含两部分内容，即 UED Token 变量（@钱宇楠，qianyunan@myhexin.com）和配置项。
给出示例：
{
token: {
// 配置项
dvStandardChart: {
baseOption: {
grid: {
height: 'auto',
width: 'auto'
}
}
},
// UED Token
'--color-visualization': [
'#3366FF',
'#FF4019',
'#ff9500',
'#62b312',
'#14ccbd',
'#199fff',
'#4433ff',
'#ff33aa',
'#ff33aa',
'#858585'
],
'--color-background-weak': 'rgba(0,0,0,0.04)',
}
}
如果同时存在 UED Token 变量和配置项，则会出现它们共同影响了图表组件的同一个配置项的情况，组件库的实现策略是配置项优先级高于 UED Token 变量。例如：
{
token: {
// 配置项
dvStandardChart: {
baseOption: {
color: [
'#14ccbd',
'#199fff',
'#4433ff',
]
}
},
// UED Token
'--color-visualization': [
'#3366FF',
'#FF4019',
'#ff9500',
'#62b312',
'#14ccbd',
'#199fff',
'#4433ff',
'#ff33aa',
'#ff33aa',
'#858585'
],
}
}
在组件库内部，最终色板的取值为 dvStandardChart.baseOption.color，由于 UED Token 变量 --color-visualization 优先级比配置项低，则不会生效。
通常来说，通过 token 参数以声明式配置的方式可以应对大部分主题风格的需求，但鉴于实际业务的复杂性，依然无法保证百分百应对所有需求，遇到强业务逻辑的需求，建议通过 Hook APIs 来解决。
例如，针对多 Y 轴的处理：
{
hook: {
beforeRenderStandardChart: (api, renderParams) => {
const { option } = renderParams;
// * --- 同一个 grid 内多 y 轴名称位置问题，将多余的轴隐藏
const girdMap = {
0: {
countLeftYAxis: 0,
countRightYAxis: 0
}
};
option?.yAxis?.forEach((axis, index) => {
const gridIndex = axis.gridIndex || 0;
let counter = girdMap[gridIndex];
if (!counter) {
counter = girdMap[gridIndex] = {
countLeftYAxis: 0,
countRightYAxis: 0
};
}
const isRight = axis?.position === 'right';
if (isRight || (counter.countLeftYAxis > 0 && axis?.position !== 'left')) {
if (counter.countRightYAxis > 0) {
// eslint-disable-next-line no-param-reassign
axis.show = false;
}
counter.countRightYAxis += 1;
} else {
if (counter.countLeftYAxis > 0) {
// eslint-disable-next-line no-param-reassign
axis.show = false;
}
counter.countLeftYAxis += 1;
}
}
}
}
}
需要注意的是，无论 token 还是 hook 参数，它们都是可重用的，在每一次渲染不同类型组件时都会执行，简单的来说就是 1 套配置对应 n 类组件。（还有一种情况，业务侧可以为不同类型组件渲染时准备不同的 token 和 hook 配置，但不建议这样做，一方面是成本很高，另一方面则是违背了 AIGC 可视化简单、快速的理念。）
业务开发构建主题风格配置时，建议可以直接在组件库项目中进行调试，可参考 examples/config/ai-f10 目录下的实现。
其中，token 参数可以完全自己构建，也可以基于组件库中预先配置的默认主题进行构建：
import { presetThemeBuilder } from 'path/to/bundle.esm.min.js';
const spec = {
token: presetThemeBuilder('light', {
backgroundColor: '#fff'
})
};
不同类型组件的差异化配置
此外，由于 AIGC 组件库封装了大量不同类型的图表组件，所以降低了灵活性，如果遇到不同类型组件难以统一为同样的风格配置时，也可以做差异化配置，不过这会增加开发成本。实现的方式是在渲染时，添加额外配置参数。给出示例：
// 兼容格式（AI 可视化推荐模型算法服务支持的格式）
{
legacy: true,
type: 'bar',
data: dataset,
xAxisAttribute: 'date',
yAxisAttribute: 'y',
style: {
gird: {
show: true,
},
series: [
{
type: 'bar',
showBackground: true,
}
]
}
}
// 基于 `view` 和 `layer` 的新格式
{
token,
hook,
view: {
main: {
layers: [
{
type: 'bar',
encoding: {
x: 'date',
y: 'y'
},
showBackground: true,
}
],
gird: {
show: true,
},
}
}
}
以上介绍了 3 种影响图表最终渲染配置的方案，它们的执行流程如下所示：
[0.] token（parsing） -> layer render -> -> [1.] view option（override） -> [2.] hook（call） -> Chart Visualization
简单的来说，首先 token 作为默认值，接着 view 中的差异化配置将会覆盖默认值，最终 hook 执行时对渲染配置项做最后的处理，具体可参考主题与配置解析流程一节的内容。