Electron 鸿蒙PC 大屏实战:12 类组件库里,7 个画在 SVG、5 个拼在 HTML,还有一张删不掉的默认占位表

左侧组件库点一下「折线趋势」,画布上就多一块能动的图;点「状态文本」,多出来的却是一行带小圆点的字。我一开始也以为这 12 个格子只是配了 12 个图标,直到把 views/editor.js 的 LIB、lib/charts.js 的两张 renderer 表和 lib/mock-data.js 的 optionFor() 逐行对完,才看清一个类型字符串是怎么同时决定「默认占几格」「走哪条渲染轨」「喂什么形状的 option」三件事的:7 类走 C.renderers 用 U.svg() 一笔笔画路径,5 类走 C.htmlRenderers 直接拼 innerHTML,w/h 存在 LIB 里当占位,切换类型时还要反过来把组件宽高收敛一遍。类型表为什么必须和渲染表、数据表的 12 个键一一对应、为什么 htmlRenderers 要优先判定、为什么多了个类型不改三处就会画出一句红字,以及我踩过的那次「未知图表类型」——下面把这几个问题一次讲透。

0. 环境与实测数据

项版本或数据
Nodev24.13.0
npm11.6.2
运行平台openharmony
渲染层零依赖静态 SPA:无 npm 运行时依赖、无 CDN、无构建工具、非 ES Module,传统 <script> 顺序加载
Electron30+(package.json 声明 ^30.0.0,本机未安装)
鸿蒙 SDK"5.0.0(12)" / runtimeOS: "HarmonyOS"(配置声明,本机未装 SDK)
hvigor本机未安装,HAP 走 dry-run
验证方式npm run check / npm run ohos:check / Node DOM 桩冒烟(唯一源与镜像各一次)
实测设备待补:本轮无真机,全部结论来自 CLI 自检与 DOM 冒烟,未实跑 Electron 窗口拖拽真机手感与 ArkWeb 下的 innerHTML 差异

页面上能读到的实测口径,全部能回到文件行号:

项值来源
组件库类型数12 类views/editor.js:6 LIB
SVG 渲染器7 类(line / bar / pie / radar / gauge / map / scatter)lib/charts.js:111-317 C.renderers
HTML 渲染器5 类(number / progress / table / carousel / text)lib/charts.js:320-385 C.htmlRenderers
optionFor 分支12 类 + 1 个 defaultlib/mock-data.js:201-217
默认占位每类一组 w/h(2×5 到 5×5)editor.js:7-18
预制满配看板14 个组件mock-data.js:17-32 FULL
栅格12 列 × 14 行editor.js:5 COLS/ROWS
组件实例登记表registry 数组charts.js:9
外部渲染器适配位useExternalRenderer(echarts)charts.js:480
自检结论共 26 项,通过 26 项,失败 0 项npm run check 既有输出

命令输出里那行 shell-init: error retrieving current directory: getcwd 是鸿蒙沙盒对用户目录的包装告警,退出码 0、输出完整,不影响任何结论。这一点在本辑 5 篇里都成立,后面不重复交代。

1. 「一排图标」不等于「12 个类型」——这个问题是怎么找上我的

我一开始也以为组件库就是 LIB.map 出来的一排 ed-comp-item,点哪个就把哪个图标搬到画布上,半小时能收工。editor.js:342-345 确实这么渲染的:draggable="true"、data-type、ico、名字,四个字段整整齐齐,看着就是「图标 → 组件」的直连。

请添加图片描述

第一遍顺着 addComponent() 往下走就卡住了。editor.js:274-285 新建一个组件时,压根没往组件对象里塞「怎么画」的函数,只塞了一个 type: def.type 和一对 w/h。那图上那条会起伏的折线是谁画的?翻到 charts.js:403-418 的 render() 才明白:它先查 C.htmlRenderers[this.type],查不到才去 U.svgEl() 建画布、查 C.renderers[this.type]。也就是说,「折线趋势」和「状态文本」从 type 这个字符串开始就分了两条完全不同的路——前者最终落到 svg.appendChild(U.svg('path'))(charts.js:130),后者落到 dom.innerHTML = '<div class="dv-statustext">'(charts.js:382)。我把一个 text 组件的属性面板里「图表类型」下拉改成 line,editor.js:234 又顺手把 c.w/c.h 用新类型的默认值 Math.min 了一遍——同一个对象,类型一变,尺寸、数据、渲染轨全跟着变。

请添加图片描述

更难受的是那次手滑:我在 optionFor 里漏抄了一个 case,DOM 桩冒烟时画布中央直接出现一行红字。它没崩,只是安静地画了一句:

