Vue3 ECharts 大屏与图表一体化

Vue3 + TS ECharts 一体化技能（大屏脚手架 + 单图表注入）

Overview

一个技能、两种用法，共用同一份图表资产 assets/builders/——不存在第二份图表模板：

两种模式产出的图表都是同一套三件套，结构、命名、生命周期完全一致：

src/hooks/charts/builders/.ts      # 选项构造器：纯函数 buildOption(data, config)
src/hooks/charts/useChart.ts      # 业务 hook：托管 init / setOption / resize / dispose
src/components/charts/Chart.vue   # UI 组件：props 接 data/config/height/theme

自包含、弱耦合：每个图表只依赖自己的 hook + builder，放进任意 Vue3 项目即可用，不注入/不覆盖任何共享 useECharts.ts（可选共享件见 assets/use-echarts.ts）。

决策：用哪个模式

• 用户要「一个页面 / 一个项目 / 大屏 / 看板」→ scaffold
• 用户要「加一个图表 / 封装个折线图 / 做个饼图组件」→ chart
• 判不出来就问，别猜。

---

模式 A：scaffold（一键起大屏）

node "/scripts/generate.mjs" ./my-screen
node "/scripts/generate.mjs" ./my-screen --theme tech-green --install
node "/scripts/generate.mjs" ./my-screen --charts trend:line,device:pie,region:map --no-kpi
node "/scripts/generate.mjs" ./my-screen --dry-run     # 只看计划不落盘

`` 即本技能目录 C:/Users/李玉明/.workbuddy/skills/vue3-echarts-dashboard。

产出结构

my-screen/
├── public/
│   ├── data/*.json        # 页面初始化数据（Axios 拉取，16 份）
│   └── geo/china.json     # 中国省级边界（离线渲染，合规）
└── src/
    ├── main.ts            # 注册 pinia / naive-ui / vue3-digital-flop / 应用主题
    ├── App.vue            # scale 等比缩放容器
    ├── theme/index.ts     # 主题（CSS 变量 + echarts.registerTheme('dashboard')）
    ├── api/               # axios 实例 + 接口 + 类型
    ├── stores/dashboard.ts# Pinia 数据中心（并发拉全部 JSON）
    ├── composables/useScreenScale.ts
    ├── components/        # ScreenHeader / PanelBox / DigitalFlop / Ranking
    ├── hooks/charts/      # builders/ + useChart.ts
    └── views/Dashboard.vue

布局与默认图表

4 列网格，行数按图表数推导（ceil((图表数 + KPI) / 4)）。默认 4×4 = 16 格：第 1 格 KPI 数字翻牌，其余 15 格图表。

数据自洽

统一流量口径 14000，各图互相印证，改数据时别破坏这个关系：

• 渠道合计（category）= 桑基「访问」节点 = 漏斗「访问」= 树/旭日根值 = 地图省份合计
• 漏斗 14000 → 10080 → 6020 → 3640 → 2772，与桑基逐段流转及各流失边完全对齐
• 水球 0.786 = 仪表盘 78.6（年度目标完成率）
• 词云与排行榜共用同一批热门页面数据

---

模式 B：chart（往已有项目注入单个图表）

python "/scripts/generate_chart.py" --target <项目根> --name sales-trend --type line
node    "/scripts/generate.mjs"      <项目根> --mode chart --name sales-trend --type line
node    "/scripts/generate.mjs"      <项目根> --mode chart --name my-pie --type pie --force

两条命令产出一致（.mjs 是主脚本，.py 是同逻辑的离线兜底）。名称接受 sales-trend / SalesTrend / sales_trend，脚本统一转 Pascal / kebab。

参数：--name（必填）、--type（默认 line）、--dry-run、--force。

产出 3 个文件后，在用到的地方：

可用类型（18 类）

每个类型的 ChartData 与 public/data/*.json 的结构一一对应（含 title），所以大屏数据可直接复用，无需适配层。

---

主题系统（两模式通用）

• CSS 变量：applyTheme() 写入 --c-primary / --c-primary2 / --c-text / --c-accent / --c-axis，组件样式用 color-mix(in srgb, var(--c-primary) N%, transparent)。
• ECharts 主题：echarts.registerTheme('dashboard', …)，大屏模式下 hook 默认 theme: 'dashboard'。
• builder 调色板：hook 里的 BASE_CONFIG 由生成器按主题注入 { colors: [...], primary: '...' }（热力/地图注入 5 色渐变带）。用户传入的 config 优先级更高。
• 扩展主题：在 src/theme/index.ts 的 themes 里加一条，并把调色板同步到 scripts/generate.mjs 的 THEMES。

常见定制

• 加图表：node generate.mjs <项目根> --mode chart --name <名> --type <类型>，再在 Dashboard.vue 里放进一个 .cell。
• 换布局：改 views/Dashboard.vue 里 .dashboard__body 的 grid-template-columns 与 gridTemplateRows。
• 接后端：src/api/index.ts 里把 /data/*.json 换成真实接口，ChartData 结构保持不变即可。
• 去掉地图：删 public/geo/、RegionChart.vue、hooks/charts/useRegionChart.ts、builders/region.ts 及 store/api 中 map 相关引用，省约 570KB。
• 体积优化：参考 assets/echarts-tree-shaking.ts 改按需引入。

注意事项

• 插件型图表必须装依赖，hook 已在顶部自动 import：wordcloud → npm i echarts-wordcloud；liquidfill → npm i echarts-liquidfill。
• 地图合规：map 用 ECharts 内置 map + 本地 geoJSON（DataV 中国省级边界，含台湾省、港澳及南海诸岛），不接在线瓦片服务、不含密钥；hook 内先 registerMap 再 init。替换 geoJSON 时必须用自然资源部标准地图。
• vue3-digital-flop 的 start 只在首次加载生效，本模板用 end 绑定指标值，初始化播放一次动画。
• build 脚本仅 vite build（不跑 vue-tsc），避免全局注册的组件触发模板类型报错；需要类型检查用 npm run type-check。
• 约定与 plop-vue3-codegen 对齐：kebab 目录、Pascal 组件、camel hook，@ → src。