@hy-bricks/canvas 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +142 -0
- package/README.md +2 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +49 -0
- package/dist/index.mjs +1 -1
- package/package.json +4 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# @hy-bricks/canvas
|
|
2
|
+
|
|
3
|
+
## [0.4.2] - 2026-05-28 · devtools 强化(配套升级)
|
|
4
|
+
|
|
5
|
+
跟 `@hy-bricks/devtools` 0.4.2 同步。canvas 本次给 runtime renderer 加诊断 handle 自动注册,
|
|
6
|
+
让 BoardTile / portal-ui 主题页等"无 designer"场景在 devtools 也能看到实例计数 / 渲染开销 / 错误 / 事件。
|
|
7
|
+
**零 BREAKING**,从 0.4.x 任意版本直接升 0.4.2 安全。
|
|
8
|
+
|
|
9
|
+
### ✨ 新特性(business 侧可见的部分)
|
|
10
|
+
|
|
11
|
+
- `HyperCardPageRenderer` mount 时**自动**把诊断 handle 注册到全局,devtools 浮窗
|
|
12
|
+
自动捕获到所有运行时 canvasId(无需 host 手动调 API)
|
|
13
|
+
- `createRenderScheduler.getStats()` 暴露 `pending / mounting / mounted / disposing`
|
|
14
|
+
实时计数(O(1))
|
|
15
|
+
|
|
16
|
+
### 内部新增(devtools 消费)
|
|
17
|
+
|
|
18
|
+
`@hy-bricks/canvas` 新增 `RendererDiagnosticsHandle` 接口 + registry,**业务侧不应直接用**:
|
|
19
|
+
|
|
20
|
+
- `registerRendererDiagnostics` / `unregisterRendererDiagnostics` /
|
|
21
|
+
`getRendererDiagnostics` / `subscribeRendererDiagnostics`
|
|
22
|
+
- `RendererDiagnosticsHandle` 接口:`getSchedulerStats / listRuntimeInstances /
|
|
23
|
+
getInstanceTimings / getLayoutIssues`
|
|
24
|
+
|
|
25
|
+
详见 [根 CHANGELOG.md](../../CHANGELOG.md) §0.4.2。
|
|
26
|
+
|
|
27
|
+
### 业务侧升级
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pnpm up @hy-bricks/canvas@0.4.2
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
零代码改动。
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## [0.4.1] - 2026-05-27
|
|
38
|
+
|
|
39
|
+
文档补完 — 0.4.0 的发版说明现在 npm 包页面可见。代码无变更。
|
|
40
|
+
从 0.4.0 升上来可跳过。
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## [0.4.0] - 2026-05-27 · 组件 mounted 里立即可订阅
|
|
45
|
+
|
|
46
|
+
### ✨ 新特性
|
|
47
|
+
|
|
48
|
+
组件作者可在 `mounted` 里**直接调** `__HYPERCARD__.runtime.on(this.hcInstanceId, ...)` 立即生效,不再需要 nextTick / microtask 等一拍。
|
|
49
|
+
|
|
50
|
+
每个组件实例可读 3 个 SDK 注入 prop:
|
|
51
|
+
|
|
52
|
+
| Prop | 含义 |
|
|
53
|
+
|---|---|
|
|
54
|
+
| `this.hcInstanceId` | 实例 ID |
|
|
55
|
+
| `this.hcCanvasId` | 所属画布 ID |
|
|
56
|
+
| `this.hcComponentId` | 组件源 ID |
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
// 组件源码 component.js
|
|
60
|
+
export default {
|
|
61
|
+
mounted() {
|
|
62
|
+
console.log('我是谁', this.hcInstanceId, this.hcCanvasId)
|
|
63
|
+
|
|
64
|
+
// ✅ 立即订阅,不再要等
|
|
65
|
+
__HYPERCARD__.runtime.on(this.hcInstanceId, 'click', (payload) => {
|
|
66
|
+
// ...
|
|
67
|
+
})
|
|
68
|
+
|
|
69
|
+
// ✅ 立即拿到 handle
|
|
70
|
+
const handle = __HYPERCARD__.canvases
|
|
71
|
+
.get(this.hcCanvasId)
|
|
72
|
+
?.getInstance(this.hcInstanceId)
|
|
73
|
+
},
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### ⚠ BREAKING — host 升级前 audit
|
|
78
|
+
|
|
79
|
+
`onInstanceLifecycle('instance:ready')` / `handle.on('instance:ready')` 回调被调时,**子组件 DOM 还没渲染**,`vm.$el` 是 `null`。
|
|
80
|
+
|
|
81
|
+
**修法**(回调内访问 DOM 的话):
|
|
82
|
+
|
|
83
|
+
```js
|
|
84
|
+
// ❌ 不能直接访问 $el
|
|
85
|
+
onInstanceLifecycle('instance:ready', ({ instance }) => {
|
|
86
|
+
instance.$el.querySelector(...) // null,报错
|
|
87
|
+
})
|
|
88
|
+
|
|
89
|
+
// ✅ 等下一帧 DOM 渲染完
|
|
90
|
+
onInstanceLifecycle('instance:ready', ({ instance }) => {
|
|
91
|
+
nextTick(() => {
|
|
92
|
+
instance.$el.querySelector(...)
|
|
93
|
+
})
|
|
94
|
+
})
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### 升级 checklist
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
grep -rn "instance:ready\|onInstanceLifecycle\|getInstanceReady" src/
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
每处看回调内是否访问 `vm.$el` / DOM。
|
|
104
|
+
- 没访问 → `npm install @hy-bricks/{core,canvas,editor,devtools}@^0.4.0` 透明升
|
|
105
|
+
- 访问了 → 改 `nextTick`
|
|
106
|
+
|
|
107
|
+
### 命名保留
|
|
108
|
+
|
|
109
|
+
组件作者**不要**用这 3 个名字声明你自己的 prop(同名会被 SDK 注入覆盖):
|
|
110
|
+
`hcInstanceId` / `hcCanvasId` / `hcComponentId`。
|
|
111
|
+
|
|
112
|
+
之前的保留 prop `hcCustomValues` 不变。
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 0.3.0
|
|
117
|
+
|
|
118
|
+
### Minor Changes
|
|
119
|
+
|
|
120
|
+
- 0.3.0 渲染核心 · mount-ready 信号 + cache 精确读 API
|
|
121
|
+
|
|
122
|
+
**主题**:`RenderScheduler` 渐进 mount 下,SDK 第一次给出"组件挂好"信号(per-canvas 隔离的 event + Promise + cache 精确读 API)。host 替掉 `setTimeout(300)` / `mountConcurrency:50` / `replayFromCache` 全表遍历兜底。
|
|
123
|
+
|
|
124
|
+
**新 API**:
|
|
125
|
+
- `@hy-bricks/core`:`onInstanceLifecycle("instance:ready" | "instance:unmounted", cb)` — 模块级 lifecycle emitter,跨 canvas 共享,payload `{ canvasId, instanceId }`
|
|
126
|
+
- `@hy-bricks/canvas · CanvasHandle`:
|
|
127
|
+
- `handle.on("instance:ready" | "instance:unmounted", cb)` — per-canvas 自动过滤,payload 只透 `instanceId`
|
|
128
|
+
- `handle.getInstanceReady(instanceId): Promise<void>` — 已挂立即 resolved / 未挂等 emit / `handle.dispose()` 时 reject `HandleDisposedError`
|
|
129
|
+
- `handle.getInstanceRuntime(instanceId)` — 返**运行时 vm handle**(`ComponentInstanceHandle`),给 host 调 `setDataInput / call / emit` 用;跟 `getInstance(id)` 返 PageInstance snapshot 区分
|
|
130
|
+
- `handle.getCachedBySourceId(sourceId, params?)` — cache 精确读快照,plain object(不返 reactive)
|
|
131
|
+
- `HandleDisposedError` 具名 error class(host 可 `instanceof` 判)
|
|
132
|
+
- `handle.dispose()` 终态 guard:dispose 后所有入口 no-op / reject / null,防 listener 泄漏 + pending 永挂
|
|
133
|
+
- `@hy-bricks/canvas · HyperCardPageRendererExpose.data.getCachedBySourceId(sourceId, params?)` 同款
|
|
134
|
+
|
|
135
|
+
**边界**(摸底备忘 §1):SDK 只补"信号 + 暴露 API",**不**替 host 自动 push / replay / 重拉 — 数据治理仍归 host。D5.4 §R6 "cache 保留 + 不自动 replay,host 手动 invalidate" 合约**不变**。
|
|
136
|
+
|
|
137
|
+
**host 升级(不强制)**:
|
|
138
|
+
- 0.2.0 → 0.3.0 **不破坏现有代码**;不用 ready 信号当 0.3.0 没加
|
|
139
|
+
- 用了就简化:`handle.on("instance:ready", id => { const c = handle.getCachedBySourceId(src); if (c?.status === "success") handle.getInstanceRuntime(id)?.setDataInput?.(key, c.value) })`
|
|
140
|
+
- workaround(`replayFromCache` / `mountConcurrency:50` / 首屏 reload)**可保留**,SDK 不强制删
|
|
141
|
+
|
|
142
|
+
详见 `docs/v1/frontend-sdk/20260523-1648-claude-渲染核心-挂载就绪信号-实施稿-rev1.md`。
|
package/README.md
CHANGED
|
@@ -6,6 +6,8 @@
|
|
|
6
6
|
[](./LICENSE)
|
|
7
7
|
[](https://vuejs.org/)
|
|
8
8
|
|
|
9
|
+
> ⚠️ **0.4.0 BREAKING** ── `handle.on('instance:ready')` / `onInstanceLifecycle('instance:ready')` 回调被调时,子组件 DOM 还没渲染。回调内访问 `vm.$el` 会拿 `null`,需改 `nextTick(() => vm.$el...)`。详 [CHANGELOG](./CHANGELOG.md)。
|
|
10
|
+
|
|
9
11
|
---
|
|
10
12
|
|
|
11
13
|
## 简介
|