未知图表类型:scatter

所以这个题目的边界很清楚:type 不是「组件的名字」,而是「三张表的联合主键」——LIB 给它默认占位,C.renderers / C.htmlRenderers 给它渲染轨,M.optionFor 给它数据形状,三者缺一个,组件就只是个带标题的空框。 12 类不是一个函数里 12 个 if,是一个字符串在三个文件里各查一次表。

拆下来三件任务:一是 LIB 的 6 个字段各自被谁消费、为什么 w/h 不能省;二是 7 类 SVG 与 5 类 HTML 的分流判断为什么必须 htmlRenderers 优先、多出来的类型会落到哪;三是 optionFor() 的 12 个 case 与 tick() 逻辑时钟怎么让同一块图每次刷新都换一批数。

第 2 节末尾我会提到组件库那格「点击 / 拖拽」的小字——它对应的是第 6 节里一次真实的 ResizeObserver is not defined。下面是干完之后的完整记录,包括我踩的每一个坑。

2. 效果展示

按老规矩,先给效果再讲原理。这轮没有截图,我把 #/editor 页面上能肉眼读到的状态逐行摆出来,每一行都对应一个真实函数或字段。

  • 组件库 12 格:editor.js:342-345 由 LIB.map 拼出,每格带 data-type="number|line|…|scatter"、draggable="true"、一个 ico 字符(◆ ⌁ ▥ ◔ ◎ ✧ ◓ ▰ ☰ ◫ ▤ ⁘)和中文名;表头右侧那行小字「点击 / 拖拽」写在 editor.js:341。
  • 画布里的 14 个卡片:默认看板走 mock-data.js:17-32 的 FULL,renderCanvas()(editor.js:94-116)按 components.forEach 逐个建 ed-item,卡头是 libDef(c.type).ico + U.esc(c.title),卡体挂一个空的 ed-item-host。
  • 卡体里真正的内容:editor.js:112 一行 DV.charts.mount(host, c),这一句把「空 div」变成折线/柱状/KPI/表格,是整页最容易被忽略的一次交接。
  • 属性面板的「图表类型」下拉:editor.js:203-204 用 LIB.map 生成 12 个 option,selected 由 c.type 决定——换句话说,属性面板和左侧组件库是同一张表,不是两份清单。
  • 「组件配置 JSON(只读)」:editor.js:217-218 把整个组件 JSON.stringify(c, null, 2) 后 U.esc 塞进 .dv-code,所以 base / digits / trend / unit / seriesNames / doughnut / horizontal / scroll / text 这些字段能直接看见——它们是 editor.js:282-284 新建组件时一次性写进去的。
  • 顶部工具条的「组件 N」角标:editor.js:115 由 b.components.length 写入 #ed-comp-count,与「12 × 14 栅格」tag(editor.js:333)并列。
  • 右侧图层列表:editor.js:253-258 把 components.slice().reverse() 画出来,每行显示 w×h,用的是 libDef(c.type).ico 而不是组件自己存图标。
  • 「设计分辨率 1920×1080」:editor.js:350 读 DV.store.state.settings.designWidth/designHeight,跟 LIB 的默认 w/h 不是一个量纲——一个是栅格格数,一个是像素。
  • 预览按钮:editor.js:337 的 #ed-preview,点下去 editor.js:390 先 boards.preview(S.boardId) 再 DV.app.go('dashboard'),画布就此交给大屏视图重新 mount 一遍。

请添加图片描述

3. 原理

这个页面真正要回答的,是「一个 type 字符串,从组件库那一格到画布上那块能动的图,中间被查了几次表、被谁改写过」。事件与回调的映射如下:

事件 / 入口方向回调对象应用要回答什么
点击 .ed-comp-item视图 → 建组件editor.js:393 addComponent(type)取哪一格 LIB 默认 w/h、落在哪个空位
dragstart / drop视图 → 建组件editor.js:394,399-406text/dv-type 传的是哪个类型、落点反算成第几列第几行
addComponent()建组件 → 状态editor.js:277-285组件对象里到底存不存渲染函数(type 之外全是数据字段)
renderCanvas()状态 → DOMeditor.js:94-116先 destroyAll() 还是先 innerHTML = ''、卡体交给谁
DV.charts.mount(host, c)视图 → 图表引擎charts.js:450-455用 c.type 建哪个 Chart 实例、option 从哪来
Chart.prototype.render()实例 → 双轨分流charts.js:403-418htmlRenderers[type] 有没有,没有才建 SVG
DV.mock.optionFor(c)实例 → 数据层mock-data.js:201-21712 个 case 里哪个给 { series, categories },哪个给 { text }
属性面板改 type编辑 → 收敛editor.js:234新类型的 w/h 要不要把旧尺寸压小、标题要不要重置
C.refreshAll()定时器 → 全部实例charts.js:457-460tick() 推几格逻辑时钟、失联的 dom 要不要 destroy()

