基础图形 | Smartchart开发手册

快速应用基础图形组件 #

SmartChart 内置了丰富的基础图形组件，支持一键引用并快速定制。

在顶部菜单选择 “图形” → “基础图形”，点击任意图形即可一键应用到当前图表
在 图形商店 中可以找到更多社区贡献的 SmartChart 图形模板
内置基础图形覆盖常见类型（柱图、折线图、饼图等），通过简单修改配置即可衍生出堆叠图、面积图、双轴图等变体

基础图形选择

理解 ECharts 基础概念 #

SmartChart 的图形配置完全基于 ECharts option，理解以下核心概念有助于快速上手。

系列（series） #

系列是图形的核心，定义"画什么图、用什么数据"。每种图形类型（柱图、折线图、饼图、散点图等）对应一种系列类型（type: 'bar'、type: 'line'…）。

系列示意

组件（component） #

ECharts 将图表中的每个元素都抽象为"组件"，常用组件包括：

组件	作用
`xAxis` / `yAxis`	直角坐标系的 X/Y 轴
`grid`	直角坐标系底板（控制图表区域的位置和大小）
`legend`	图例（系列名称标识）
`tooltip`	提示框（鼠标悬停显示数据）
`toolbox`	工具栏（下载、切换图形等）
`dataZoom`	数据区缩放（拖动筛选数据范围）
`visualMap`	视觉映射（将数据映射为颜色、大小等）
`geo`	地理坐标系（地图）

组件示意

组件定位 #

绝大多数组件支持 top / right / bottom / left / width / height 进行精确定位（坐标基于 ECharts 容器）：

绝对像素：bottom: 54 表示距容器底边 54px
百分比：right: '20%' 表示距容器右边 20%

组件定位示意

坐标系 #

不同类型的系列对应不同的坐标系（直角坐标系、极坐标系、地理坐标系等），一个图表中可以同时存在多种坐标系。

坐标系示意

快速应用配置项 #

在图形编辑器的 “参考” 菜单中可以找到常用配置项片段，直接复制使用。

参考菜单

ECharts 配置项非常丰富，完整列表请参考 ECharts 速查手册
也可以通过 AI 获取配置方法，推荐提示词：

我需要将 ECharts 的标题字体颜色设为红色，请仅提供对应的 ECharts 配置项

注意：尽量不要在代码中硬编码颜色等样式，推荐在 图形主题 中统一设置，方便后期整体风格替换。

将 ECharts 官方示例转化为 SmartChart 图形 #

第一步：获取原生 ECharts 示例 #

前往 ECharts 官方示例找到目标图形，复制其 option 代码。

以简单柱图为例（查看示例）：

option = {
    xAxis: {
        type: 'category',
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
    },
    yAxis: {
        type: 'value'
    },
    series: [{
        data: [120, 200, 150, 80, 70, 110, 130],
        type: 'bar'
    }]
};

第二步：转化为 SmartChart 图形 #

将 option 代码粘贴到 SmartChart 图形编辑器，点击菜单 “工具 → 转化为 SmartChart” 进行自动初步转化。

转化菜单

自动转化后，将静态数据替换为动态数据集，参考以下标准写法：

let dataset = __dataset__              // 接收后端传入的二维数组
let legend_label = ds_rowname(dataset) // 自动获取 legend 标签（维度列表）
let xlabel = dataset[0].slice(1)       // X 轴标签（表头中除第一列外的字段名）
dataset = ds_createMap(dataset)        // 转化为 key→[] 字典格式

// 手动定义 series（混合图形，如柱+线）
let series = [];
series.push({
    data: dataset[legend_label[0]],    // 第一个系列数据
    type: 'bar'
});
series.push({
    data: dataset[legend_label[1]],    // 第二个系列数据
    type: 'line'
});

option__name__ = {
    xAxis: {
        type: 'category',
        data: xlabel
    },
    yAxis: {
        type: 'value'
    },
    series: series
};

效果预览（柱形 + 折线混合图）：

第三步：添加更多配置项 #

在 option 中加入 title、legend、tooltip 等配置丰富图表：

option__name__ = {
    title: {
        text: '自定义图示例',
        left: 'center'
    },
    tooltip: {
        trigger: 'axis',
        formatter: '{a} <br/>{b} : {c}'   // 提示框格式：系列名 + 类别 + 值
    },
    legend: {
        left: 'left',
        data: legend_label                 // 图例自动取维度标签
    },
    xAxis: {
        type: 'category',
        data: xlabel
    },
    yAxis: {
        type: 'value'
    },
    series: series
};

自动化生成 series（多系列通用写法） #

当系列数量不固定时，推荐用循环自动生成：

// dataset 已转为 ds_createMap 格式后，按 legend_label 自动生成
let series = [];
for (let name of legend_label) {
    series.push({
        name: name,
        data: dataset[name],
        type: 'bar'
    });
}

// 或者基于原始二维数组列数自动生成（更简洁）
let series = [];
for (let i = 1; i < dataset[0].length; i++) {
    series.push({ type: 'bar' });
}
// 配合 ECharts dataset 使用，无需手动指定 data
option__name__ = {
    dataset: { source: __dataset__ },
    xAxis: { type: 'category' },
    yAxis: { type: 'value' },
    series: series
};

常见问题排查 #

图形编辑器能显示，但保存后仪表盘中无法显示 #

按顺序检查以下几点：

变量名未替换：检查代码中 myChart 和 option 是否都已替换为带 __name__ 后缀的形式：
```
// ❌ 错误
myChart.setOption(option)
// ✅ 正确
myChart__name__.setOption(option__name__)
```
多次 setOption：如果代码中手动调用了 setOption，需要在 option 定义后补上：
```
myChart__name__.setOption(option__name__)
```

变量声明冲突：代码中如有 let data = xx，需改为不带 let 的赋值：

// ❌ 错误（let 作用域问题）
let data = dataset
// ✅ 正确
data = dataset