宜搭 ECharts 高级报表技能

适用场景

核心规则

致命规则（FATAL）

1. 聚合统计禁止前端聚合：KPI、分组、求和、平均、趋势、占比都必须走原生报表 getDataAsync.json / getCacheData.json。
2. 必须依赖原生报表：不能在没有原生报表数据源的情况下直接创建 ECharts 聚合页面。
3. 不要混用 cid 和 fieldId：cid 是 node_xxx，用于报表数据请求；fieldId 是组件标识，不能作为 API 请求参数。
4. 不要编造报表参数：reportId、cid、dataSetKey、filterKey 必须来自 URL 或 Schema。
5. ECharts 通过 CDN 加载：使用 this.utils.loadScript 或等价动态脚本加载，禁止 import / require。
6. 数据失败必须有错误态：接口失败、无权限、空数据都要展示可理解提示，不要静默空白。

重要规则（IMPORTANT）

1. 原生报表双端隐藏：创建 ECharts 页面后，原生报表作为数据源应在 PC 和移动端导航中隐藏。
2. 记录绑定关系：写入 .cache/<项目名>-report-bindding.json，记录 ECharts 页面、原生报表和组件映射。
3. 更新时双页面同步：需求变化时先更新原生报表 Schema，再更新 ECharts 页面和绑定关系。
4. 明细表走表单数据接口：仅数据明细表可用 this.utils.yida.searchFormDatas，聚合图表仍走报表接口。
5. 遵循平台 JSX 组件页面规范：状态、生命周期、事件绑定、发布前校验按平台 Jsx 组件运行时规则执行。
6. 当前应用报表绑定优先：修复或迁移现有 ECharts 页面时，不要复用其它应用的 REPORT_xxx、prdId/topicId 或 cid。必须在当前 app 内创建或同步原生报表，再批量替换绑定。

方案选择

开发流程

# Step 1: 只读检测环境和登录态
openyida env --json
openyida login --check-only --json

# Step 2: 准备原生报表数据源
# 无原生报表时先使用 yida-report 创建；已有 URL 时解析 appType/formUuid

# Step 3: 获取报表 Schema；需要文件时用 CLI 输出目录或结构化文件写入工具保存 stdout
openyida get-schema <appType> --all --keyword <报表名称> --output-dir .cache/openyida/<项目名或任务名>/schemas

# Step 4: 解析 cid / className / dataSetKey / filterKey / cname

# Step 5: 创建 ECharts 自定义页面并编写源码
openyida create-page <appType> "<ECharts页面名>" --mode dashboard
openyida check-page project/pages/src/<页面名>.oyd.jsx

# Step 6: 发布并验证
openyida publish project/pages/src/<页面名>.oyd.jsx <appType> <echartsFormUuid> --health-check

已有 ECharts 页面 / 跨应用迁移修复流程

当页面报错 no permission for the report、图表数据加载失败，或发现源码里绑定的 REPORT_xxx 属于旧应用时，按下面流程修复：

1. openyida list-forms <当前appType> --json 确认当前应用是否已有 formType=report；没有则先用 yida-create-form-page 创建数据源表单，按业务场景写入示例数据，再用 yida-report 创建原生报表。
2. openyida get-schema <当前appType> <新REPORT_xxx> --json，从 componentsTree 提取所有 Youshu* 组件的 id、componentName、props.dataSetModelMap key、dataViewQueryModel.filterList[].filterKey 和标题。
3. 页面常量只保留 REPORT_FORM_UUID / REPORT_UUID，prdId/topicId 必须通过 getFormNavigationListByOrder 按该 REPORT 动态获取。
4. 每个组件绑定使用真实 schema 值：cid 使用 node_oc...，className 使用 YoushuTable / YoushuSimpleIndicatorCard 等，表格 dataSetKey 以 schema 为准（常见 table），指标卡常见 youshuData。
5. filterKey 必须按组件记录，例如 statusTableStatus、budgetTableStatus。不要把字段级的 status 当作多个组件通用的 filterKey。
6. 写入 .cache/openyida/<任务名>/report-binding.json，记录数据源表单、新报表、组件映射和绑定的 ECharts 页面。
7. 增加防回归测试：grep 或 Jest 断言源码不再包含旧 REPORT、旧 prdId、旧 appType 和旧 cid 前缀。
8. 执行 openyida check-page、openyida compile、openyida publish ... --health-check，最后跑 git diff --check。

报表参数速查

图表组件白名单

必须排除 YoushuPageHeader、YoushuTopFilterContainer、YoushuSelectFilter、YoushuTimeFilter、YoushuInputFilter 等容器或筛选器组件。

ECharts 页面必备结构

数据接口速查

生成前自检

• [ ] 已确认需求是 ECharts 高级可视化，而非普通原生报表
• [ ] 已存在或已创建原生报表数据源
• [ ] 已通过 openyida get-schema 获取 Schema 文件
• [ ] 已提取每个图表组件的 cid、className、dataSetKey、filterKey、cname
• [ ] prdId 通过导航接口动态获取，不硬编码
• [ ] 页面绑定的 REPORT_xxx 属于当前 app，不是旧样例应用或其它应用
• [ ] filterKey 按组件记录，未把同一字段的筛选 key 跨组件复用
• [ ] 聚合图表不使用 searchFormDatas 做前端聚合
• [ ] renderJsx 所有分支都有隐藏 timestamp div
• [ ] didUnmount 清理 ECharts 实例、resize 监听和定时器
• [ ] 发布前执行 openyida check-page <源文件>
• [ ] 记录 .cache/<项目名>-report-bindding.json

常见问题

Q：用户说"优化已有报表"，是不是改原生报表？
A：不是。本技能最终产物是 ECharts 自定义页面，原生报表只作为数据源。

Q：为什么不能前端聚合？
A：权限、过滤器、数据量和统计口径都由宜搭原生报表保证；前端聚合容易越权、慢且口径不一致。

Q：多个图表能共用同一个 filterKey 吗？
A：不能。同一个筛选器在不同组件里也可能有不同 filterKey，必须逐组件提取。

Q：页面点击筛选后怎么刷新？
A：更新 _customState.filterValueMap，重新调用报表数据请求函数，对已有 chart 执行 setOption，不要频繁 dispose 重建。

参考文档