type 是路由键,不是渲染器本身:组件对象里从头到尾没有一行画图的代码,只有一张被三个文件共同认可的索引。 这条决定了 editor.js 全文不出现 svg、path、canvas.getContext 里的任何一个——它只负责拼 ed-item 的壳,内容的解释权完整交给 lib/charts.js。渲染层能跑在 file:// 下,靠的就是这层「数据形状与绘制实现分离」。

请添加图片描述

还有一处模型判断值得先钉死:12 类不是「12 个同构的图表」,而是「7 个需要坐标系的图 + 5 个不需要坐标系的片段」。 SVG 那 7 类全都要 gridLines()(charts.js:77)或 pad 计算,HTML 那 5 类全是 dom.innerHTML = ... 拼字符串(charts.js:320-385)。所以 render() 里的判定顺序不能反:先查 htmlRenderers,命中就 return,否则才走 U.svgEl() + defs() 那套基建。这个细节决定了第 5 节为什么把「分流判断」单独拆成一小节,也决定了新增一个类型时,改一张表是不够的。

请添加图片描述
请添加图片描述

4. 工程怎么搭

组件类型相关的文件在唯一源里的位置:

electron/ohos/src/
├── index.html                      # 23 个 <script> 顺序加载;:41 是 views/editor.js
├── app.js                          # 13 个 hash 路由;:10 注册 { id:'editor' };:36 A.go
├── lib/
│   ├── utils.js                    # :11 U.el / :221 U.svg / :227 U.svgEl / :50 U.clamp / :72 U.deepClone
│   ├── mock-data.js                # :17 FULL / :34 SLOTS / :40 TYPES / :201 optionFor() 12 类分发
│   ├── store.js                    # :126 store.boards / :128 find / :162 update / :171 preview
│   ├── charts.js                   # :9 registry / :12 renderers / :13 htmlRenderers / :388 Chart
│   ├── datav.js                    # :79 sectionTitle / :8 panel,编辑器标题栏
│   ├── request.js                  # 数据源层,编辑器不直接依赖
│   ├── bridge.js                   # :224 B.file.saveJson,保存工程时用到
│   └── scenarios.js                # :413 LAYOUTS / :440 applyLayout,一键布局预设
├── views/
│   ├── editor.js                   # :5 COLS/ROWS / :6 LIB / :92 libDef / :94 renderCanvas / :274 addComponent
│   └── dashboard.js                # 预览目标,用同一套 DV.charts.mount 重画
└── styles/
    ├── base.css                    # 主题变量(--primary / --border)
    └── views.css                   # .ed-comp-grid / .ed-item / .ed-item-host 等编辑器样式

这次整理最关键的变化,是把「能画」变成「能查表」。三条边界平时看不出来,动一行代码就会撞上:lib/ 不依赖任何 views/(所以 charts.js 里没有 ed- 前缀的 class)、组件对象只存数据不存函数(所以 JSON.stringify(c) 能直接展示)、editor.js 只走 DV.charts 与 DV.mock 两个公共 API(所以把 charts.js 整份换成 ECharts 适配层,编辑器一行不用改,charts.js:480 的 useExternalRenderer 就是留的这个口)。

最小接入——组件库到画布其实就是三步:查表拿默认占位、建数据对象、把壳交给图表引擎:

// views/editor.js - addComponent()(节选,:274-285)
var def = LIB.filter(function (l) { return l.type === type; })[0] || LIB[0];
snapshot();
var c = {
  id: U.uid('c'), type: def.type, title: def.name,
  x: U.clamp(x === undefined ? 0 : x, 0, COLS - def.w),
  y: U.clamp(y === undefined ? 0 : y, 0, ROWS - def.h),
  w: def.w, h: def.h, dataSource: 'ds-http-01',
  base: U.randInt(800, 5000), digits: 2, trend: U.rand(-5, 18), unit: '万元',
  seriesNames: ['交易额', '退款额'], doughnut: true, horizontal: true, scroll: true,
  text: '运行状态正常 · 数据实时更新'
};
// views/editor.js - renderCanvas()(节选,:111-112)
var host = U.$('[data-host]', item);
DV.charts.mount(host, c);   // 内部:C.init(dom, c.type) → setOption(M.optionFor(c)) → render()

