DataGear 6.0.0 的核心变化集中在看板开发链路：新增 API 2.0 版本环境，并重构看板 API 与内置图表插件。与此同时，看板源码编辑模式补上了“替换”和“自定义插入图表元素属性”功能。这次升级不仅影响可视化设计人员，也会直接影响维护自定义看板、图表插件和页面脚本的开发者。
API 2.0 是一次明确的兼容边界
新版本专门提供 API 2.0 环境，意味着看板 API 的变化不应被当成普通的小版本增量。对于已有项目，升级前最需要梳理的是看板源码中所有依赖旧 API 的位置，包括：
- 直接调用看板对象或图表对象的方法；
- 读取图表状态、数据集结果和元素属性的脚本；
- 自定义事件处理代码；
- 基于旧版内置图表插件扩展的实现；
- 复制到多个看板中的公共 JavaScript 片段。
不要只检查能否打开看板。页面成功加载，并不代表筛选联动、定时刷新、下钻或者自定义事件仍按原逻辑执行。更可靠的办法是给现有看板建立一份交互清单，在 API 2.0 环境中逐项回归。
| 检查对象 | 建议验证内容 |
|---|---|
| 图表渲染 | 初始数据、空数据和异常数据能否正常展示 |
| 参数传递 | 查询条件、默认值和多值参数是否正确 |
| 图表联动 | 点击、筛选、下钻和跳转是否仍然生效 |
| 页面脚本 | 初始化顺序、事件回调和异步逻辑是否正常 |
| 自定义插件 | 插件注册、配置读取和渲染生命周期是否兼容 |
内置图表插件重构带来的影响
内置图表插件与看板 API 同时重构，说明升级检查不能局限于页面代码。依赖内置插件行为的自定义样式、配置覆盖和二次封装，也可能需要调整。
建议把插件使用方式分成三类处理：
- 仅通过设计器配置的标准图表，可以优先进行视觉回归，检查标题、图例、坐标轴、颜色和提示框。
- 使用源码修改图表元素属性的页面，需要核对属性名称、生成结果以及运行时读取方式。
- 自定义图表插件应单独建立测试看板，覆盖初始化、更新、销毁和窗口尺寸变化等场景。
如果生产环境包含大量看板，可以先选取柱状图、折线图、饼图、表格以及一个自定义插件作为代表样本。样本通过后再扩大迁移范围，能更早暴露公共兼容问题。
源码编辑器开始适合批量维护
6.0.0 为看板设计页面的源码编辑模式增加了“替换”功能。这个看似基础的能力，在迁移 API、统一属性名或清理重复脚本时非常实用。
替换操作也有明显风险。相同字符串可能同时出现在 JavaScript、HTML 属性、CSS 选择器和普通文本中。执行批量替换前，应先导出或复制看板源码，并使用足够具体的匹配内容。例如，替换完整方法调用通常比替换一个通用变量名更可控。
新增的“自定义插入图表元素属性”功能，则可以减少反复手写属性的成本。团队可以把常用属性沉淀成统一片段，用于图表标识、业务域、刷新策略或测试标记。具体可用属性及其格式，应以 6.0.0 实际设计器和 API 2.0 文档为准。
可以这样实践：为看板元素建立可检查的属性约定
下面是一个可直接打开运行的独立 HTML 示例，用来演示如何为图表容器定义自定义属性，并通过 JavaScript 读取它们。它不是 DataGear 6.0.0 官方 API 示例；接入真实看板时，需要把属性名称和 API 调用替换为平台实际支持的形式。
将内容保存为 dashboard-attribute-demo.html，然后用浏览器打开：
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>看板元素属性示例</title>
<style>
body { font: 16px/1.5 sans-serif; margin: 24px; }
.chart { border: 1px solid #bbb; padding: 20px; }
</style>
</head>
<body>
<section
id="sales-chart"
class="chart"
data-chart-key="monthly-sales"
data-business-domain="sales"
data-refresh-seconds="60"
>
月度销售图表容器
</section>
<script>
const element = document.querySelector('#sales-chart');
const config = {
chartKey: element.dataset.chartKey,
businessDomain: element.dataset.businessDomain,
refreshSeconds: Number(element.dataset.refreshSeconds)
};
if (!Number.isFinite(config.refreshSeconds)) {
throw new Error('data-refresh-seconds 必须是数字');
}
console.log('图表元素配置：', config);
element.insertAdjacentHTML(
'beforeend',
`<pre>${JSON.stringify(config, null, 2)}</pre>`
);
</script>
</body>
</html>
也可以用下面的命令启动一个本地静态服务器：
python3 -m http.server 8080
随后访问 http://localhost:8080/dashboard-attribute-demo.html。在真实项目中，可以将同类属性通过源码编辑器的新插入能力加入图表元素，再由统一脚本读取。属性命名建议采用 data- 前缀，避免与标准 HTML 属性冲突；但 DataGear 是否对属性名称有额外约束，需要在迁移前验证。
升级时把回滚能力留在手里
DataGear 6.0.0 涉及 API 和图表插件重构，适合采用分批迁移，而不是直接覆盖生产环境。升级前至少应完成以下检查：
- 备份应用配置、数据库以及关键看板源码；
- 统计旧版 API 和自定义插件的使用范围；
- 在独立环境验证 API 2.0，不直接修改唯一的生产副本；
- 对核心看板执行数据、交互和视觉回归；
- 使用源码替换功能时保留替换前版本；
- 验证数据集参数相关配置，尤其是带默认值和动态传参的场景；
- 准备明确的回滚步骤，并记录迁移期间修改过的看板。
这次版本的价值不只在于增加编辑器功能，更在于为看板 API 和插件体系建立新的演进基础。对新项目，可以直接围绕 API 2.0 建立开发规范；对已有项目，则应把它视为一次需要盘点依赖、测试行为并控制发布范围的兼容性升级。