事件协议没有 IPC,只有一条 DOM 内的「类型契约」。新建组件落库后的形状长这样:

type  : "line"                      # 联合主键:LIB / renderers / optionFor 三表共用
w / h : 5 / 5                       # 来自 LIB,栅格格数,不是像素
optionFor("line") -> {             # mock-data.js:116 lineOption()
  categories: ["00:00", ... "23:00"],
  series: [{ name:"交易额", data:[...] }, { name:"退款额", data:[...] }],
  area: true, smooth: true, unit: "万元"
}
C.renderers.line(inst, svg, w, h, o)  # charts.js:111,只有这一支会用到 U.svg()

这里有一个很容易被忽略的窗口期:renderCanvas() 的第一句是 DV.charts.destroyAll()(editor.js:96),第二句才是 inner.innerHTML = ''(editor.js:97)。顺序反了会留下一批 _ro 还 observe 着已脱离文档 dom 的 Chart 实例——charts.js:459 虽然会在 refreshAll() 时按 dom.isConnected 兜底销毁,但那要等下一个刷新周期。先销毁再清空,是把这个空窗压到零。另一处缓冲在 charts.js:420-426:ResizeObserver 用 U.debounce(..., 120) 包了一层,缩放画布时不会每一帧都重画一次 SVG。

5. 把代码讲透

5.1 LIB 六个字段:w/h 为什么不能省

接收侧最容易写错的是把 LIB 当成「图标清单」。editor.js:6-19 每一格有 6 个字段,其中只有 ico 和 name 是给左侧面板看的:

// views/editor.js - LIB(节选,:6-19)
var LIB = [
  { type: 'number',   name: '数字指标', ico: '◆', w: 3, h: 2 },
  { type: 'line',     name: '折线趋势', ico: '⌁', w: 5, h: 5 },
  { type: 'bar',      name: '柱状排行', ico: '▥', w: 4, h: 5 },
  { type: 'pie',      name: '环形占比', ico: '◔', w: 3, h: 5 },
  { type: 'map',      name: '地图飞线', ico: '◎', w: 4, h: 5 },
  { type: 'radar',    name: '能力雷达', ico: '✧', w: 3, h: 5 },
  { type: 'gauge',    name: '仪表盘',   ico: '◓', w: 2, h: 5 },
  { type: 'progress', name: '进度条组', ico: '▰', w: 4, h: 2 },
  { type: 'table',    name: '实时列表', ico: '☰', w: 3, h: 5 },
  { type: 'carousel', name: '公告轮播', ico: '◫', w: 5, h: 2 },
  { type: 'text',     name: '状态文本', ico: '▤', w: 3, h: 2 },
  { type: 'scatter',  name: '气泡散点', ico: '⁘', w: 4, h: 5 }
];

三个细节值得单独说:第一,w/h 是栅格格数,配合 COLS=12, ROWS=14(editor.js:5),最小 2×5(仪表盘)、最大 5×5(折线/轮播),全表没有超过 12 列或 14 行的值。 第二,type 同时被 addComponent()、renderCanvas() 的 libDef()、属性面板下拉、optionFor() 用,是个不落库的派生索引——组件对象里存 type,但表里不注册就等于没这类型。 第三,ico 不是组件自己的字段,renderCanvas()(editor.js:106)和 renderLayers()(editor.js:255)都是现查 libDef(c.type).ico,所以改图标只要改 LIB 一格,14 个组件的卡头一起变。

反直觉陷阱:不要以为「数字指标 3×2 比折线 5×5 小,是因为它内容少」。尺寸是按大屏排布给的——4 个 KPI 横排正好铺满第 0 行(mock-data.js:18-21 的 FULL 前四项 x=0/3/6/9, w=3),折线占 5 列是因为 mock-data.js:22 给它留的是 x=0,y=2,w=5,h=5。判断依据是一屏怎么分,不是组件画起来多复杂。

降级说明:libDef()(editor.js:92)查不到类型时返回 LIB[0](数字指标),不是抛错;addComponent()(editor.js:275)同样兜到 LIB[0]。所以 DataTransfer 拿到一个不在表里的字符串,画布上会出现一个 3×2 的数字卡,而不是白屏。这是 file:// / ArkWeb 里 getData 行为不一致时最稳的兜底。

5.2 libDef() 与属性面板改 type:一次切换要收敛三样东西

编辑侧最容易写错的是以为「改图表类型」只改一个字符串。editor.js:229-238 的 change 回调里,type 是唯一带副作用分支的字段:

// views/editor.js - renderProps() 字段绑定(节选,:223-238)
U.$$('[data-p]', box).forEach(function (n) {
  var key = n.dataset.p;
  // ...
  n.addEventListener('change', function () {
    snapshot();
    var v = n.value;
    if (['x', 'y', 'w', 'h', 'carouselInterval'].indexOf(key) >= 0) v = Number(v);
    c[key] = v;
    if (key === 'type') { var d = libDef(c.type); c.title = d.name; c.w = Math.min(c.w, d.w); c.h = Math.min(c.h, d.h); }
    if (key === 'x' || key === 'y' || key === 'w' || key === 'h' || key === 'type' || key === 'accent') renderCanvas();
    else renderProps();
    renderLayers();
  });
});

三个细节值得单独说:第一,收敛用的是 Math.min 而不是直接赋 d.w/d.h——只把过大的尺寸压到新类型上限,用户手工拉宽过的组件不会被强行缩回默认值。 第二,标题被无条件重置成 d.name,所以「今日总营收」改成折线后会变成「折线趋势」,这不是 bug,是避免旧标题和新图形对不上。 第三,type 落在 renderCanvas() 那一组(和 x/y/w/h/accent 同组),而 title/dataSource/animation 只 renderProps()——因为只有前者会改变 DOM 里 ed-item-host 的内容或位置。

反直觉陷阱:不能用「renderProps() 重画一次属性面板」来代替 renderCanvas()。属性面板是右侧那一栏,画布是中间那块;type 变了但画布不重画,卡体里挂的还是旧 Chart 实例(charts.js:388 的 this.type 建完就不变),用户会看到「下拉显示折线,卡里还是柱状」。

降级说明:libDef() 用 || LIB[0] 兜底(editor.js:92),optionFor() 用 default: return {} 兜底(mock-data.js:215)。两处兜底不是重复:前者保证「有东西可画」,后者保证「拿到空 option 时渲染器不炸」——比如 line 渲染器 charts.js:113 用 o.series || [],空对象照样能进 gridLines()。

5.3 双轨分流:htmlRenderers 为什么必须优先判定

引擎侧最容易写错的是把 12 类当成同一套「先建 SVG 再选函数」。charts.js:403-418 的 render() 里,两条路的岔口只有一行:

// lib/charts.js - Chart.prototype.render()(节选,:403-418)
Chart.prototype.render = function () {
  var dom = this.dom;
  var w = Math.max(80, dom.clientWidth || 400), h = Math.max(56, dom.clientHeight || 220);
  this.w = w; this.h = h;
  dom.innerHTML = '';
  var htmlFn = C.htmlRenderers[this.type];
  if (htmlFn) {
    htmlFn(this, dom, this.option);
  } else {
    var svg = U.svgEl('0 0 ' + w + ' ' + h, { class: 'dv-chart-svg', 'data-chart': this.type });
    dom.appendChild(svg); this.svg = svg;
    defs(svg, this.id);
    var fn = C.renderers[this.type];
    if (fn) fn(this, svg, w, h, this.option);
    else svg.appendChild(txt(svg, w / 2, h / 2, '未知图表类型:' + this.type, { 'text-anchor': 'middle', fill: '#ff5d7d' }));
  }
  bindTip(this);
  // ...ResizeObserver 观察
};

三个细节值得单独说:第一,5 类 HTML 组件命中后直接 return 式地跳过 SVG 基建,defs()(charts.js:45 那 8 组渐变 + 发光滤镜)压根不会执行,省掉一整个 <defs> 树。 第二,7 类 SVG 组件全部依赖 U.svgEl() 给出 viewBox,w/h 取 dom.clientWidth/clientHeight 并有 80/56 的下限(charts.js:405)——画布缩到 60% 时图不会塌成 0 宽。 第三,bindTip(this)(charts.js:419)在两条路之后统一绑,所以 KPI 卡和折线图共用同一个 #dv-chart-tip 浮层,tooltip 逻辑只有一份。

反直觉陷阱:不能把判定写成 if (C.renderers[this.type]) 画SVG else 拼HTML。number 同时不在 C.renderers 里、在 C.htmlRenderers 里,反写恰好也能跑;但新增一个「两边都注册」或「两边都没注册」的类型时,反写会静默走错轨。正写的语义是「HTML 是例外,SVG 是默认」,跟 charts.js:417 那句红字兜底刚好配成一套。

降级说明:C.renderers[type] 查空时不是白屏,是往 SVG 中间写一行 未知图表类型:xxx(charts.js:417)——DOM 桩冒烟时我就是靠这行红字定位到 optionFor 漏抄的 case。真实浏览器里 Arc/ArkWeb 对 U.svg() 创建的命名空间节点支持一致,但本机没有真机,这一支未在 ArkWeb 实跑,标「待补」。

5.4 optionFor() 12 个 case:同一张图每次刷新为什么数不一样

数据侧最容易写错的是以为「组件存了数据」。editor.js:277-285 建的组件里只有 base/trend/unit 这类参数,真正的点位全在 mock-data.js:201-217 现算:

// lib/mock-data.js - optionFor()(节选,:201-217)
M.optionFor = function (c) {
  switch (c.type) {
    case 'number': return M.numberOption(c);
    case 'line': return M.lineOption(c);
    case 'bar': return M.barOption(c);
    case 'pie': return M.pieOption(c);
    case 'radar': return M.radarOption();
    case 'gauge': return M.gaugeOption(c);
    case 'progress': return M.progressOption();
    case 'map': return M.mapOption();
    case 'table': return M.tableOption();
    case 'carousel': return M.carouselOption();
    case 'scatter': return M.scatterOption();
    case 'text': return M.textOption(c);
    default: return {};
  }
};

三个细节值得单独说:第一,12 个 case 与 LIB 的 12 个 type 严格一一对应,但顺序不同——LIB 按大屏排布习惯排(KPI 在前、散点在末),optionFor 按渲染复杂度排,两边靠字符串对齐,不靠下标。 第二,radarOption()、progressOption()、mapOption()、tableOption()、carouselOption()、scatterOption() 六个函数不接 c 参数(mock-data.js:133,144,162,174,187,196),它们的形状完全由数据层决定,属性面板里那些 seriesNames/doughnut/horizontal 对这几类不起作用。 第三,wave()(mock-data.js:113)里读的是模块级 T,而 T 只由 M.tick()(mock-data.js:13)递增;C.refreshAll()(charts.js:458)在 advance !== false 时先 tick() 再逐个 refresh()——所以「图会动」是逻辑时钟驱动的,不是 Math.random() 每帧乱跳。

反直觉陷阱:不能用「组件对象的某个字段没变」判断图该不该重画。numberOption()(mock-data.js:153-160)里 delta = Math.sin(T/3 + c.x)*base*0.012,同一个 T 下 x 不同的两个 KPI 值也不同;位置本身就是算式的输入。这也是为什么 editor.js:235 把 x/y 归进「要 renderCanvas()」那一组。

降级说明:default: return {}(mock-data.js:215)保证未知类型拿到空 option 而不抛 undefined.series;Chart.prototype.refresh()(charts.js:429-432)用 if (!this.component) return this 跳过没有绑定组件的实例。真实项目里这一层会被 DV.request 的 HTTP/WebSocket 数据替换,但本机无真实后端,未实跑联调,标「待补」。

5.5 Chart 实例生命周期:注册、观察、销毁三步都藏在 charts.js

生命周期最容易写错的是以为「innerHTML = '' 就等于销毁」。charts.js:9 的 registry 是一张全局表,实例不会随 DOM 消失:

// lib/charts.js - 实例与对外 API(节选,:388-392, :434-455, :471)
function Chart(dom, type) {
  this.dom = dom; this.type = type; this.id = 'dvchart-' + (++seq);
  this.option = {}; this.component = null; this._tipBound = false;
  this._ro = null; this.destroyed = false;
}
Chart.prototype.destroy = function () {
  this.destroyed = true;
  if (this._ro) { this._ro.disconnect(); this._ro = null; }
  this.dom.innerHTML = '';
  var i = registry.indexOf(this); if (i >= 0) registry.splice(i, 1);
};
C.init = function (dom, type) {
  if (!dom) return null;
  var old = registry.filter(function (c) { return c.dom === dom; })[0];
  if (old) old.destroy();
  var inst = new Chart(dom, type);
  registry.push(inst);
  return inst;
};
C.mount = function (dom, component) {
  var inst = C.init(dom, component.type);
  inst.component = component;
  inst.setOption(DV.mock.optionFor(component));
  return inst;
};
C.destroyAll = function () { registry.slice().forEach(function (c) { c.destroy(); }); };

三个细节值得单独说:第一,C.init()(charts.js:442-449)会先按 dom 查旧实例并 destroy(),所以同一个 ed-item-host 反复 mount 不会在 registry 里堆出重复项。 第二,destroy() 只做三件事——置 destroyed、断 ResizeObserver、从 registry 摘掉,不清 component;setOption()(charts.js:393-394)开头 if (this.destroyed) return this 让已销毁实例变成静默空操作。 第三,C.useExternalRenderer(renderer)(charts.js:480-483)只把 external 换掉,setOption() 里 if (external && external.render) 会短路掉整套自绘 SVG,业务代码一行不改——这是给真实 ECharts 留的适配位,不是已启用的功能。

反直觉陷阱:不能把 ResizeObserver 当成「浏览器一定有的东西」。charts.js:420 写的是 if (!this._ro && window.ResizeObserver),DOM 桩里若连这个构造函数都不存在,前面 U.debounce 那段虽然被 if 挡住,但别的视图(如 dashboard 的 IntersectionObserver)会先抛。判断「观察器可不可用」要看 window 上有没有,不是看代码里有没有 new。

降级说明:C.refreshAll()(charts.js:459)对 !c.dom.isConnected 的实例直接 destroy(),等于给「DOM 被清空但没走 destroyAll()」补了一层回收;ResizeObserver 缺席时 render() 仍能靠 clientWidth 画出一版静态图,只是不会随容器尺寸变化自动重排。本机无 Electron/Chromium,拖拽缩放后的真实重绘手感未实跑,标「待补」。

6. 我踩过的坑(每一条都有真实报错)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发、DOM 桩冒烟与自检的真实报错和排查记录。

坑1:DOM 桩里 ResizeObserver is not defined。 第一次用宽容型 DOM 桩加载渲染层,视图还没渲染完就停了:

view.render dashboard → IntersectionObserver is not defined
view.render editor    → ResizeObserver is not defined
加载脚本:22/22 · 视图渲染通过:0/13

一开始以为 charts.js:420 那个 if (window.ResizeObserver) 已经挡住了,后来才反应过来:桩里 window 上连这个属性都没有,new ResizeObserver 之前的 IntersectionObserver 在 dashboard 视图先炸了,跟 charts.js 无关。修法是在桩里补齐三个浏览器 API:

IntersectionObserver: function () { this.observe = function () {}; this.unobserve = function () {}; this.disconnect = function () {}; },
ResizeObserver: function () { this.observe = function () {}; this.unobserve = function () {}; this.disconnect = function () {}; },
matchMedia: () => ({ matches: false, addListener() {}, removeListener() {} })

补完 视图渲染通过:13/13。桩缺失不是代码错误,但没补就永远看不到真正的代码错误。

坑2:optionFor 漏一个 case,画布中央出现红字。 抄 12 个分支时少了 scatter,冒烟没抛异常,只是 scatter 卡里画了一行粉色文字:

未知图表类型:scatter

一开始以为是自己把 LIB 的 type 写错了,后来才反应过来:charts.js:417 那句兜底只管「C.renderers 查不到」,而我漏的是数据层——optionFor 返回 {},scatter 渲染器 charts.js:310 拿到 o.points || [] 画了空网格,红字来自另一个手工塞进来的错类型。教训是三张表要一起对:用 Node 逐行打 LIB 的 type 列表与 optionFor 的 case 列表求差集,别靠肉眼。

类型表、渲染表、数据表三者的键必须能被脚本枚举出来比对,不能只靠人眼扫。

坑3:属性面板改了 type,画布没跟着变。 我为了省一次重绘,把 editor.js:235 的 key === 'type' 从 renderCanvas() 那组挪走了,结果下拉显示「折线趋势」、卡里还是旧的柱状图。没有报错,只有一次沉默的不一致:

[DOM 桩] c.type = "line"  # 但 host 里第一个子节点是 <div class="dv-kpi">

一开始以为 setOption() 会自己重读 component.type,后来才反应过来:Chart 的 this.type 在 charts.js:389 构造时定死,refresh()(charts.js:429)只换 option 不换渲染器。改类型等于换实例,只能靠 renderCanvas() 重新 mount。

坑4:grep 复杂正则零输出,行号全靠猜。 想一次抓出所有 U.xxx = function 的行号,写了条带转义的 grep,返回空:

grep: Unknown option 'primary'
(另一条)grep -n "S.VERSION\|function seeded\|..." → 无输出

一开始以为文件里没这些符号,后来才反应过来是沙盒对复杂正则和 --primary 这种以连字符开头的参数处理有问题。改用 Node 逐行 indexOf 打印真实行号,本辑 5 篇所有 文件:行号 才落得实。

行号必须来自可复现的脚本输出,不能来自编辑器的肉眼估算。

坑5:innerHTML = '' 之后 registry 还在涨。 早期 renderCanvas() 先清空 inner 再逐个 mount,连续切几次看板后 DV.charts.count() 一直涨:

[冒烟] C.count() before=14  after switch board ×3 = 56

一开始以为 C.init() 的 old.destroy()(charts.js:444)会兜住,后来才反应过来:dom 已经是全新的 ed-item-host 节点,filter(c.dom === dom) 一个都匹配不上,旧实例只能等 refreshAll() 按 isConnected 回收。修法就是 editor.js:96 把 DV.charts.destroyAll() 提到清空 DOM 之前。先注销再拆 DOM,顺序反了就靠定时器擦屁股。

坑6:getcwd 告警被误判成命令失败。 每条 Bash 都带这么一行,退出码却是 0、stdout 完整:

shell-init: error retrieving current directory: getcwd: cannot access parent directories: Invalid argument
chdir: error retrieving current directory: getcwd: cannot access parent directories: Invalid argument
Exit Code: 0

一开始以为同步脚本没跑,差点重跑一遍 npm run sync:renderer;后来才反应过来是鸿蒙沙盒对用户目录的包装告警,与工程无关。判断命令成败看退出码和 stdout,不看 stderr 里的路径告警。

坑7:以为「12 类组件」等于「12 个文件」。 我按类型去 views/ 下找 line.js、pie.js,一个都没有:

ls electron/ohos/src/views/*.js
# editor.js  dashboards.js  boards.js  ... 没有任何以图表类型命名的文件

一开始以为漏了文件,后来才反应过来:12 类全在 charts.js 一个文件里,靠 C.renderers / C.htmlRenderers 两张对象表挂着,类型是对象键,不是模块边界。这也解释了为什么 index.html:41 只引一个 editor.js,画布却能画 12 种东西。

能跑不等于能复用:把类型做成文件会让 index.html 多 12 个 <script>,做成对象键才让「换渲染器」只改 charts.js:480 一行。

7. 现在怎么用:从 Demo 到依赖

本工程没有 npm 运行时依赖,接入方式就是把唯一源挂进三端入口。index.html:29-36 的顺序不能动:utils → mock-data → store → charts → datav → request → bridge → scenarios,charts.js 必须在 editor.js 之前,否则 DV.charts.mount 是 undefined。

# 工程根目录(唯一源在 electron/ohos/src/)
cd /storage/Users/currentUser/Documents/DevEcoStudioProjects/electron-ohos-datav

# 同步唯一源 → 根 src/ 镜像 → 鸿蒙 rawfile/(本轮未改动代码,仅说明既有链路)
npm run sync:renderer

# 三套自检 + 静态预览
npm run check          # 共 26 项,通过 26 项,失败 0 项(JS 语法 38/38、脚本引用 23 个、13 路由)
npm run ohos:check     # 共 49 项 · 通过 49 · 失败 0(三处逐字节一致)
npm run serve          # 浏览器打开 /src/index.html#/editor

测试数量交代:本轮没有新增单元测试,验证来自 npm run check 26 项、npm run ohos:check 49 项,以及 Node DOM 桩对 13 个视图 render 的冒烟(加载脚本:22/22 · 视图渲染通过:13/13 · 新增错误:0)。真机结果标「待补」,没有 DevEco build 号可写。

免得读者踩到同一堵墙:

  • 本机无 DevEco SDK、无真机、无 Electron/Chromium,ArkWeb 下 U.svg() 节点、innerHTML 差异、拖拽手感全部未实跑,只保证 DOM 桩不抛异常。
  • LIB / C.renderers + C.htmlRenderers / M.optionFor 是三张独立的表,新增类型要同时改三处;只在 LIB 加一格会画出 未知图表类型:xxx。
  • w/h 是 12×14 栅格的格数,不是像素;editor.js:350 的 designWidth/designHeight 才是像素,两者别混用。
  • C.useExternalRenderer() 是适配位,不是已接入的 ECharts;charts.js:3 注释里写的是「生产环境可平滑替换」,本仓库没有引入 echarts 依赖。
  • 组件对象不存渲染函数、不存 icon、不存真实数据,JSON.stringify(c) 能完整展示;谁要是往里塞了函数,editor.js:218 的只读 JSON 和 U.deepClone()(utils.js:72 走 JSON.parse(JSON.stringify()))会一起把它吞掉。
  • optionFor() 的数据来自逻辑时钟 T(mock-data.js:13),不是真实接口;本机无后端,HTTP/WebSocket 联调未实跑。

它不是一个渲染好的控件货架,是一份被三个模块共同遵守的类型契约:编辑器拿它查默认占位,图表引擎拿它选绘制轨,数据层拿它决定 option 的形状。三张表对齐的那一刻,一个 type 字符串才有意义;任何一张表缺一个键,组件就退化成一个带标题的空框。零依赖、能跑在 file:// 下、能被整份换成 ECharts——这些不是 separate 的技巧,都是「类型只是索引」这一个决定的副产品。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