docs: complete advanced II custom UI documentation

This commit is contained in:
AncTe committed 2026-11-15 18:48:28 +08:00
1 parent e25ef39481
commit 5db2cefb39
127 files changed
+22831 -13

No files matched your search

+1
View File
@@ -590,6 +590,7 @@ Plans:
- [x] 10-31-PLAN.md — 两篇补写内容的独立读者审阅(沿用高级 I 人格)→ 问题清单 → 迭代修正(≤3 轮)→ 复审清零
- [x] 10-32-PLAN.md — 两篇补写内容的用户主导修订循环 → 用户确认 → 最终格式 / 构建 / SUMMARY 收尾
- [x] 10-42-PLAN.md — VitePress 内嵌自定义渲染器 demo 最小 POC(config alias / dedupe / isCustomElement / vue-jsx + 包装组件 + 渲染基础与 UISystem 两个 demo + 不进导航的 POC 页)
- [x] 10-54-PLAN.md — 用户审阅与收尾(19 篇非示例文档已审阅;示例 1-6 标记待审阅;文档审阅计划完成,带待审阅项)
**说明:** 每篇中级教程遵循 `10-CONTEXT.md` D-21..D-44 的逐篇要点与阅读顺序(4/8/9/3)。**旧内容删除已并入本批(D-04,Wave 0 / 10-01)**:删除 `docs/guide/*`、`docs/dev/*`、`docs/logger/*`、`docs/api/*` 与首页 `docs/index.md`,并清理 `docs/.vitepress/config.ts` 的旧 `nav`/`sidebar` 键。文档改动为 `docs/intermediate/*.md`(新增)、`docs/.vitepress/config.ts` 与 `docs/.vitepress/api.ts`(缺失目录守卫,保留按包生成机制)。构建命令 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`;`init.ts` 在 `docs/api/` 缺失时安全跳过。本机 PowerShell 禁止 `pnpm.ps1`,命令经 `cmd /c "..."` 执行。
+8 -7
View File
@@ -4,10 +4,10 @@ milestone: v1.0
current_phase: 10
current_phase_name: 文档重构
status: executing
stopped_at: Phase 10 进行中:中级 24 篇 + 高级 I 9 篇 + 高级 II 10 篇已收尾;10-06/10-11/10-12 待补
last_updated: "2026-10-29T00:00:00.000Z"
last_activity: 2026-10-29
last_activity_desc: 10-42 文档内嵌渲染 demo POC 完成并经用户人工验证
stopped_at: Phase 10 进行中:10-54 文档审阅计划已收尾(非示例文档完成,示例 1-6 待审阅);10-06/10-11/10-12 待补
last_updated: "2026-11-15T00:00:00.000Z"
last_activity: 2026-11-15
last_activity_desc: 10-54 用户审阅计划收尾;非示例文档完成,示例 1-6 标记待审阅
state_head: dbbcf533dce2f22078a82d26817f36b85865da62
progress:
total_phases: 10
@@ -29,11 +29,11 @@ See: .planning/PROJECT.md (updated 2026-09-17)
## Current Position
Phase: 10 (文档重构) — IN PROGRESS
Plan: 第一批(中级 24 篇)、第二批(高级 I 7 篇)、第三批(高级 II 10 篇)、第四批(高级 I 补写 Mover/FaceHandler 2 篇)已收尾;10-42 文档内嵌渲染 demo POC 已完成并经用户验证;10-06 / 10-11 / 10-12 待补
Plan: 第一批(中级 24 篇)、第二批(高级 I 7 篇)、第三批(高级 II 10 篇)、第四批(高级 I 补写 Mover/FaceHandler 2 篇)已收尾;10-42 文档内嵌渲染 demo POC 已完成并经用户验证;10-54 文档审阅计划已收尾(非示例文档完成,示例 1-6 待审阅);10-06 / 10-11 / 10-12 待补
Status: In Progress
Last activity: 2026-10-29 — 10-42 文档内嵌渲染 demo POC 完成并经用户确认(人工验证通过)
Last activity: 2026-11-15 — 10-54 用户审阅计划收尾;非示例文档完成,示例 1-6 标记待审阅
Progress: Phase 10 · 29/32 plans(中级 + 高级 I 9 篇 + 高级 II 已收尾;总览 / 初级 / 高级 III / API / Agent 参考仍待推进)(另:10-42 文档内嵌渲染 demo POC 已完成并经用户验证,Phase 10 的计数收口仍归 10-41)
Progress: Phase 10 · 29/32 plans(中级 + 高级 I 9 篇 + 高级 II 已收尾;总览 / 初级 / 高级 III / API / Agent 参考仍待推进)(另:10-42 文档内嵌渲染 demo POC 已完成并经用户验证,10-54 文档审阅计划已收尾但示例 1-6 待审阅,Phase 10 的计数收口仍归 10-41)
## Performance Metrics
@@ -268,6 +268,7 @@ Recent decisions affecting current work:
- Phase 10 added (2026-10-14): 文档重构(重构过老、结构不佳、新人难懂的项目文档,面向新人/不懂代码的作者/有基础作者等多背景读者提供分层指南,并专门为 AI Agent 编写参考文档);Depends on Phase 9
- Phase 10 第一批(中级教程 24 篇 + 旧内容清空 + 站点注册 + D-09 修订 + 读者/用户修订循环)已完成并收尾(2026-10-20);第二批(高级 I 7 篇 + 站点注册 + 独立读者审阅 + 用户 6 轮修订)已完成并经用户确认收尾(2026-10-20);第三批(高级 II 10 篇 + 站点注册 + 独立读者审阅 + 用户 3 轮修订)已完成并经用户确认收尾(2026-10-23);第四批(高级 I 补写 Mover + FaceHandler 2 篇 + 注册 + 读者/用户修订)已完成并经用户确认收尾(2026-10-24)。遗留 `10-06` / `10-11` / `10-12` 缺独立 SUMMARY,其范围已被后续修订覆盖
- Phase 10 增量 10-42(2026-10-29):VitePress 内嵌自定义渲染器 demo 最小 POC(DOM 包装组件动态 import 引擎 + 渲染基础 / UISystem 两个 demo + 不进导航 POC 页 + docs 局部 tsconfig + ESLint docs override);用户人工验证通过(原话 `pass`),页面 `docs/poc/render-demo.md` 与命名暂时保留;未做 fence 插件 / 正式渲染端文档批次 / client-base 组件 / nav·sidebar 注册;无源码改动、无 commit
- Phase 10 增量 10-54(2026-11-15):用户审阅计划收尾;19 篇非示例文档已审阅,6 篇示例保留现状并标记待审阅;文档审阅计划标记为完成(带待审阅项);未改源码/demo,未 commit;详见 `10-54-SUMMARY.md`
### Pending Todos
@@ -0,0 +1,372 @@
---
phase: 10-docs-restructure
plan: 43
type: execute
wave: 1
depends_on: []
files_modified:
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- docs/tsconfig.json
- docs/.vitepress/config.ts
- docs/advanced/ii/index.md
- docs/advanced/index.md
- docs/advanced/ii/ui/ui-template.md
- docs/advanced/ii/ui/ui-template-ts.md
- docs/advanced/ii/ui/container-and-coordinates.md
- docs/advanced/ii/ui/basic-shapes.md
- docs/advanced/ii/ui/curves-and-paths.md
- docs/advanced/ii/ui/text.md
- docs/.vitepress/components/demos/ui/template-demo.tsx
- docs/.vitepress/components/demos/ui/container-demo.tsx
- docs/.vitepress/components/demos/ui/shapes-demo.tsx
- docs/.vitepress/components/demos/ui/curves-demo.tsx
- docs/.vitepress/components/demos/ui/text-demo.tsx
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 78000
raw_tokens: 48000
tasks: 7
confidence: low
must_haves:
truths:
- "新增子分组下先落地 6 篇正文(Part 0 两篇 + Part 1 前四篇),每篇单 `#` H1、按 D-84 的理解顺序组织、末尾有 `## 边界与注意`;篇幅由内容决定,不套模板、不留 `[待补]` 占位"
- "所有 UI 示例是完整、结构正确的 TSX 组件/文件级片段(`defineComponent` + `SetupComponentOptions` + 返回 render 函数),Props 一律 `extends IGameUIPropsBase, DefaultProps`,`props` 数组含 `controller` / `instance` / `state`;属性名全程 camelCase;条件写 `hidden` 或三元、循环写 `.map()`;`key` 只在会重排/增删且需要保留身份时出现"
- "示例里的容器自定义标签只出现 `container-custom` 这一种写法(`docs/.vitepress/config.ts` 的 `custom` 数组同时放行 `container-custom` 与 `custom-container`,后者是运行时当前注册名);正文不出现渲染器类名、渲染器初始化、标签注册、以及以 core 开头的命名空间;不出现 Thumbnail / Tip;`icon` / `winskin` / `map-render` 只作占位"
- "5 个 live demo(template / container / shapes / curves / text)都是 `.tsx` 默认导出组件,无 DOM 属性;其中 4 个只 import vue 与元素标签(不得出现任何 `@motajs/*` / `@user/*`),唯一例外是 `text-demo.tsx` 可以 `import { Font } from '@motajs/render'`(元素层类,不是渲染器)且必须用**位置参数**构造 `new Font('Verdana', 32, 'px', 700)`(签名 `(family, size, sizeUnit, weight, italic)`),不得调用 `Font.defaults`;页面用 `<ClientOnly>` 包裹 `RenderDemo` 且 loader 为 `() => import('...')`,文档正文不展示 demo 源码"
- "`docs/tsconfig.json` 的 `include` 增加 `.vitepress/**/*.tsx`(其余字段原样),`cmd /c \"pnpm exec vue-tsc --noEmit -p docs/tsconfig.json\"` 中路径以 `docs/` 开头且含 `error TS` 的行为 0"
- "侧边栏在高级 II 分组内新增嵌套子分组,只登记已存在的 6 篇;`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom` 与 `custom-container`(前者是文档写法,后者是运行时当前注册名);`cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\"` 通过、输出含 `build complete`、无 dead link"
- "`docs/advanced/ii/index.md` 与 `docs/advanced/index.md` 不再声称本层只写数据端 / 渲染端未完工,并给出指向新子分组的一句入口;两页**都**写出同一条性能边界(「高级 II 的性能篇讲 UI 系统的缓存与显示策略,引擎级性能仍属高级 III」);`docs/advanced/ii/index.md` 的「本层一共十篇」改写为「十篇数据端 + 27 篇 UI 子分组」,并列明「Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端」"
- "`cmd /c \"pnpm exec prettier --check docs/advanced/ii/ui docs/.vitepress/components/demos/ui\"` 通过;`cmd /c \"pnpm exec eslint docs/.vitepress/components/demos/ui\"` 为 0 error / 0 warning"
- "未改 `packages/` / `packages-user/` / `src/`、未改 `10-01`..`10-42` 的计划与 POC 记录、未改既有 JSDoc/注释;本计划不产生任何 git commit"
artifacts:
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表 + 用户确认标记 + 参考清单哈希基线 + 写作硬规则 + 门禁记录区)"
- "docs/advanced/ii/ui/ui-template.md、ui-template-ts.md、container-and-coordinates.md、basic-shapes.md、curves-and-paths.md、text.md"
- "docs/.vitepress/components/demos/ui/template-demo.tsx、container-demo.tsx、shapes-demo.tsx、curves-demo.tsx、text-demo.tsx"
- "docs/tsconfig.json(include 增加 `.vitepress/**/*.tsx`)"
- "docs/.vitepress/config.ts(`custom` 数组追加 `container-custom`;高级 II 分组内新增嵌套子分组与两个 Part 分组)"
- "docs/advanced/ii/index.md、docs/advanced/index.md(措辞修正 + 子分组入口)"
key_links:
- "页面 → live:`.md` 里 `import RenderDemo from '../../../.vitepress/components/renderDemo.vue'` + `() => import('../../../.vitepress/components/demos/ui/xxx-demo.tsx')`;demo 由包装组件在 `onMounted` 动态 import,因此 SSR 预渲染不触碰 `document`"
- "demo → 渲染树:demo 只写 vue 的 `ref` / `computed` 与元素标签,标签由 docs 的 `isCustomElement` 放行、由 `vuejsx` 编译;属性名 camelCase 才能命中元素的属性处理。`text-demo` 是唯一允许从 `@motajs/render` 取元素层类 `Font` 的 demo——那是元素,不是渲染器,仍不创建渲染器、不初始化画布;其余 4 个 demo 必须零引擎 import"
- "侧边栏 → 页面:每条 `link` 必须是 `docs/advanced/ii/ui/` 下已存在的文件名,否则构建报 dead link;因此登记与建页在同一任务内完成"
- "`docs/tsconfig.json` → vue-tsc:`.tsx` 进入 include 后 demo 才参与类型检查;根 `tsconfig.json` 已为 `jsx: preserve` + `jsxImportSource: vue`,docs 配置沿用即可"
- "跨页引用时序:目标页已存在时才写 `./xxx.md` 链接;目标页要到后续批次才创建时只写纯文本(如「第 8 篇『层级、变换与性能』」「第 17 篇『内置组件:文本与输入』」),由创建该页的批次回填链接。本计划第 3 / 4 / 6 篇因此都含纯文本前瞻引用,不含前向 markdown 链接"
---
> **编号变更(2026-11-01):** 本文件中的旧 10-49 / 10-50 分工已重排,完整映射见文末「编号变更」小节。
<scope_justification>
本计划 7 个任务、16 个 `files_modified`,超出「2–3 任务 / ≤ 8 文件」的默认上限,仍保持单计划:
- 任务拆分的依据是「每个任务能独立验证」:Task 0 是用户关卡,Task 1 是基础设施(改完即可构建),Task 2/Task 3/Task 4 各写 2 篇正文 + 对应 demo + 侧边栏登记,Task 5 是六类门禁收口,Task 6 是用户 live 目视。再合并会让「4 篇正文 + 4 个 demo + 侧边栏 + 全量门禁」压成一个不可独立验证的巨块。
- 16 个文件里 6 个是正文、5 个是 demo、2 个是导览修正、1 个是 docs 配置、1 个是侧边栏、1 个是本批记录文件。它们共享同一套写作规则、同一份参考清单哈希与同一次构建,切片只会让记录与门禁跨计划重复。
- 用户原始建议把 Part 0 + Part 1 八篇放在 10-43;实测这会让单计划吃下 8 篇正文 + 7 个 demo + 4 个基础设施文件,单次执行超出智能区。本计划把 Part 1 后两篇(图片与最小纹理、层级变换与性能)移到 10-44,与 Part 2 合并为 6 篇,保持「每计划 ≤ 8 篇」的约束;批次边界与依赖关系已在 10-44 的 `<context>` 中说明。
- 成本约占单计划预算的 78%(`estimate.tokens` 78,000 / 单计划预算 100,000;`raw_tokens` 48,000 × 校准系数),无跨计划依赖(`depends_on: []`、`wave: 1`)。
不因篇幅删内容:6 篇正文、5 个 live、导览修正、参考清单哈希校验、六类门禁、用户 live 目视全部保留。
</scope_justification>
<objective>
在高级 II 下开出子分组「自定义 UI 与渲染」,落地其中第一组正文(Part 0 起步两篇 + Part 1 元素与布局前四篇),并把这一批的写作基础设施一次建好:docs 的 `.tsx` 类型入口、侧边栏嵌套子分组、live demo 目录约定、参考清单哈希基线、以及高级 II / 高级总导览的措辞修正。
Purpose: 读者第一次写 UI 需要一条从「复制模板 → 打开面板」开始的直线路径,并且作者的例子必须全部是可运行的 TSX;文档站的侧边栏、类型检查与 live 机制必须先支撑得住这批页面,后续四个批次才能只做加法。
Output: 6 篇正文、5 个 `.tsx` live demo、`10-CUSTOM-UI-NOTES.md` 记录文件、`docs/tsconfig.json` 与侧边栏(含 `custom` 数组放行 `container-custom`)的加法式改动、两处导览措辞修正。**不改源码、不改已有正文、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md
@.planning/phases/10-docs-restructure/10-42-PLAN.md
@.planning/phases/10-docs-restructure/10-42-POC-NOTES.md
@docs/.vitepress/config.ts
@docs/tsconfig.json
@docs/.vitepress/components/renderDemo.vue
@docs/poc/render-demo.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
**本批定位(D-10 / D-11 / D-13 / D-14):**
- 这是 Phase 10 的又一次增量派发:**只新增 10-43..10-49 七个计划**(其中 10-48 只做独立读者审阅、10-49 做用户主导修订与收尾),不改 `10-01`..`10-42`,不重规划其它批次,不补 `10-06` / `10-11` / `10-12`。
- 27 篇按 6 个内容计划推进:10-43(基础设施 + 6 篇)、10-44(Part 1 后两篇 + Part 2 四篇)、10-45(Part 3 四篇)、10-46(Part 4 五篇)、10-47(Part 5 六篇);写作完成后 10-48(独立读者审阅)、10-49(用户主导修订 + 最终门禁 + 落位评估 + 收尾)。
- **Task 0 是硬关卡**:先汇报本计划要写什么、页面文件名 / 侧边栏显示名 / demo 文件与组件名 / 落点 / 参考文件清单与哈希策略,等用户明确回复「可以执行」;未收到前不得改任何文件、不得派发修改子代理。
- 页面文件名、侧边栏显示名、子分组名、demo 文件名与组件名都属 D-13,**必须先经用户同意**;本计划里出现的名字一律标注为「建议值,待 Task 0 确认」。
- 越界内容(源码修改、既有正文改写、nav 新增顶层入口、fence 插件)只记录、不实施(D-14)。
**本批写作硬规则(全批一致,逐条来自锁定决策与 `10-CUSTOM-UI-RESEARCH.md`):**
- 目标读者:完全没写过 UI、不知道 canvas 是什么的作者。只讲写 UI 必需的 Vue 概念(响应式、props、条件、循环、组件、slots、attrs);不讲作者不需要调用的初始化。
- 示例一律 TSX,不用单文件组件示例;条件写 `hidden` 或三元,循环写 `.map()`;`key` 只在列表会重排 / 插入 / 删除且需要保留元素身份时加(`dev.md:122`),不为规避重挂载问题加 `key`(`dev.md:123`)。
- `hidden` = 不显示、不交互:保留元素与状态,跳过绘制与命中;三元会创建 / 销毁并重置状态,只在「必须真正不存在」「需要重置状态或生命周期」「子树很重且长期不用」时用。
- 属性名一律 camelCase(`fillStyle` / `strokeStyle` / `lineWidth` / `anchorX` / `zIndex`)。容器自定义标签全批只用 `container-custom` 这一种写法。
- UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`,`props` 数组至少含 `controller` / `instance` / `state`。
- `update:xxx` 只作为 `v-model:xxx` 的使用说明出现,不教读者手动监听对应的事件属性。
- 组件内按键用 `useKey(props.state.hotkey.system)!` 非空断言,不加多余类型守卫。
- 正文不出现渲染器类名、渲染器初始化、标签注册;不出现以 core 开头的命名空间(当它不存在,live 跑不起来也保留内容)。
- 不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位,不展开内部。
- 正文不写「源码里怎么实现」的叙述、不写仓库行号引用;跨页引用:**目标页已存在时**写 `./xxx.md#标题`,**目标页要到后续批次才创建时**先写纯文本(如「第 8 篇『层级、变换与性能』」),由创建该页的批次回填链接——绝不在目标页存在前写 markdown 链接,否则构建报 dead link。
- 代码块是完整、结构正确的文件 / 类 / 函数级片段(D-62 / D-70 / D-87),注释按 D-65 尽量写;编辑器产出的内容(配置、生成物)不手写(D-73)。
- 篇幅由内容决定(D-88);一节只回答一个问题,认知跳跃处补 1–2 句过渡(D-86);按「问题 / 场景 → 系统模型 → 机制与理由 → 接口 / 用法 → 完整示例 → 边界」组织(D-84)。单 `#` H1,`## 边界与注意` 收尾(D-61)。
- live 一律 `RenderDemo` + `.tsx` demo:页面 `<ClientOnly>` 包裹、loader 写 `() =&gt; import('...')`、正文不展示 demo 源码;跑不起来不阻塞、不删内容。
- 文件 CRLF;每篇写完后跑 prettier(D-45)。
**参考文件与哈希(写作前必查,变化即停):** `10-CUSTOM-UI-RESEARCH.md` 的 `## Reference Manifest` 已给出 A–F 各表在基线 `b94b4c3` 的 `git rev-parse HEAD:<path>` 哈希。本计划只用其中与元素属性、TSX 属性、UI 栈、live 基础设施相关的条目;Task 1 用 `git hash-object -- <path>` 逐条核对并把结果写进 NOTES。**任何一条哈希与 Manifest 不一致,或 `git status --porcelain -- <path>` 显示工作树已改,立即停下向用户报告,不得按旧内容继续写作。** `src/client/ui/choices.tsx` 只允许接口参考,且工作树版本与 HEAD 不同(Manifest I 节已记录),本计划不读它。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报本批拆分、命名清单与落点,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md(User Constraints、Page Plan、Docs Placement / Conventions、Per-page Notes 第 1–6 篇、Reference Manifest)、.planning/phases/10-docs-restructure/10-CONTEXT.md(D-09、D-10、D-11、D-13、D-14、D-45、D-46、D-84..D-90)、.planning/phases/10-docs-restructure/10-42-PLAN.md(Task 0 汇报与关卡体例)、docs/.vitepress/config.ts:215-257(高级 II 现有分组)、docs/.vitepress/components/renderDemo.vue、docs/poc/render-demo.md</read_first>
<action>向用户做四段汇报并停下等待(D-12)。
**要做什么**——在高级 II 下新开子分组「自定义 UI 与渲染」(建议名,待确认),本计划先落地 6 篇正文(UI 通用模板、同一 UI 的 TS 元素层写法、容器与坐标、基础图形、曲线与路径、文字),配套 5 个 `.tsx` live demo,并把这一批的基础设施一次建好。**不做**任何源码修改、不改已有正文语义、不动 nav 顶层入口。
**为什么**——读者的第一个 UI 需要一条能照着抄的直线路径;先把模板、坐标、图形、文字讲通,后面的响应式、组件化、内置组件与完整示例才有落点。基础设施(`.tsx` 类型入口、侧边栏骨架、demo 目录、参考清单哈希)必须先立,否则后面每个批次都要重复一遍。
**大致怎么做**——Task 1 建记录文件并核对参考清单哈希、给 `docs/tsconfig.json` 加 `.tsx`、修正两处导览措辞,然后跑首次全量构建;Task 2 写 Part 0 两篇 + 模板 demo 并登记侧边栏;Task 3 写容器与坐标、基础图形两篇 + 两个 demo;Task 4 写曲线与路径、文字两篇 + 两个 demo;Task 5 收口六类门禁(prettier / ESLint / docs 类型 / 构建 / 静态断言 / 记录);Task 6 由用户在浏览器目视 live 与抽查正文。
**影响范围**——只新增 `docs/advanced/ii/ui/` 下 6 个 `.md` 与 `docs/.vitepress/components/demos/ui/` 下 5 个 `.tsx`,加法式修改 `docs/.vitepress/config.ts`(高级 II 分组内新增嵌套子分组;`custom` 数组追加 `container-custom`,保留 `custom-container`)与 `docs/tsconfig.json`(include 增加 `.tsx`),修正 `docs/advanced/ii/index.md` 与 `docs/advanced/index.md` 两处措辞,新增 `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md`。不动 `packages/`、`packages-user/`、`src/`、已有正文、nav 顶层入口、POC 页与 `10-01`..`10-42`。
**必须整份交给用户确认的清单(建议值,未确认不得落盘):**
| 项 | 建议值 |
|----|--------|
| 子分组名 | 自定义 UI 与渲染 |
| 子分组内分组 | Part 0 起步 / Part 1 元素与布局 / Part 2 交互与数据 / Part 3 组件化 / Part 4 内置组件与 UI 系统 / Part 5 完整示例 |
| 目录 | `docs/advanced/ii/ui/` |
| 第 1 篇 | `ui-template.md` ·「UI 通用模板(TSX)」 |
| 第 2 篇 | `ui-template-ts.md` ·「同一 UI 的 TS 元素层写法」 |
| 第 3 篇 | `container-and-coordinates.md` ·「容器与坐标」 |
| 第 4 篇 | `basic-shapes.md` ·「基础图形」 |
| 第 5 篇 | `curves-and-paths.md` ·「曲线与路径」 |
| 第 6 篇 | `text.md` ·「文字」 |
| 后续 21 篇文件名 | 见 `10-CUSTOM-UI-RESEARCH.md` 的「建议目录与文件名」表(本次一并确认,后续批次不再重开命名) |
| demo 目录 | `docs/.vitepress/components/demos/ui/` |
| 本计划 demo | `template-demo.tsx`(`TemplateDemo`)/ `container-demo.tsx`(`ContainerDemo`)/ `shapes-demo.tsx`(`ShapesDemo`)/ `curves-demo.tsx`(`CurvesDemo`)/ `text-demo.tsx`(`TextDemo`) |
| 侧边栏层级 | 高级 II → 子分组 → 6 个 Part → 篇目(两层嵌套);若渲染不理想,退化为子分组下 27 条平铺 |
| 落点 | 先全部写进高级 II 的新子分组;合并 / 拆分的评估留到 10-49 |
| 导览更新时机 | 本计划只做措辞修正 + 一句入口;完整目录表留到 10-49 收尾 |
同时说明:①本计划的 6 篇与 5 个 demo 在本计划内完成,Part 1 后两篇(图片与最小纹理、层级变换与性能)与 Part 2 合并到 10-44,原因是单计划不超过 8 篇正文;②参考清单以 `10-CUSTOM-UI-RESEARCH.md` 的 Manifest 为准,写作前逐条核对哈希,变化即停;③改名即改本计划中对应路径与断言,其余结构不变;④**容器标签的已知重构点**:运行时代码当前注册的自定义标签名是 `custom-container`,而用户已锁定文档统一写 `container-custom`;本计划会在 `docs/.vitepress/config.ts` 的 `custom` 数组里同时放行两者(docs-only,不改 `packages/`),因此构建不会报未知标签,但 live 里的 `container-custom` 可能暂时不渲染——这是已知重构点,不阻塞写作与构建,也**不得**把文档改写回 `custom-container`、**不得**要求修改 `packages/`。**未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;执行期间不得调用 `opencode` 命令;不得修改任何既有 JSDoc / 注释;本计划不做 git commit。然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报拆分、命名清单、落点与参考清单策略,供用户裁决。</what-built>
<how-to-verify>确认:①是否同意本批 27 篇拆成 10-43..10-49 七个计划(六个内容计划 + 10-48 审阅 + 10-49 修订收尾)、且 10-43 只做 6 篇 + 基础设施;②子分组名、6 个 Part 名、目录、27 个文件名与侧边栏名、demo 目录与 5 个 demo 名是否采用建议值(逐项可改);③侧边栏两层嵌套是否可接受;④是否同意本计划只做导览措辞修正、完整目录表留到 10-49;⑤是否接受「不改源码、不改已有正文、不 commit」;⑥是否接受「文档统一写 `container-custom`,并在 docs 的 `custom` 数组里同时放行 `custom-container`,live 可能暂时不渲染」。⑥确认后不得再要求改回 `custom-container` 或改 `packages/`。</how-to-verify>
<resume-signal>回复「可以执行」以继续(可同时给出命名选择);其它回复视为未批准,本计划停在此处。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」;子分组名、目录、6 个 Part 名、27 个文件名与侧边栏名、demo 目录与 5 个 demo 名、侧边栏层级、导览更新时机逐项确定。用户未回复「可以执行」前不得创建或修改任何文件。汇报中已完整给出上表与拆分理由。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,且命名与落点已逐项确认(含最终子分组名、6 个 Part 名、6 篇文件名、5 个 demo 名、侧边栏层级、导览更新时机)。</human-check>
</verify>
<done>用户回复「可以执行」且命名清单已确定。</done>
</task>
<task type="auto">
<name>Task 1: 记录命名与参考清单哈希 + docs 的 .tsx 入口 + 导览措辞修正 + 首次构建</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md, docs/tsconfig.json, docs/.vitepress/config.ts, docs/advanced/ii/index.md, docs/advanced/index.md</files>
<precondition>用户已在 Task 0 明确回复「可以执行」,且命名清单已逐项确认;命令在仓库根目录执行。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md(Reference Manifest A–G、Docs Placement / Conventions、写作规范表)、docs/tsconfig.json(全文)、docs/advanced/ii/index.md(全文,重点 15 与 77-81 两处措辞)、docs/advanced/index.md(重点 13 与 36-41)、.planning/config.json(security_enforcement / ASVS 级别)</read_first>
<action>本任务做四件事。
**(a)新建 `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md`**(CRLF、UTF-8)。这是本批七个计划共用的**追加式**记录文件,后续只允许在末尾追加小节,不得改写前面已写内容。内容顺序:
1. 标题与一行说明「本文件记录 10-43..10-49 的命名、参考清单哈希、门禁与人工验证,只追加不改写」。
2. **命名总表**:按 Task 0 确认结果逐项写最终值,覆盖子分组名、6 个 Part 名、目录、27 个文件名与侧边栏显示名、demo 目录、27 篇各自是否配 live 与 demo 文件名。
3. 独占一行 `用户确认(10-43):可以执行`,**下一行**以 `用户原文:` 开头写用户原话;紧接着独占一行写 `基线 HEAD:` + `git rev-parse HEAD` 的完整 sha(**本批七个计划的起点**;10-48 的 Task 1 会记录 `基线 HEAD(10-48 记录)` 用于证明审阅期间未改正文,10-49 的 Task 1 会另行记录 `基线 HEAD(10-49 记录)` 用于收尾断言,此处只作整批起点的补充证据)。
4. **参考清单哈希基线**:一张表,列为「路径 / Manifest 哈希(HEAD)/ 写作前 `git hash-object -- <path>` 实测 / 是否一致」,覆盖 `10-CUSTOM-UI-RESEARCH.md` 中本批会引用的条目(Manifest A:`core/item.ts`、`core/types.ts`、`core/graphics.ts`、`core/misc.ts`、`core/transform.ts`、`core/canvas2d.ts`、`style/font.ts`、`assets/texture.ts`;B:`render-vue/src/props.ts`、`elements.ts`、`tag.ts`、`types.ts`、`use.ts`;C:`system/src/ui/*`;F:`client-base/src/types.ts`、`client-modules/src/client.ts`、`ui/func.ts`、`src/bootstrap.ts`、`src/client/ui/main.tsx`、`inputBox.tsx`、`title.tsx`、`load.tsx`;G:`docs/.vitepress/components/renderDemo.vue`、`demos/basicRender.vue`、`demos/uiSystem.vue`、`docs/.vitepress/config.ts`)。另单列一行记录 `src/client/ui/choices.tsx` 的**工作树** `git hash-object` 值与其 HEAD 值(Manifest I 已注明两者不同,只允许接口参考)。
5. 一句规则:**任一文件实测哈希与 Manifest 不一致、或 `git status --porcelain -- <path>` 非空(`docs/.vitepress/config.ts` 与 `docs/tsconfig.json` 本计划自己要改,除外),立即停下向用户报告,不得按旧内容继续写作。**
6. **写作硬规则摘要**(把本计划 `<context>` 里的十二条规则压缩成可执行清单)。
7. **门禁记录区**:预留 `## 门禁记录` 与 `## 人工验证记录` 两个二级标题,本任务只建标题,内容由 Task 5 / Task 6 追加。
**(b)`docs/tsconfig.json`**:`include` 数组增加一项 `"./.vitepress/**/*.tsx"`(放在现有 `.vue` 项之后)。**不得**改 `extends`、`baseUrl`、`paths`、`ignoreDeprecations`,不得把它并入 `pnpm check:type`,不得改根 `tsconfig.json` / `tsconfig.node.json`。
**(b-2)`docs/.vitepress/config.ts` 的 `custom` 数组**:在 `'custom-container'` 之后追加一项 `'container-custom'`(用户锁定的文档写法)。**只做加法**:保留 `'custom-container'`(运行时代码当前注册的名字)、不动 `map-render` / `animate` / `damage` / `graphics` / `icon` / `winskin` 这些既有项、不改 `isCustomElement` 函数体、不改 `vuejsx({ isCustomElement })` 调用点、不引入新依赖。这是 docs-only 改动,**不得**改 `packages/` / `packages-user/` / `src/`,也**不得**把文档改写回 `custom-container`。
**(c)导览措辞修正(两处,只改矛盾句,不改篇目表)**:
- **前置约束**:本任务**不得**在 `docs/advanced/ii/index.md` / `docs/advanced/index.md` 里写入任何指向 `./ui/...` 的 markdown 链接,也不得写入 `/advanced/ii/ui/...` 形式的站内链接——这些页面要到 Task 2 才创建,提前写会让 `pnpm docs:build` 报 dead link。本任务只写纯文本入口,链接由 Task 2 在页面落盘后回填。
- `docs/advanced/ii/index.md`:把「这里仍然只写数据端;引擎编写者的内容属于高级 III。」改写成「这一层的主体是数据端;另有自定义 UI 与渲染子分组(见侧边栏),面向要在画布上写界面的作者。」;把「本层不覆盖什么」里的「**渲染端与编辑器**:渲染端表现、编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内」改写为只排除「编辑器属性项、状态栏展示、怪物图鉴」,并补一句「界面绘制与 UI 系统见子分组『自定义 UI 与渲染』」——**改写后该页不得残留 `渲染端与编辑器` 这一小标题**。**同时改三处计数/受众/边界措辞**:①把「本层一共十篇:这一页导览,加上九篇正文。」改成「本层一共十篇(这一页导览 + 九篇数据端正文),另有『自定义 UI 与渲染』子分组 27 篇(见侧边栏)。」;②在 UI 子分组入口处补一句「Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端;上文的数据端前置只对数据端篇目成立。」;③补一句性能边界「高级 II 的性能篇(第 21 篇)讲 UI 系统的缓存与显示策略,引擎级性能仍属高级 III。」。其余表格、篇目表、插件边界不动。
- `docs/advanced/index.md`:把「渲染端尚未完工,本层当前只收录数据端内容;渲染端专属篇目只以占位符出现,等渲染端完工后补齐。」改写成说明高级 II 已收录自定义 UI 与渲染子分组、但本层其它篇目仍以数据端为主;并在提到「性能」的位置补**与上一页同一句**「高级 II 的性能篇(第 21 篇)讲 UI 系统的缓存与显示策略,引擎级性能仍属高级 III」,避免与高级 III 重叠。**只改这些语义,不新增顶层导航、不改 phase 表其它行、不动「三条路径」计数**(第四条路径在两处导览的收尾批次 10-49 Task 3 才写入)。
**(d)首次全量构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`。把结论写进 NOTES 门禁区:`首次构建:green` 并附命令与关键输出(`build complete` / dead link 行数)。若 red:先只回退本任务 (b)(b-2)(c) 的改动再跑一次,判断是否由本次改动引起;回退后仍 red 则**停止后续所有任务**,把完整报错贴回对话等用户指令,不得自行修复既有问题。另跑一次 `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,确认 `docs/` 路径 0 报错,把条数与摘要(含既有引擎报错条数)记进 NOTES 门禁区。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; if(-not(Test-Path -LiteralPath $n)){ Write-Error "MISSING $n" }; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'CONFIRM-10-43' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'CONFIRM-QUOTE' }; foreach($k in @('命名总表','参考清单哈希基线','写作硬规则','## 门禁记录','## 人工验证记录','choices.tsx')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD:[0-9a-f]{7,40}'){ Write-Error 'NOTES-NO-BASE-HEAD' }; if($np -match "(?<!\r)\n"){ Write-Error 'NOTES-LF-ONLY' }; $js='const fs=require("fs");const t=JSON.parse(fs.readFileSync("docs/tsconfig.json","utf8"));const inc=Array.isArray(t.include)?t.include:[];if(!inc.some(function(v){return v.indexOf("*.tsx")>=0})){console.error("TSCONFIG-NO-TSX");process.exit(1)}const keep=[".vitepress/**/*.ts",".vitepress/**/*.vue","../src/types/vite-env.d.ts"];keep.forEach(function(k){if(!inc.some(function(v){return v.indexOf(k)>=0})){console.error("TSCONFIG-LOST:"+k);process.exit(1)}});if(t.extends!=="../tsconfig.json"){console.error("TSCONFIG-EXTENDS");process.exit(1)}if(!t.compilerOptions||t.compilerOptions.baseUrl!==".."||t.compilerOptions.ignoreDeprecations!=="6.0"){console.error("TSCONFIG-OPTS");process.exit(1)}const p=t.compilerOptions.paths||{};if(!p["@motajs/*"]||!p["@user/*"]){console.error("TSCONFIG-PATHS");process.exit(1)}console.log("TSCONFIG-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'TSCONFIG-FAIL' }; $cfg1=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); if($cfg1.IndexOf('container-custom') -lt 0){ Write-Error 'CFG-NO-CONTAINER-CUSTOM' }; if($cfg1.IndexOf('custom-container') -lt 0){ Write-Error 'CFG-LOST-CUSTOM-CONTAINER' }; if($cfg1.IndexOf('isCustomElement') -lt 0){ Write-Error 'CFG-LOST-ISCUSTOM' }; if($cfg1.IndexOf("'map-render'") -lt 0 -and $cfg1.IndexOf('"map-render"') -lt 0){ Write-Error 'CFG-LOST-MAPRENDER' }; $ii=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); if($ii -match '仍然只写数据端'){ Write-Error 'INDEX2-STILL-DATA-ONLY' }; if($ii.IndexOf('自定义 UI 与渲染') -lt 0){ Write-Error 'INDEX2-NO-ENTRY' }; if($ii.IndexOf('custom-range.md') -lt 0){ Write-Error 'INDEX2-LOST-TABLE' }; if($ii -match '\]\(\./ui/'){ Write-Error 'INDEX2-FORWARD-LINK' }; if($ii.IndexOf('/advanced/ii/ui/') -ge 0){ Write-Error 'INDEX2-FORWARD-LINK-ABS' }; if($ii.IndexOf('27 篇') -lt 0){ Write-Error 'INDEX2-NO-UI-COUNT' }; if($ii.IndexOf('渲染端与编辑器') -ge 0){ Write-Error 'INDEX2-OLD-RENDERER-TERM' }; if($ii.IndexOf('一共十篇:') -ge 0){ Write-Error 'INDEX2-OLD-COUNT' }; if($ii.IndexOf('基础 TS') -lt 0){ Write-Error 'INDEX2-NO-AUDIENCE' }; if($ii.IndexOf('引擎级性能仍属高级 III') -lt 0){ Write-Error 'INDEX2-NO-PERF-BOUNDARY' }; $ad=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/index.md')); if($ad -match '\]\(\./ui/'){ Write-Error 'INDEX1-FORWARD-LINK' }; if($ad.IndexOf('引擎级性能仍属高级 III') -lt 0){ Write-Error 'INDEX1-NO-PERF-BOUNDARY' }; if($ad -match '渲染端尚未完工'){ Write-Error 'INDEX1-STILL-UNFINISHED' }; if($ad.IndexOf('自定义 UI 与渲染') -lt 0){ Write-Error 'INDEX1-NO-ENTRY' }; if($ad.IndexOf('高级 III') -lt 0){ Write-Error 'INDEX1-LOST-III' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING", "CONFIRM-10-43", "CONFIRM-QUOTE", "NOTES-MISSING", "NOTES-NO-BASE-HEAD", "NOTES-LF-ONLY", "TSCONFIG-", "TSCONFIG-FAIL", "CFG-NO-CONTAINER-CUSTOM", "CFG-LOST-", "INDEX2-", "INDEX1-", "INDEX1-FORWARD-LINK", "INDEX1-NO-PERF-BOUNDARY", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 存在且含命名总表、独占一行 `用户确认(10-43):可以执行` + 下一行 `用户原文:`、独占一行 `基线 HEAD:<sha>`、参考清单哈希基线表(含 choices.tsx 的 HEAD 与工作树两值)、写作硬规则、`## 门禁记录` 与 `## 人工验证记录` 两个预留标题;`docs/tsconfig.json` 的 include 含 `*.tsx` 且既有三项 / extends / baseUrl / paths / ignoreDeprecations 未变;`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom` 与 `custom-container`,其余既有项(含 `map-render`)与 `isCustomElement` 未变;两处导览不再出现矛盾句并给出子分组入口,原篇目表与高级 III 引用仍在,且**不含**任何指向 `./ui/...` 的前向链接(入口只有纯文本,链接由 Task 2 回填);`docs/advanced/ii/index.md` 的「一共十篇」已改写为「十篇数据端 + 27 篇 UI 子分组」,并写明「Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端」;`docs/advanced/ii/index.md` 与 `docs/advanced/index.md` **两页都**含同一句性能边界;首次全量构建 green、无 dead link;`vue-tsc -p docs/tsconfig.json` 下 `docs/` 路径 0 报错并把结论记入 NOTES。</acceptance_criteria>
<done>命名与哈希基线落盘,docs 接受 `.tsx`,导览矛盾句已修,首次构建 green。</done>
</task>
<task type="auto">
<name>Task 2: Part 0 两篇(UI 通用模板 / TS 元素层写法)+ 模板 demo + 侧边栏子分组骨架</name>
<files>docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/ui-template-ts.md, docs/.vitepress/components/demos/ui/template-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/index.md</files>
<precondition>NOTES 含 `用户确认(10-43):可以执行`;Task 1 的首次构建 green;子分组名、两篇文件名与 demo 名已确认。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 1、2 篇;Author Entry 全节;Render Elements 的「所有元素共有的属性」)、.planning/phases/10-docs-restructure/10-42-POC-NOTES.md(命名与落点体例)、packages-user/client-base/src/types.ts:16-55(IGameUIPropsBase 与 ClientCore 的两个控制器)、src/bootstrap.ts:12-16、src/client/ui/title.tsx:1-3、docs/.vitepress/components/renderDemo.vue、docs/.vitepress/config.ts:215-257</read_first>
<action>写两篇正文与一个 demo,并在侧边栏建立子分组骨架。
**(1)`ui-template.md`(第 1 篇)**:按 D-84 顺序写。开头用两三句话回答「UI 是什么、canvas 是什么」——画面由本框架的元素绘制,作者用 TSX 描述结构,不用 DOM。然后给**完整最小模板**:`import { defineComponent } from 'vue'`、`import { GameUI, SetupComponentOptions } from '@motajs/system'`、`import { DefaultProps } from '@motajs/render-vue'`、`import { IGameUIPropsBase } from '@user/client-base'`;`interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}`;`const myPanelProps = { props: ['controller', 'instance', 'state'] } satisfies SetupComponentOptions&lt;MyPanelProps&gt;`;组件用 `defineComponent&lt;MyPanelProps&gt;` 返回 render 函数,内部是 `container` + `g-rect` + `text`;最后 `export const MyPanelUI = new GameUI('my-panel', MyPanel)`。随后给「只改哪几行」表格(文件名 / 组件名 / `GameUI` 名、`container` 的 `loc`、里面的元素、Props 基类、`props` 列表、打开处)。再讲打开与关闭三个位置:`client.sceneController.open(MyPanelUI, {})`(作者入口)、`props.controller.open(MyPanelUI, {})`(在另一个 UI 内)、`props.controller.close(props.instance)`(关闭自己),并各配一小段说明;主 UI 栈只用一句话交代 `props.state.mainUIController.open(...)` 的存在,不展开。最后放 live(`template-demo`)。`## 边界与注意` 写:少声明 `controller` / `instance` / `state` 中任何一个就拿不到对应 props;Props 基类只能用 `IGameUIPropsBase` 配 `DefaultProps`;属性名必须 camelCase,写错不报错也不生效;不要用单文件组件写法。
**(2)`template-demo.tsx`**:默认导出一个 `defineComponent`,只 import `vue` 的所需符号(若不需要响应式就不要 import 多余符号),根节点 `container` 逻辑尺寸 480×320,内含 `g-rect` 背景与 `text`;不 import 任何引擎包,不创建渲染器或 canvas,不写 `style` / `class`;组件名 `TemplateDemo`。
**(3)`ui-template-ts.md`(第 2 篇)**:讲同一画面用元素层接口怎么写:先用 `ref&lt;Container&gt;()` 拿到 TSX 里的 `container`,在 `onMounted` 里 `new Rect()` / `new Text(...)`,用 `size` / `pos` 设几何、用**各自类上的 setter** 设样式(图形:`rect.setFillStyle(...)` / `rect.setStrokeStyle(...)`;文字:`label.setText(...)` / `label.setStyle(fill, stroke)` / `label.setFont(...)`——`setFillStyle` 只在 `GraphicItemBase` 上,`Text` 没有它),再 `host.value!.appendChild(rect, label)`;给完整组件片段(含 import 与 render 函数)。然后给**两张**对照表而不是一张:`TSX 属性 ↔ 图形元素 setter`(`loc` ↔ `pos` + `size`、`fillStyle` ↔ `setFillStyle`、`strokeStyle` ↔ `setStrokeStyle`)与 `TSX 属性 ↔ 文字元素 setter`(`loc` ↔ `pos`、`text` ↔ `setText`、`fillStyle` / `strokeStyle` ↔ `setStyle`、`font` ↔ `setFont`),并明确「两套映射不能混用:把 `setFillStyle` 用在文字元素上不成立」。再讲清楚三件事:元素层不参与 Vue 响应式、改属性必须调 setter、`ref` 要等挂载后才拿得到实例所以放在 `onMounted`;`host.value!` 是组件内必定存在的非空断言。live 复用 `template-demo`(说明「同一画面,两种写法」)。`## 边界与注意` 写:元素层是画布元素,不能直接当 UI 打开(UI 必须是 Vue 组件);不要为了拿到容器去查询 DOM;不要在这里引入渲染器。
**(4)侧边栏**:在 `docs/.vitepress/config.ts` 的高级 II 分组 `items` 末尾新增一个嵌套子分组对象:`text` 为确认后的子分组名、`collapsed: false`,其 `items` 里先放一个 `{ text: '起步', collapsed: false, items: [...] }`,`items` 两条分别指向 `'/advanced/ii/ui/ui-template'` 与 `'/advanced/ii/ui/ui-template-ts'`,显示名按确认结果。**只做加法**:不动高级 II 既有 10 条、不动高级 I / III 分组、不改任何既有注释与缩进风格(4 空格)。**每条 link 必须对应本任务已创建的文件**,否则构建会报 dead link。
**(5)回填导览链接**:两篇页面已在本任务落盘,把 Task 1 写下的纯文本入口改成带链接的版本——在 `docs/advanced/ii/index.md` 的那句入口里,用 `[UI 通用模板](./ui/ui-template.md)` 与 `[同一 UI 的 TS 元素层写法](./ui/ui-template-ts.md)` 两个链接指向本任务创建的两篇。**只加这两个链接**:不得加其它 `./ui/...` 链接(其余 25 篇要到后续批次才创建),不得改导览其它段落。
写完后先跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`(D-45),再交给自动门禁。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const p1="docs/advanced/ii/ui/ui-template.md";const p2="docs/advanced/ii/ui/ui-template-ts.md";[p1,p2].forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const s1=fs.existsSync(p1)?rd(p1):"";["defineComponent","SetupComponentOptions","GameUI","IGameUIPropsBase","DefaultProps","controller","instance","state","sceneController.open","props.controller.open","props.controller.close(props.instance)","g-rect","container","text"].forEach(function(k){if(s1.indexOf(k)<0)bad.push("P1:"+k)});if(!/\x3cClientOnly\x3e/.test(s1))bad.push("P1:NO-CLIENTONLY");if(!/\(\)\s*=>\s*import\(/.test(s1))bad.push("P1:NO-LOADER");const s2=fs.existsSync(p2)?rd(p2):"";["appendChild","ref\x3cContainer\x3e","onMounted","Rect","Text","setFillStyle","setText","setStyle","setFont"].forEach(function(k){if(s2.indexOf(k)<0)bad.push("P2:"+k)});const d="docs/.vitepress/components/demos/ui/template-demo.tsx";if(!fs.existsSync(d))bad.push("NO-DEMO");else{const s=rd(d);if(!/export\s+default/.test(s))bad.push("DEMO-NO-DEFAULT");if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE-IMPORT");["container","g-rect","text"].forEach(function(k){if(s.indexOf(k)<0)bad.push("DEMO:"+k)});if(/style=|class=/.test(s))bad.push("DEMO-DOM-ATTR")}const idx2=rd("docs/advanced/ii/index.md");if(idx2.indexOf("./ui/ui-template.md")<0||idx2.indexOf("./ui/ui-template-ts.md")<0)bad.push("INDEX-BACKFILL");if((idx2.match(/\]\(\.\/ui\//g)||[]).length!==2)bad.push("INDEX-FORWARD-LINK");const cfg=rd("docs/.vitepress/config.ts");if(cfg.indexOf("/advanced/ii/ui/ui-template")<0||cfg.indexOf("/advanced/ii/ui/ui-template-ts")<0)bad.push("SIDEBAR-LINKS");if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("SIDEBAR-LOST");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-43", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "CRLF:", "P1:", "P2:", "NO-DEMO", "DEMO-", "SIDEBAR-", "INDEX-BACKFILL", "INDEX-FORWARD-LINK", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>两篇正文各单 H1、含 `## 边界与注意`、CRLF;第 1 篇含完整模板所需的全部标识符(`defineComponent` / `SetupComponentOptions` / `GameUI` / `IGameUIPropsBase` / `DefaultProps` / 三个 props 名 / 三个打开关闭入口),并用 `&lt;ClientOnly&gt;` + `() =&gt; import(...)` 接 live;第 2 篇含 `appendChild` 与**两张**元素层 setter 对照表(图形:`setFillStyle` / `setStrokeStyle`;文字:`setText` / `setStyle` / `setFont`),并明确两套映射不能混用、元素层不当 UI 打开;两篇都不出现被禁写法;`template-demo.tsx` 默认导出、只 import vue、无 DOM 属性、含 container / g-rect / text;侧边栏新增嵌套子分组、两条链接指向已建页面、高级 II 既有条目与高级 III 分组未丢;`docs/advanced/ii/index.md` 的纯文本入口已回填这两个页面的链接,且全文只有这两处 `./ui/` 链接(其余 25 篇此时尚未创建);全量构建 green 且无 dead link。</acceptance_criteria>
<done>Part 0 两篇与模板 demo 完成,侧边栏子分组骨架可用且构建 green。</done>
</task>
<task type="auto">
<name>Task 3: 容器与坐标 / 基础图形两篇 + 两个 demo + 侧边栏登记</name>
<files>docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/.vitepress/components/demos/ui/container-demo.tsx, docs/.vitepress/components/demos/ui/shapes-demo.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-43):可以执行`;Task 2 的页面与侧边栏骨架已存在且构建 green。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 3、4 篇;Render Elements 的属性默认值 / 各元素专属属性 / loc 顺序;Common Pitfalls)、packages/render/src/core/types.ts:37-44(ElementLocator)、packages/render-vue/src/props.ts:24-160、packages/render/src/core/graphics.ts:37-49(图形默认值)、docs/.vitepress/config.ts(Task 2 新增的子分组结构)</read_first>
<action>写两篇正文与两个 demo,并把它们登记进侧边栏。
**(1)`container-and-coordinates.md`(第 3 篇)**:先回答「坐标从哪来」——根容器的左上角就是原点,子元素坐标相对父容器左上角;容器同时是布局单位与事件捕获单位。再讲 `loc` 的六元组顺序 `[x, y, width, height, anchorX, anchorY]` 与等价的分开属性,讲锚点 0 / 0.5 的差别(默认 `anchorX` / `anchorY` 为 0,圆形与椭圆默认 0.5)。给出默认值表(`width` / `height` 默认 200),提醒按需显式给尺寸。示例写一个 480×320 根容器,内部两个不同 `loc` / `anc` 的嵌套容器,各放一个 `g-rect` 标出边界并用 `text` 标注坐标。`zIndex` 只讲「越大越靠上」一句,细节留给第 8 篇——**此处只写纯文本「第 8 篇『层级、变换与性能』」,不要写 `./layer-transform-performance.md` 链接**(该页在 10-44 创建,届时由 10-44 回填)。元素层的 `appendChild` / `removeChild` 只用一两句话带过(完整写法见第 2 篇)。live 用 `container-demo`。`## 边界与注意`:默认尺寸 200 容易被忽略;锚点改变了元素「自己的哪一点」落在 `x` / `y` 上;不要用 DOM 的定位思路去理解嵌套。
**(2)`basic-shapes.md`(第 4 篇)**:四个基础图形 `g-rect` / `g-circle` / `g-ellipse` / `g-line` 各给一个最小示例;讲清 `fill` / `stroke` / `strokeAndFill` 是**模式开关**,`fillStyle` / `strokeStyle` 才是样式;讲线宽、虚线、端点与连接样式(`lineWidth` / `lineDash` / `lineCap` / `lineJoin`);讲 `g-line` 用两点(`x1` / `y1` / `x2` / `y2` 或 `line`)自动算位置与大小;讲 `radius` / `radiusX` / `radiusY`;讲 `actionStroke` 让命中区域只算描边。同一页里给一张「默认填充 / 默认描边」对照表。live 用 `shapes-demo`,点击让某个图形换色(这为第 10 篇埋伏笔,正文用一句话点明「事件在第 10 篇展开」——**只写纯文本,不加链接**;该页在 10-44 创建,届时由 10-44 回填)。`## 边界与注意`:默认色是浅灰,示例要显式给色;`fill` 不是颜色属性;圆的默认锚点与矩形不同。
**(3)两个 demo**:`container-demo.tsx`(`ContainerDemo`)展示嵌套容器 + 半透明矩形 + 坐标标注文字;`shapes-demo.tsx`(`ShapesDemo`)展示四个图形 + 点击换色(用 `ref&lt;string&gt;` 存颜色,`onClick` 改值)。都只 import vue 与元素标签,默认导出组件,不 import 引擎包,不写 `style` / `class`。
**(4)侧边栏**:在 Task 2 建的子分组 `items` 里追加 `{ text: '元素与布局', collapsed: false, items: [...] }`,两条链接分别指向 `/advanced/ii/ui/container-and-coordinates` 与 `/advanced/ii/ui/basic-shapes`。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const pages={"docs/advanced/ii/ui/container-and-coordinates.md":["loc","anc","anchorX","anchorY","width","height","zIndex","container","g-rect","text"],"docs/advanced/ii/ui/basic-shapes.md":["g-rect","g-circle","g-ellipse","g-line","fillStyle","strokeStyle","lineWidth","lineDash","actionStroke","radius"]};Object.keys(pages).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});pages[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("NO-CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("NO-LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["container-demo.tsx","shapes-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-NO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/container-and-coordinates","/advanced/ii/ui/basic-shapes","/advanced/ii/ui/ui-template","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-43", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "NO-CLIENTONLY", "NO-LOADER", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>两篇正文单 H1、含 `## 边界与注意`、CRLF、含各自必需标识符(容器篇:`loc` / `anc` / `anchorX` / `anchorY` / 默认尺寸 / `zIndex` 一句;图形篇:四个图形与填充描边 / 线宽虚线 / `actionStroke` / `radius`),都接 live 且不出现被禁写法;两个 demo 默认导出、只 import vue、无 DOM 属性;侧边栏新增「元素与布局」两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>容器与坐标、基础图形两篇与两个 demo 完成并已登记。</done>
</task>
<task type="auto">
<name>Task 4: 曲线与路径 / 文字两篇 + 两个 demo + 侧边栏登记</name>
<files>docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/text.md, docs/.vitepress/components/demos/ui/curves-demo.tsx, docs/.vitepress/components/demos/ui/text-demo.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-43):可以执行`;Task 3 的两篇与「元素与布局」分组已存在且构建 green。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 5、6 篇;各元素专属属性表的曲线 / 路径 / 文字行)、packages/render/src/core/graphics.ts:564-1014(曲线、路径、圆角矩形的属性语义)、packages/render/src/style/font.ts:35-60(`constructor(family, size, sizeUnit, weight, italic)` 位置参数与静态默认值)、:160-192(`Font.defaults` / `Font.clone` 的 `Partial<IFontConfig>` 形式)、packages/render/src/core/misc.ts:10-147(文字默认填充色 / 描边宽度 / 自动尺寸)、docs/.vitepress/config.ts(Task 3 后的子分组结构)</read_first>
<action>写两篇正文与两个 demo,并把它们登记进侧边栏。
**(1)`curves-and-paths.md`(第 5 篇)**:先一句话说明「曲线用控制点画,路径用浏览器自带的 `Path2D` 存一组子路径」。`g-bezier` 讲三点式控制点(起点、两个控制点、终点)与 `curve` 八元数组;`g-quad` 讲单控制点与六元数组;`g-path` 讲 `path` 必须是 `Path2D` 实例(给出在组件外用 `new Path2D()` 组好再传入的完整片段);`g-rectr` 讲圆角数组:`circle` 1–4 项、`ellipse` 2 / 4 / 6 / 8 项,并说明为什么四个角可以不同。给一张「默认描边 / 默认填充」对照表,指出曲线默认描边、路径与圆角矩形默认填充。live 用 `curves-demo`:一条三次贝塞尔、一条二次贝塞尔、一个 `Path2D` 折线、一个圆角矩形。`## 边界与注意`:`path` 传字符串不行;`curve` 数组长度写错不会报错只是画不对;圆角矩形与矩形的命中区域不同。
**(2)`text.md`(第 6 篇)**:先讲文字元素是最简单也最容易误用的一种:`text` 属性 + `fillStyle` 填充 + 可选描边(`stroke` / `strokeStyle` / `strokeWidth`);字体用 `font`(`Font` 类型),给出**位置参数**构造 `new Font('Verdana', 32, 'px', 700)`(签名 `(family, size, sizeUnit, weight, italic)`,默认值取自 `Font.defaultFamily` / `Font.defaultSize` 等静态字段)与命名式的 `Font.clone(Font.defaults(), { size: 32, weight: 700 })`;**构造函数只接受位置参数——不要传对象字面量(对象形式的配置只属于 `Font.defaults` / `Font.clone` 的 `Partial<IFontConfig>`)**;讲文字尺寸由测量决定,不要给 `width` / `height` 期待裁剪;讲用锚点把文字居中(`anchorX` / `anchorY` 0.5)。明确说明文字元素**不会自动换行**,需要换行、打字机效果时用第 17 篇的文本组件——**此处只写纯文本「第 17 篇『内置组件:文本与输入』」,不要写 `./builtin-text-and-input.md` 链接**(该页在 10-46 创建,届时由 10-46 回填)。live 用 `text-demo`:三种字号 / 颜色的对照,加一个 `new Font('Verdana', 32, 'px', 700)` 的标题(**位置参数构造**;live 里不调用 `Font.defaults`、不改 `Font.defaultFamily` 等静态默认值,避免影响后续 demo 的默认字体;正文可以讲 `Font.defaults` / `Font.clone` 的语义)。`## 边界与注意`:`fillStyle` 默认白色;`strokeWidth` 默认 1;给文字设宽高不会截断;长文本不要用文字元素硬排。
**(3)两个 demo**:`curves-demo.tsx`(`CurvesDemo`)与 `text-demo.tsx`(`TextDemo`),都默认导出组件、无 DOM 属性。`curves-demo` **只** import vue 与元素标签;`text-demo` 额外允许 `import { Font } from '@motajs/render'`(元素层类,不是渲染器),除此之外不得 import 任何 `@motajs/*` / `@user/*`,且必须用 `new Font('Verdana', 32, 'px', 700)` 构造、不得调用 `Font.defaults`。`CurvesDemo` 的 `Path2D` 在组件内构造一次即可(不要每次渲染都 new,必要时用 `ref` 或模块内常量并在注释里说明原因)。
**(4)侧边栏**:在「元素与布局」分组的 `items` 末尾追加两条链接,分别指向 `/advanced/ii/ui/curves-and-paths` 与 `/advanced/ii/ui/text`。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/new\s+Font\s*\(\s*\{/];const pages={"docs/advanced/ii/ui/curves-and-paths.md":["g-bezier","g-quad","g-path","g-rectr","Path2D","curve","circle","ellipse"],"docs/advanced/ii/ui/text.md":["text=","fillStyle","strokeStyle","strokeWidth","Font","Font.defaults","anchorX","anchorY"]};Object.keys(pages).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});pages[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("NO-CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("NO-LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const t=fs.existsSync("docs/advanced/ii/ui/text.md")?rd("docs/advanced/ii/ui/text.md"):"";if(t.indexOf("不会自动换行")<0){bad.push("TEXT-NO-WRAP-NOTE")}if(t.indexOf("](./builtin-text-and-input.md)")>=0){bad.push("TEXT-FORWARD-LINK")}if(t.indexOf("第 17 篇")<0){bad.push("TEXT-NO-PLAINREF")}["curves-demo.tsx","text-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-NO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(f==="text-demo.tsx"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+f);if(!/new\s+Font\(\s*[\x22\x27]/.test(s))bad.push("DEMO-NO-FONT-CTOR:"+f);if(/new\s+Font\(\s*\{/.test(s))bad.push("DEMO-FONT-OBJ-CTOR:"+f);if(/Font\.defaults/.test(s))bad.push("DEMO-FONT-DEFAULTS:"+f)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f)}});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/curves-and-paths","/advanced/ii/ui/text","/advanced/ii/ui/container-and-coordinates","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-43", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "TEXT-NO-WRAP-NOTE", "TEXT-FORWARD-LINK", "TEXT-NO-PLAINREF", "NO-CLIENTONLY", "NO-LOADER", "CRLF:", "NO-DEMO", "DEMO-", "DEMO-NO-FONT-CTOR", "DEMO-FONT-OBJ-CTOR", "DEMO-FONT-DEFAULTS", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>曲线篇含四种路径元素与 `Path2D` / `curve` / 圆角项数说明,文字篇含填充 / 描边 / **位置参数**构造 `new Font('Verdana', 32, 'px', 700)` 与 `Font.clone(Font.defaults(), ...)` 的命名式写法(并说明对象参数构造不存在)/ 锚点居中,并明确「不会自动换行」且以**纯文本**指向第 17 篇(不含 `./builtin-text-and-input.md` 链接,由 10-46 回填);两篇单 H1、有 `## 边界与注意`、CRLF、接 live、无被禁写法;两个 demo 默认导出、无 DOM 属性,`text-demo` 只额外 import `@motajs/render` 的 `Font` 且用位置参数 `new Font('Verdana', 32, 'px', 700)`(不出现对象参数构造、不调用 `Font.defaults`),`curves-demo` 不 import 任何引擎包;侧边栏新增两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>曲线与路径、文字两篇与两个 demo 完成并已登记。</done>
</task>
<task type="auto">
<name>Task 5: 六类门禁收口(prettier / ESLint / docs 类型 / 构建 / 静态断言)+ NOTES 记录</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2..4 的 6 篇与 5 个 demo 已落盘、侧边栏 6 条齐全、构建 green。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/*.md、docs/.vitepress/components/demos/ui/*.tsx、docs/.vitepress/config.ts、docs/tsconfig.json</read_first>
<action>按固定顺序跑门禁并记录结论,**顺序不可颠倒**:
1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md"`,随后 `--check` 同路径(D-45)。不要格式化 `.prettierignore` 内文件或其它既有页面。
2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,要求 0 error / 0 warning。若出现 `react/jsx-boolean-value` 之类的 JSX 规则告警,按规则改写法(布尔 prop 用简写),**不得**为消告警把渲染属性改成连字符形式。
3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:只要求路径以 `docs/` 开头且含 `error TS` 的行为 0;`packages/` / `packages-user/` / `src/` 的既有报错只记条数与摘要,标注「既有、非本轮引入、不得修」。
4. 静态断言:用一条 Node 脚本复核本批 6 篇与 5 个 demo 的硬约束(单 H1、`## 边界与注意`、被禁写法为 0、每篇 `<ClientOnly>` + 动态 loader、demo 默认导出且无 DOM 属性(4 个 demo 必须零引擎 import;`text-demo` 允许且仅允许 `@motajs/render` 的 `Font`,且必须是位置参数 `new Font('Verdana', 32, 'px', 700)`,不得出现对象参数构造或 `Font.defaults`)、CRLF),并复核侧边栏 6 条链接、`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom` 与 `custom-container`、高级 II 既有条目、高级 III 分组仍在。
5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、无 dead link。
6. 向 NOTES 的 `## 门禁记录` 追加本次结论:六类门禁逐条命令与结果、`docs/` 路径类型报错 0、既有引擎报错条数与摘要、构建耗时与 dead link 行数、本批 6 篇与 5 个 demo 的清单(路径 + 是否配 live)。
本任务不改任何正文语义,只做格式化、断言与记录。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/new\s+Font\s*\(\s*\{/];const md=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["template-demo","container-demo","shapes-demo","curves-demo","text-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m);if(m==="text-demo"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+m);if(!/new\s+Font\(\s*[\x22\x27]/.test(s))bad.push("DEMO-NO-FONT-CTOR:"+m);if(/new\s+Font\(\s*\{/.test(s))bad.push("DEMO-FONT-OBJ-CTOR:"+m);if(/Font\.defaults/.test(s))bad.push("DEMO-FONT-DEFAULTS:"+m)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+m)}if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("DEMO-CRLF:"+m)});const cfg=rd("docs/.vitepress/config.ts");if(cfg.indexOf("container-custom")<0)bad.push("CFG-NO-CONTAINER-CUSTOM");if(cfg.indexOf("custom-container")<0)bad.push("CFG-LOST-CUSTOM-CONTAINER");md.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-43 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T5-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-43", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "DEMO-NO-FONT-CTOR", "DEMO-FONT-OBJ-CTOR", "DEMO-FONT-DEFAULTS", "CFG-NO-CONTAINER-CUSTOM", "CFG-LOST-", "NOTES-NO-", or "NOTES-NO-ENGINE-NOTE"; or output lacks "T5-OK"</fails_when>
</verify>
<acceptance_criteria>prettier `--write` 与 `--check` 均通过;ESLint 为 0 error / 0 warning 且渲染属性仍为 camelCase;`vue-tsc -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;静态断言全绿(6 篇单 H1 / 边界节 / 无被禁写法 / ClientOnly + 动态 loader / CRLF;5 个 demo 默认导出、无 DOM 属性、CRLF,4 个零引擎 import,`text-demo` 仅允许 `@motajs/render` 的 `Font` 且为位置参数构造、无 `Font.defaults`;侧边栏 6 条 + `custom` 数组双名放行 + 既有条目 + 高级 III 未丢);全量构建 green、无 dead link;NOTES 的 `## 门禁记录` 下有 `### 10-43 门禁` 小节并含 `docs/ 路径类型报错 0` 与「既有引擎报错」条数摘要。</acceptance_criteria>
<done>六类门禁全绿并已记录,本批 6 篇 5 demo 达到可交付状态。</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 6: 用户目视 5 个 live 并抽查正文</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 5 通过(六类门禁全绿、构建产物已生成、NOTES 已记录门禁结论)。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录与命名表)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/(5 个 demo)</read_first>
<action>请用户用 `cmd /c "pnpm docs:dev"`(或对构建产物用 `cmd /c "pnpm docs:preview"`)打开这 6 篇页面,逐条确认:①侧边栏出现子分组与「起步 / 元素与布局」两个分组,6 条链接都能点开且不 404;②第 1 篇的 live 显示深色背景矩形与标题文字;③第 3 篇的 live 能看到嵌套容器边界与坐标文字;④第 4 篇的 live 能看到四个图形,点击其中某个图形颜色变化;⑤第 5 篇的 live 能看到两条曲线、一条折线和圆角矩形;⑥第 6 篇的 live 能看到不同字号 / 颜色的文字与带描边的标题;⑦抽查第 1、2 篇正文:模板能直接照抄(含 `client.sceneController.open`)、TS 对照表与代码一致、没有渲染器类名与 core 命名空间。用户确认通过时,在 NOTES 的 `## 人工验证记录` 追加**独占一行**的 `用户人工验证(10-43):通过`,下一行以 `用户原文:` 开头写原话;若发现问题,逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复后重跑 Task 5 门禁再请用户复验(循环不限轮次)。**只有用户明确通过才可进入 10-44**;沉默或只回复「可以」不算通过。</action>
<what-built>6 篇正文与 5 个 live demo,站点构建产物已生成并可在本地预览。</what-built>
<how-to-verify>按上面①–⑦逐条在浏览器与正文中检查;重点看侧边栏层级、每个 live 是否真实绘制、第 4 篇点击是否变色、模板是否可直接照抄。</how-to-verify>
<resume-signal>若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。</resume-signal>
<acceptance_criteria>用户明确回复 live 与正文均通过,且 NOTES 的 `## 人工验证记录` 下有 `用户人工验证(10-43):通过` 与用户原文;否则问题清单已记录并进入修复循环。</acceptance_criteria>
<verify>
<human-check>用户已明确确认 6 篇页面可读、5 个 live 正常、侧边栏层级可用,并已把结论记入 NOTES。</human-check>
</verify>
<done>用户人工验证结论已记录(通过,或问题清单进入修复循环)。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 文档站构建期(SSR 预渲染)→ live demo | 预渲染在 Node 中执行;demo 必须由 `RenderDemo` 在浏览器端动态 import,页面不得静态 import demo |
| demo → 渲染树 | demo 只声明本地静态结构与 props,不接收外部输入、不解析字符串、不发请求 |
| 侧边栏 → 页面文件 | 每条 link 必须指向已存在文件,否则构建 dead link 失败 |
| 文档正文 → 读者 | 读者照抄示例;写错属性名不会报错但也不生效,属于正确性风险而非安全风险 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-129 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页在同一任务内完成;构建门禁要求 0 dead link,静态断言复核 6 条链接与既有条目未丢 |
| T-10-130 | Denial of Service(构建不可用) | `.tsx` demo 进入 SSR | high | mitigate | demo 只由 `RenderDemo` 的 loader 动态 import;页面只静态 import 包装组件;`<ClientOnly>` 包裹;每次构建门禁必须 `build complete` |
| T-10-131 | Information Disclosure | 正文泄露引擎内部实现 | low | mitigate | 静态断言禁渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;正文只写应用层用法 |
| T-10-132 | Repudiation | 命名与验证结论无据可查 | medium | mitigate | 命名总表、哈希基线、门禁与人工验证全部落在追加式 NOTES;每个 auto 任务复检 `用户确认(10-43):可以执行` |
| T-10-133 | Tampering | 参考文件在写作期间被改动 | high | mitigate | Task 1 记录 `git hash-object` 基线;写作前逐条核对,任一不一致或工作树被改即停下问用户 |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 本计划不安装任何新包(`vue` / `@vitejs/plugin-vue-jsx` / `vitepress` / `prettier` 均已在依赖中);若发现缺失,停止并报告,不得临时安装 |
</threat_model>
<verification>
- 确认门禁:NOTES 含 `用户确认(10-43):可以执行` + 下一行 `用户原文:`;Task 6 后含 `用户人工验证(10-43):通过` + `用户原文:`,且无 `状态:待处理`。
- 内容门禁:6 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性;跨批次前瞻引用(第 8 / 10 / 17 篇)只写纯文本,不含指向尚未创建页面的 markdown 链接。
- 示例门禁:Props 基类与三个 props 名齐全;属性 camelCase;live 全部 `<ClientOnly>` + 动态 loader;demo 默认导出、无 DOM 属性;4 个 demo 零引擎 import,`text-demo` 是唯一例外(仅 `@motajs/render` 的 `Font`,位置参数 `new Font('Verdana', 32, 'px', 700)`,不出现对象参数构造、不碰 `Font.defaults`)。
- 容器标签门禁:`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom`(文档写法)与 `custom-container`(运行时当前注册名),其余既有项与 `isCustomElement` 未变。
- 类型门禁:`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;引擎既有报错只记录。
- 构建门禁:`pnpm docs:build` green、`build complete`、0 dead link。
- 格式门禁:prettier `--check` 通过;ESLint 0 error / 0 warning。
- 越界门禁:`git status --porcelain packages/ packages-user/ src/` 不含本计划引入的改动;未改 `10-01`..`10-42` 与 POC 文件;未 commit;ROADMAP / STATE 本计划不改。
</verification>
<success_criteria>
- 高级 II 下出现新子分组,第一批 6 篇正文可按顺序阅读并直接照抄模板;tsx 示例与 live 一致。
- 基础设施一次建好:`.tsx` 进入 docs 类型检查、侧边栏两层嵌套可用、demo 目录约定确立、参考清单哈希基线在案、docs 的 `custom` 数组放行 `container-custom`。
- 两处导览不再自相矛盾,并给出本子分组的入口与性能边界说明。
- 六类门禁全绿并有记录;用户目视 live 通过;未改源码、未 commit。
</success_criteria>
<output>
Create `.planning/phases/10-docs-restructure/10-43-SUMMARY.md` when done
</output>
## 编号变更(2026-11-01)
本文件写作期的计划编号已因后续重排而改变,原文保持不变,读到时按下列映射理解:
- 本文件提到的「10-49 用户主导修订 + 收尾」→ 现为 `10-54-PLAN.md`(用户审阅 + 最终门禁 + 落位评估 + 收尾)。
- 本文件提到的旧「10-49 七个计划」中的读者审阅 / 用户修订两段 → 读者循环现为 `10-53-PLAN.md`(Round 2/3,Round 1 记录保留在 `10-49-READER-REVIEW.md`);用户审阅现为 `10-54-PLAN.md`。
- 新增的 `10-49`..`10-52` 是 Part 0–1 / 2–3 / 4 / 5 的深度扩写(D-93),`10-48` 仍是 pre-review 修复。
- 旧 `10-49-PLAN.md` / `10-50-PLAN.md` 已被新计划替换;本文件不因编号变更而改正文。
@@ -0,0 +1,327 @@
---
phase: 10-docs-restructure
plan: 44
type: execute
wave: 2
depends_on:
- 10-43
files_modified:
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- docs/.vitepress/config.ts
- docs/advanced/ii/ui/basic-shapes.md
- docs/advanced/ii/ui/container-and-coordinates.md
- docs/advanced/ii/ui/image-and-texture.md
- docs/advanced/ii/ui/layer-transform-performance.md
- docs/advanced/ii/ui/reactivity.md
- docs/advanced/ii/ui/events.md
- docs/advanced/ii/ui/hotkey-in-ui.md
- docs/advanced/ii/ui/conditional-and-list-rendering.md
- docs/.vitepress/components/demos/ui/texture-demo.tsx
- docs/.vitepress/components/demos/ui/layer-demo.tsx
- docs/.vitepress/components/demos/ui/events-demo.tsx
- docs/.vitepress/components/demos/ui/reactivity-demo.tsx
- docs/.vitepress/components/demos/ui/conditional-demo.tsx
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 76000
raw_tokens: 47000
tasks: 6
confidence: low
must_haves:
truths:
- "Part 1 收尾两篇(图片与最小纹理、层级/变换/性能)与 Part 2 四篇(响应式、事件与交互、按键与快捷键、条件与循环渲染)全部落地,每篇单 `#` H1、按 D-84 组织、末尾 `## 边界与注意`、CRLF"
- "性能篇明确「优先 `hidden`」:`hidden` 不显示、不交互、保留元素与状态、跳过绘制与命中;三元只在必须真正不存在 / 需要重置状态或生命周期 / 子树很重且长期不用时使用;`scale` 写成 `[x, y]` 数组、`rotate` 用弧度"
- "响应式篇从零讲 `ref` / `reactive` / `computed` / `watch`,讲清 TSX 里为什么写 `.value`、`reactive` 不能整体替换与解构会丢响应式、props 不要解构;不假设读者会 Vue"
- "事件篇覆盖 `onClick` / `onDown` / `onUp` / `onMove` / `onEnter` / `onLeave` / `onWheel` 与捕获变体,讲 `IActionEvent` 的坐标字段、`stopPropagation`、`noevent`、`cursor`、`actionStroke`,并说明 `enter` / `leave` 不走普通冒泡"
- "按键篇只写 UI 作者会用到的部分:`props.state.hotkey.system`、`useKey(...)!`、`implement`、注册新指令与分组、`HotkeyEmitMode`、优先级与阻断、UI 相关默认按键表;不展开按键系统的存档、监听与内部匹配"
- "条件与循环篇按 `dev.md:122` 写 `key` 规则:`.map()` 用于循环,`key` 只在列表会重排 / 插入 / 删除且需要保留身份时加,不为规避重挂载问题加 `key`"
- "5 个 live demo(texture / layer / events / reactivity / conditional)默认导出、无 DOM 属性;其中 layer / events / reactivity / conditional 只 import vue 与元素标签,唯一例外是 `texture-demo.tsx` 可以 `import { Texture } from '@motajs/render'`(元素层类,不是渲染器),除此之外不得 import 任何 `@motajs/*` / `@user/*`;页面用 `&lt;ClientOnly&gt;` + `() =&gt; import('...')`;按键篇不配伪装成引擎按键的 live"
- "侧边栏新增「交互与数据」分组 4 条、「元素与布局」补 2 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link"
- "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning"
- "未改 `packages/` / `packages-user/` / `src/`、未改 10-43 已验收的 6 篇正文与 5 个 demo 的语义(第 3 / 4 篇各只回填一处跨页链接,不改文字语义)、未改 `10-01`..`10-43` 计划、未改既有 JSDoc/注释;不 commit"
artifacts:
- "docs/advanced/ii/ui/image-and-texture.md、layer-transform-performance.md、reactivity.md、events.md、hotkey-in-ui.md、conditional-and-list-rendering.md"
- "docs/.vitepress/components/demos/ui/texture-demo.tsx、layer-demo.tsx、events-demo.tsx、reactivity-demo.tsx、conditional-demo.tsx"
- "docs/.vitepress/config.ts(高级 II 子分组内新增「交互与数据」、补「元素与布局」两条)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-44 命名确认、门禁与人工验证记录)"
key_links:
- "第 8 篇的 `hidden` 口径与第 12 篇的条件渲染口径必须一致:两处都写「不显示、不交互、保留状态、跳过绘制与命中」,否则读者会在两篇之间得到相反结论"
- "第 9 篇的响应式是第 10、12、13 篇的前置:事件回调用 `ref` 改状态、条件用 `hidden` 读状态、组件用 props 收状态;这三处的示例都要能回到第 9 篇的同一套写法。第 9 篇对第 13 篇只写纯文本前瞻引用,链接由 10-45 创建第 13 篇时回填;本批创建第 8、10 篇后要回填 10-43 第 3、4 篇的纯文本前瞻引用(只加链接,不改文字语义)"
- "第 11 篇的 `useKey` 作用域跟随组件挂载 / 卸载;示例只写 `useKey(props.state.hotkey.system)!` 与 `implement`,不引导读者自己监听键盘"
- "第 7 篇的最小纹理与第 17 篇的 `image` 相关组件共用 `ITexture` 概念;本篇只讲最小可运行纹理,不展开素材管线"
---
<scope_justification>
本计划 6 个任务、15 个 `files_modified`,超出默认上限,保持单计划:
- 6 篇正文分三个写作任务(2 + 2 + 2),每个任务都能独立验证「两篇 + 对应 demo + 侧边栏」;门禁与人工验证各自独立成任务,无法再合并。
- 15 个文件里 6 篇正文、5 个 demo、2 篇**只回填链接**的 10-43 已验收页面(第 3 篇 `container-and-coordinates.md`、第 4 篇 `basic-shapes.md`——10-43 约定目标页不存在时只写纯文本,由本批创建第 8 / 10 篇后回填 markdown 链接)、1 个侧边栏、1 个记录文件;它们共享同一份参考清单哈希、同一套写作规则与同一次构建。
- 承接 10-43 的拆分:Part 1 后两篇随 Part 2 一起做,是因为这两篇(纹理与性能)都需要「响应式 / 事件」已建立的概念做对照;放在同一计划可避免跨计划重复解释。
不删内容:6 篇正文、5 个 live、按键默认表、性能口径、`key` 规则、六类门禁、用户目视全部保留。
</scope_justification>
<objective>
落地子分组的第二批 6 篇:Part 1 收尾的「图片与最小纹理」「层级、变换与性能」,以及 Part 2 的「响应式」「事件与交互」「按键与快捷键」「条件与循环渲染」。这一批把读者从「会画静态图形」推到「会接交互、会读数据、会按条件与列表组织画面」。
Purpose: 元素与布局讲完之后,读者必须能用状态驱动画面、用事件接住点击、用按键收口操作,并且知道什么时候用 `hidden`、什么时候必须让元素真正消失。这一批也是后面组件化与内置组件的前置。
Output: 6 篇正文、5 个 `.tsx` live demo、侧边栏两处登记、NOTES 追加记录。**不改源码、不改 10-43 已验收内容、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md
@.planning/phases/10-docs-restructure/10-43-PLAN.md
@docs/.vitepress/config.ts
@docs/advanced/ii/ui/text.md
@docs/.vitepress/components/demos/ui/template-demo.tsx
@docs/.vitepress/components/demos/ui/shapes-demo.tsx
**流程约定:**
- 本计划是 Phase 10 的增量派发:只新增/修改本计划 `files_modified` 内文件;不改 `10-01`..`10-43` 计划文件;不重规划其它批次。
- **Task 0 是硬关卡**:向用户汇报本计划 6 篇写什么、demo 名、live 取舍、以及第 7 篇的纹理造法选项,等用户明确回复「可以执行」。
- 6 篇文件名与侧边栏名已在 10-43 的命名总表里确认;本计划 Task 0 只需复述确认值并等「可以执行」,**若用户在本轮改动命名**,先更新 NOTES 命名总表再落盘。
- 每次改文件前必须声明是「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理(AGENTS.md)。
- 不得调用 `opencode` 命令;不得修改任何既有 JSDoc / 注释(新增文件除外);不做 git commit / push。
**本批写作硬规则(与 10-43 完全一致,不再重复展开):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。
**参考文件与哈希:** 以 `10-CUSTOM-UI-RESEARCH.md` 的 `## Reference Manifest` 与 NOTES 的「参考清单哈希基线」为准。写作前对本计划涉及的文件(`core/misc.ts`、`core/item.ts`、`core/canvas2d.ts`、`core/transform.ts`、`assets/texture.ts`、`core/event.ts`、`core/container.ts`、`system/src/hotkey/*`、`client-base/src/use/hotkey.ts`、`client-base/src/hotkey/hotkey.ts`)重跑 `git hash-object -- <path>` 比对;任一不一致或 `git status --porcelain` 非空即停下问用户。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报本计划 6 篇与 live 取舍得,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、参考清单哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 7–12 篇、Performance、Hotkey、Common Pitfalls)、docs/advanced/ii/ui/text.md(Page 6 已落地体例)、docs/.vitepress/config.ts(10-43 建好的子分组结构)</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——落地 6 篇:图片与最小纹理、层级/变换与性能、响应式、事件与交互、按键与快捷键、条件与循环渲染;配 5 个 `.tsx` live,按键篇不配 live。
**为什么**——读者在会画静态图形之后,必须先学会「状态驱动画面」,才能接交互、接按键、接列表;性能篇把 `hidden` 的口径一次讲定,后面组件化与完整示例都直接引用它。Part 1 的两篇在此收尾,是因为它们与响应式 / 事件互为对照。
**大致怎么做**——Task 1 写纹理篇与性能篇 + `texture-demo` / `layer-demo`;Task 2 写响应式篇与事件篇 + `reactivity-demo` / `events-demo`;Task 3 写按键篇与条件循环篇 + `conditional-demo`;Task 4 跑六类门禁并写 NOTES;Task 5 由用户目视 5 个 live 并抽查正文。
**影响范围**——新增 `docs/advanced/ii/ui/` 下 6 个 `.md` 与 `demos/ui/` 下 5 个 `.tsx`;加法式追加侧边栏 6 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、10-43 已验收的 6 篇与 5 个 demo、POC 页、ROADMAP / STATE。
**必须请用户确认的两点:**
1. **第 7 篇的最小纹理造法**(研究文件 Q2,尚未定):推荐用 `document.createElement('canvas')` 画一个色块再包成纹理,因为最直观、不依赖素材;备选是用 `ImageBitmap` 或一张现成图片占位。请用户选一个。
2. **live 取舍**:纹理 / 层级变换 / 事件 / 响应式 / 条件循环五篇配 live;按键篇**不配** live(文档站没有游戏的按键系统,配一个假的会误导读者),只放代码块并在正文标明这一点。若用户要求按键篇也要 live,必须先说明「只能演示浏览器键盘事件,不是引擎按键」。
同时复述 6 篇文件名与侧边栏显示名(沿用 10-43 的命名总表)与 5 个 demo 名,确认无改动。**参考文件:`packages/render/src/core/misc.ts`、`core/item.ts`、`core/canvas2d.ts`、`core/transform.ts`、`core/event.ts`、`core/container.ts`、`assets/texture.ts`、`packages/system/src/hotkey/*`、`packages-user/client-base/src/use/hotkey.ts`、`client-base/src/hotkey/hotkey.ts`;策略:写作前逐条 `git hash-object -- <path>` 与 Manifest / NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。</action>
<what-built>尚无产物;本任务只汇报本计划范围、live 取舍与第 7 篇纹理方案。</what-built>
<how-to-verify>确认:①是否同意本计划 6 篇与 5 个 live 的范围;②第 7 篇最小纹理用 canvas 自造 / `ImageBitmap` / 现成图片占位(三选一);③是否接受按键篇不配 live;④6 篇文件名与侧边栏名是否沿用 10-43 确认值。</how-to-verify>
<resume-signal>回复「可以执行」以继续(请同时给出纹理方案选择);其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且纹理造法方案、按键篇 live 取舍、6 篇命名三项均已确定;NOTES 命名总表如被改动已同步。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,并已选定纹理方案与按键篇 live 取舍;命名沿用或在 NOTES 中同步。</human-check>
</verify>
<done>用户回复「可以执行」且三项待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 图片与最小纹理 / 层级、变换与性能 两篇 + 两个 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/.vitepress/components/demos/ui/texture-demo.tsx, docs/.vitepress/components/demos/ui/layer-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/container-and-coordinates.md</files>
<precondition>本计划的 Task 0 已回复「可以执行」并选定纹理方案;10-43 的 6 篇与侧边栏骨架存在且构建 green。本任务负责把 `用户确认(10-44):可以执行` 与用户原文追加进 NOTES。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 7、8 篇;Render Elements 的属性默认值 / 缓存默认值;Performance 全节;`docs/guide/ui/perf.md` 的可用结论)、packages/render/src/core/misc.ts:150-192(image 元素语义)、packages/render/src/assets/texture.ts、packages/render-vue/src/props.ts:24-81(`hd` / `anti` / `noanti` / `cache` / `nocache` / `scale` / `rotate`)、dev.md:116-123(换行与 `key` 规则)、docs/.vitepress/config.ts</read_first>
<action>先向 NOTES 末尾追加本节(`## 10-44 命名确认`),写独占一行 `用户确认(10-44):可以执行`、下一行 `用户原文:`、纹理方案最终选择、按键篇 live 取舍、6 篇与 5 个 demo 的最终名;并重跑本任务涉及参考文件的 `git hash-object` 比对,把结果追加到哈希表。然后写两篇正文与两个 demo。
**(1)`image-and-texture.md`(第 7 篇)**:先回答「图片元素需要什么」——一个纹理对象 + 元素的宽高(按元素框拉伸)。讲 `image` 元素:`image` 属性接收纹理,`loc` 决定绘制区域。讲最小纹理怎么造:按 Task 0 选定方案给完整片段——若选 canvas,就在组件外或 `onMounted` 里画一个色块 / 棋盘,再包成纹理;若选 `ImageBitmap` 或现成图片,就给对应写法与加载时机的说明。讲像素图设置:`noanti` 关抗锯齿、`hd={false}` 关高清缓存,并说明为什么要一起关(放大时边缘不被插值模糊)。`icon` / `winskin` / `map-render` 只用一两句话说明是应用层素材标签、本篇不展开,**不写内部实现**。`## 边界与注意`:纹理创建有成本,不要在每次渲染里重复造;图片按元素宽高拉伸,比例不对会变形;纹理对象不要在组件卸载后继续被引用(一句话点到,不展开生命周期细节)。
**(2)`layer-transform-performance.md`(第 8 篇)**:按「遮挡 → 变换 → 显示开关 → 缓存」的顺序讲:
- `zIndex` 决定遮挡,同级越大越靠上;给出两个重叠矩形换序的示例。
- `scale` 必须是 `[x, y]` 数组;`rotate` 用弧度;`alpha` 改不透明度;三者都在元素自己的坐标系里生效。
- **`hidden` 优先**:明确写「`hidden` 不显示、不交互,但保留元素与状态,并跳过绘制与命中」,给出用按钮切换 `hidden` 的示例;再说明三元表达式会创建 / 销毁并重置状态,只在「必须真正不存在」「需要重置状态或生命周期」「子树很重且长期不用」,以及「必须彻底摘掉事件监听、或不能接受隐藏元素继续占内存」时使用。这一段的口径必须与第 12 篇一致。
- 缓存:讲 `cache` / `nocache` 的默认取向(容器类默认缓存、图形 / 文字 / 图片默认不缓存),以及什么情况值得打开缓存;`hd` / `anti` / `noanti` 一句带过并指向第 7 篇。
- `noevent`:元素可见但不接收交互,且会让 `cursor` 失效;给出一个遮罩示例。
- `filter` / `composite` 各一句话,说明存在即可,不展开取值表。
- 末尾给一张「什么时候用 `hidden`、什么时候用三元」的判定表。
`## 边界与注意`:`scale` 写数字无效;`rotate` 单位是弧度;改锚点会连同变换一起改变视觉位置;缓存打开后内容变化需要让元素知道自己脏了,简单场景优先不缓存。
**(3)两个 demo**:`texture-demo.tsx`(`TextureDemo`)显示动态生成的最小纹理 + 一个 `noanti hd={false}` 对照;`layer-demo.tsx`(`LayerDemo`)用按钮切换 `hidden` / `alpha` / `scale` 并展示 `zIndex` 遮挡。都默认导出、无 DOM 属性。`layer-demo` **只** import vue 与元素标签;`texture-demo` 额外允许 `import { Texture } from '@motajs/render'`(元素层类,不是渲染器),除此之外不得 import 任何 `@motajs/*` / `@user/*`。`texture-demo` 里造纹理的代码只跑一次(`onMounted` 或模块内常量),并在注释里写明原因。
**(5)回填第 3 篇的跨页链接**:`docs/advanced/ii/ui/container-and-coordinates.md` 里讲 `zIndex` 的那句现在写的是纯文本「第 8 篇『层级、变换与性能』」(10-43 的约定:目标页不存在时只写纯文本)。本任务已创建第 8 篇,把该纯文本改成 `[第 8 篇「层级、变换与性能」](./layer-transform-performance.md)`。**只改这一处链接,不改任何文字语义、不动该页其它内容。**
**(4)侧边栏**:在「元素与布局」分组末尾追加 `/advanced/ii/ui/image-and-texture` 与 `/advanced/ii/ui/layer-transform-performance` 两条。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/image-and-texture.md":["image","noanti","hd","icon","winskin","map-render"],"docs/advanced/ii/ui/layer-transform-performance.md":["zIndex","scale","rotate","alpha","hidden","cache","nocache","noevent","三元","filter","composite"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const L=fs.existsSync("docs/advanced/ii/ui/layer-transform-performance.md")?rd("docs/advanced/ii/ui/layer-transform-performance.md"):"";if(L.indexOf("不显示、不交互")<0){bad.push("HIDDEN-SEMANTICS")}if(!/三元/.test(L)){bad.push("NO-TERNARY")}if(!/重置/.test(L)){bad.push("NO-RESET")}["texture-demo.tsx","layer-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(f==="texture-demo.tsx"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+f);if(s.indexOf("Texture")<0)bad.push("DEMO-NO-TEXTURE:"+f)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f)}});const p3=rd("docs/advanced/ii/ui/container-and-coordinates.md");if(p3.indexOf("](./layer-transform-performance.md)")<0)bad.push("BACKFILL-P3");const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/image-and-texture","/advanced/ii/ui/layer-transform-performance","/advanced/ii/ui/text","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-44", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "HIDDEN-SEMANTICS", "NO-TERNARY", "NO-RESET", "NO-DEMO", "DEMO-", "DEMO-NO-TEXTURE", "BACKFILL-P3", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 追加了 10-44 命名确认(含独占一行确认标记 + 用户原文 + 纹理方案 + 按键 live 取舍)与哈希比对结果;纹理篇覆盖 image / noanti / hd / 三个占位标签;性能篇覆盖 zIndex / scale 数组 / rotate 弧度 / alpha / hidden 语义 / cache / noevent / filter / composite,并用判定表区分 `hidden` 与三元;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;`layer-demo` 只 import vue 与元素标签,`texture-demo` 只额外 import `@motajs/render` 的 `Texture`,两者都默认导出且无 DOM 属性;第 3 篇(`container-and-coordinates.md`)里对第 8 篇的纯文本引用已回填为 `./layer-transform-performance.md` 链接且该页其它内容未变;侧边栏新增两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>纹理篇与性能篇完成,`hidden` 口径与后续篇章统一。</done>
</task>
<task type="auto">
<name>Task 2: 响应式 / 事件与交互 两篇 + 两个 demo + 侧边栏「交互与数据」</name>
<files>docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/.vitepress/components/demos/ui/reactivity-demo.tsx, docs/.vitepress/components/demos/ui/events-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/basic-shapes.md</files>
<precondition>NOTES 含 `用户确认(10-44):可以执行`;Task 1 两篇已落盘且构建 green。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 9、10 篇;Vue / TSX Integration 全节;事件类型与字段)、packages/render/src/core/event.ts:52-134(事件名与字段)、packages/render/src/core/item.ts:757、1106-1109(noevent 与 cursor)、packages/render/src/core/container.ts:93-116(捕获与冒泡顺序)、Vue 官方文档 reactivity-fundamentals(2026-10-30 读取)</read_first>
<action>写两篇正文与两个 demo,并建立「交互与数据」分组。
**(1)`reactivity.md`(第 9 篇)**:从零讲,不假设读者会 Vue。顺序:
- 问题:画面要跟着数据变,手写「改数据再重画」迟早漏。
- `ref`:`const count = ref(0)`;在 TSX 里读要写 `count.value`,模板渲染函数里也一样——这一点必须讲透,并解释为什么(`ref` 是一个带 `value` 的盒子,Vue 靠读它来追踪依赖)。
- `reactive`:适合一整块对象;讲两条限制——不能整体替换、解构会丢响应式,并给出替代写法。
- `computed`:派生值,示例 `const doubled = computed(() => count.value * 2)`,说明它惰性求值且会缓存。
- `watch`:副作用,示例监听 `count` 打印一行;说明什么时候用 `watch`、什么时候其实用 `computed` 更合适。
- 一小节「什么时候用 `shallowRef` / `markRaw`」:只讲判断依据(大对象、不需要深层响应、外部实例),不展开内部机制。
- 最后一小节「props 不要解构」,**只写纯文本「第 13 篇『组件与 props』」**——第 13 篇在 10-45 创建,此处不写 markdown 链接,由 10-45 回填。
`## 边界与注意`:`reactive` 不能整体替换;解构会丢响应式;`ref` 忘记 `.value` 是最常见错误;不要在渲染函数里做副作用。
**(2)`events.md`(第 10 篇)**:先讲命中测试:事件先找到最上层被点到的元素,再沿容器向外传递。然后:
- 事件名用 `on` + 事件名(`onClick` / `onDown` / `onUp` / `onMove` / `onEnter` / `onLeave` / `onWheel`),捕获阶段在名字后加 `Capture`;**不要**写成模板指令语法(这一点用文字说明,不给反例代码)。
- 事件对象字段:相对元素的坐标、相对画布的坐标、`identifier`、`type`、`buttons` 与修饰键;给一个把坐标显示到文字元素上的示例。
- 捕获与冒泡:子元素先捕获、父元素后冒泡;`stopPropagation()` 在捕获阶段阻止继续捕获、在冒泡阶段阻止继续冒泡,但不阻止同一元素上的其它监听器。
- `enter` / `leave`:由根节点的悬停集合统一触发,不走普通冒泡,给一句提醒。
- `noevent`:元素可见但不接收交互,事件下穿,`cursor` 也不再生效;给一个遮罩示例。
- `cursor`:悬停时的鼠标样式,写在元素上。
- `actionStroke`:只把描边算作命中区域(链接回第 4 篇的说明)。
示例用「点击矩形换色 + 悬停改光标 + 滚轮改文字」一组,全部用 `ref` 驱动。`## 边界与注意`:属性名写错不报错也不触发;`hidden` 的元素既不绘制也不参与命中;`noevent` 与 `hidden` 是两件事,不要混用。
**(3)两个 demo**:`reactivity-demo.tsx`(`ReactivityDemo`)做计数器 + 计算属性 + 监听结果文字;`events-demo.tsx`(`EventsDemo`)做点击换色 + 悬停改光标 + 滚轮改文字,并把事件坐标写到文字元素上。都默认导出、只 import vue 与元素标签、无 DOM 属性。
**(4)侧边栏**:在子分组 `items` 里追加 `{ text: '交互与数据', collapsed: false, items: [...] }`,先放 `/advanced/ii/ui/reactivity` 与 `/advanced/ii/ui/events` 两条。只做加法。
**(5)回填第 4 篇的跨页链接**:`docs/advanced/ii/ui/basic-shapes.md` 的 live 说明里现在写的是纯文本「事件在第 10 篇展开」。本任务已创建第 10 篇,把该纯文本改成 `[第 10 篇「事件与交互」](./events.md)`。**只改这一处链接,不改任何文字语义、不动该页其它内容。**
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/reactivity.md":["ref(","reactive(","computed(","watch(","value","shallowRef","markRaw","解构"],"docs/advanced/ii/ui/events.md":["onClick","onDown","onUp","onMove","onEnter","onLeave","onWheel","Capture","stopPropagation","noevent","cursor","actionStroke"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["reactivity-demo.tsx","events-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const p4=rd("docs/advanced/ii/ui/basic-shapes.md");if(p4.indexOf("](./events.md)")<0)bad.push("BACKFILL-P4");const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/reactivity","/advanced/ii/ui/events","/advanced/ii/ui/image-and-texture","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(cfg.indexOf("交互与数据")<0)bad.push("CFG-NO-PART2");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-44", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "BACKFILL-P4", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>响应式篇含 `ref` / `reactive` / `computed` / `watch` / `.value` 解释 / `shallowRef` / `markRaw` / 解构警告,且从零讲、不假设读者会 Vue;事件篇含 7 个冒泡事件名 + 捕获变体 + `stopPropagation` / `noevent` / `cursor` / `actionStroke`,并说明 `enter` / `leave` 不普通冒泡;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;第 9 篇对第 13 篇只含纯文本前瞻引用(无 markdown 链接);两个 demo 默认导出、无 DOM 属性、不 import 任何引擎包;第 4 篇(`basic-shapes.md`)里对第 10 篇的纯文本引用已回填为 `./events.md` 链接且该页其它内容未变;侧边栏新增「交互与数据」两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>响应式篇与事件篇完成,交互与数据分组已建立。</done>
</task>
<task type="auto">
<name>Task 3: 按键与快捷键 / 条件与循环渲染 两篇 + 条件循环 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/hotkey-in-ui.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/.vitepress/components/demos/ui/conditional-demo.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-44):可以执行`;Task 2 已落盘并建好「交互与数据」分组;Task 0 已确认按键篇不配 live。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 11、12 篇;Hotkey 全节)、packages-user/client-base/src/use/hotkey.ts:6-71、packages/system/src/hotkey/types.ts:9-77、src/client/misc/hotkey.ts(默认按键与分组,只取 UI 相关行)、dev.md:116-123、docs/.vitepress/components/demos/ui/layer-demo.tsx(`hidden` 示例体例)</read_first>
<action>写两篇正文与一个 demo。
**(1)`hotkey-in-ui.md`(第 11 篇)**:只写 UI 作者会用到的部分。顺序:
- 问题:UI 里要让 Esc 关闭、Enter 确认,不要自己监听键盘。
- 按键系统的最小模型:指令(有名字、有默认按键)+ 作用域(跟着组件挂载 / 卸载)+ 实现(把指令接到当前作用域的回调)。
- `useKey`:在 `setup` 里 `const key = useKey(props.state.hotkey.system)!;`,说明组件内必定有实例所以用非空断言;讲作用域随卸载自动离开。
- `key.implement('@common/exit', () => props.controller.close(props.instance))`,并给一个再绑一条的示例。
- 注册新指令:`system.addCommand(...)`;分组:`hotkey.setGroup(...)`;说明为什么分组(设置界面按组显示)。
- 触发方式:`HotkeyEmitMode` 的三种(抬起、只触发一次、持续触发)各一句话;优先级与阻断各一句话,并说明「同优先级不互相阻断」。
- UI 相关默认按键表(`@common/confirm` / `@common/exit` / `@ui/menu` / `@ui/toolbox` / `@ui/command` / `@ui/save` / `@ui/load` / `@ui/book` / `@ui/input-confirm` 等),标明「默认值,玩家可在设置里改」。
- 明确一句:本篇不涉及按键系统的存档、监听与内部匹配。
**不配 live**,并在正文用一句话说明「文档站没有游戏的按键系统,因此本篇不提供可运行示例」。`## 边界与注意`:`useKey` 必须在 `setup` 中调用;作用域随组件卸载离开,不要在已卸载组件里继续用;同一次挂载里重复 `implement` 同一指令会覆盖;别把按键回调写成异步长任务。
**(2)`conditional-and-list-rendering.md`(第 12 篇)**:先讲 TSX 里没有模板指令,条件与循环都是普通表达式。
- 条件:**优先 `hidden`**——写清「不显示、不交互、保留元素与状态、跳过绘制与命中」,给一个开关面板的示例;再讲三元表达式会真正移除节点(组件卸载、状态重置),列出三类该用三元的场景(必须真正不存在 / 需要重置状态或生命周期 / 子树很重且长期不用),并补一句「需要彻底摘掉事件监听、或不能接受隐藏元素继续占内存时,也只能用三元」。
- 循环:用 `.map()` 生成一组元素;给一个固定顺序、无状态列表的例子并**不加** `key`,说明为什么不加。
- `key`:只在列表会重排 / 插入 / 删除且需要保留元素身份时加(引用 `dev.md:122` 的规则,用文字复述),给一个带 `key` 的可增删列表例子;明确不要为规避重挂载问题加 `key`。
- 一小节对比表:`hidden` vs 三元 vs `.map()` + `key`。
`## 边界与注意`:`hidden` 的元素仍在树里,数量和层级照旧;三元反复切换会反复重建,成本在组件初始化;`map` 返回的每一项都要有稳定结构;`key` 不是性能开关。
**(3)`conditional-demo.tsx`**:一个开关切换面板 `hidden`,一个可增删列表用 `.map()`(初始固定顺序的简单列表不加 `key`,可增删的那组加 `key`),并用文字显示「切换后状态是否保留」。默认导出、只 import vue 与元素标签、无 DOM 属性。
**(4)侧边栏**:在「交互与数据」分组追加 `/advanced/ii/ui/hotkey-in-ui` 与 `/advanced/ii/ui/conditional-and-list-rendering` 两条。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const hk="docs/advanced/ii/ui/hotkey-in-ui.md";const cd="docs/advanced/ii/ui/conditional-and-list-rendering.md";if(!fs.existsSync(hk))bad.push("MISSING:"+hk);else{const s=rd(hk);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+hk);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+hk);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+hk+":"+r)});["useKey(","implement(","addCommand","setGroup","HotkeyEmitMode","@common/exit","@common/confirm","priority"].forEach(function(k){if(s.indexOf(k)<0)bad.push("HK:"+k)});if(/saveState|loadState|preventDefault/.test(s))bad.push("HK-INTERNAL");if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+hk);if(/\x3cClientOnly\x3e/.test(s))bad.push("HK-UNEXPECTED-LIVE")}if(!fs.existsSync(cd))bad.push("MISSING:"+cd);else{const s=rd(cd);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+cd);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+cd);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+cd+":"+r)});["hidden",".map(","key","三元","重置"].forEach(function(k){if(s.indexOf(k)<0)bad.push("CD:"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+cd);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+cd);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+cd)}const d="docs/.vitepress/components/demos/ui/conditional-demo.tsx";if(!fs.existsSync(d))bad.push("NO-DEMO");else{const s=rd(d);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT");if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE");if(/style=|class=/.test(s))bad.push("DEMO-DOM");if(!/\.map\(/.test(s))bad.push("DEMO-NO-MAP");if(s.indexOf("hidden")<0)bad.push("DEMO-NO-HIDDEN")}const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/hotkey-in-ui","/advanced/ii/ui/conditional-and-list-rendering","/advanced/ii/ui/reactivity","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-44", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "HK:", "HK-INTERNAL", "HK-UNEXPECTED-LIVE", "CD:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>按键篇含 `useKey(...)!` / `implement` / `addCommand` / `setGroup` / `HotkeyEmitMode` / 优先级 / UI 相关默认按键表,且不出现按键系统的存档与监听接口、不配 live;条件循环篇含 `hidden` 优先、三元场景、`.map()`、`key` 规则与对比表,且与第 8 篇口径一致;两篇单 H1、有边界节、CRLF、无被禁写法;条件循环篇接 live、按键篇不接;demo 含 `.map(` 与 `hidden`;侧边栏新增两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>按键篇与条件循环篇完成,Part 2 四篇齐备。</done>
</task>
<task type="auto">
<name>Task 4: 六类门禁收口 + NOTES 记录</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1..3 的 6 篇与 5 个 demo 已落盘、侧边栏 6 条齐全、构建 green。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts</read_first>
<action>按固定顺序跑门禁并记录,顺序不可颠倒:
1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。
2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning;布尔 JSX 属性用简写,不得为消告警改渲染属性名。
3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:只要求 `docs/` 路径 0 报错;引擎既有报错记条数与摘要。
4. 静态断言:6 篇单 H1 / `## 边界与注意` / 无被禁写法 / 该配 live 的五篇有 `<ClientOnly>` + 动态 loader / 按键篇不接 live / 5 个 demo 默认导出且无 DOM 属性(`texture-demo` 允许且仅允许 `@motajs/render` 的 `Texture`)/ 侧边栏 12 条(本批 6 条 + 10-43 的 6 条)都在 / 第 3 与第 4 篇的跨页链接已回填。
5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。
6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-44 门禁` 小节:六类命令与结果、`docs/` 路径类型报错 0、既有引擎报错条数、构建耗时、本批 6 篇与 5 个 demo 清单。
7. 交叉一致性检查并写进该小节:第 8 篇与第 12 篇的 `hidden` 表述逐字同义(「不显示、不交互」+「保留元素与状态」);第 6 篇对第 17 篇仍是纯文本前瞻引用(链接由 10-46 回填),本批未引入任何指向未创建页面的链接;第 3 / 4 篇的跨页链接已回填且构建 0 dead link。
本任务不改正文语义,只做格式化、断言与记录。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const live=["image-and-texture","layer-transform-performance","reactivity","events","conditional-and-list-rendering"];const md=live.concat(["hotkey-in-ui"]);md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m);if(live.indexOf(m)>=0){if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m)}});const hk=rd("docs/advanced/ii/ui/hotkey-in-ui.md");if(hk.indexOf("\x3cClientOnly\x3e")>=0)bad.push("HK-LIVE");const L=rd("docs/advanced/ii/ui/layer-transform-performance.md");const C=rd("docs/advanced/ii/ui/conditional-and-list-rendering.md");[L,C].forEach(function(s,i){if(s.indexOf("不显示、不交互")<0)bad.push("HIDDEN-SEMANTICS:"+i);if(s.indexOf("保留")<0)bad.push("HIDDEN-KEEP:"+i)});["texture-demo","layer-demo","events-demo","reactivity-demo","conditional-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(m==="texture-demo"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+m)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+m)}if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m)});const p3=rd("docs/advanced/ii/ui/container-and-coordinates.md");const p4=rd("docs/advanced/ii/ui/basic-shapes.md");if(p3.indexOf("](./layer-transform-performance.md)")<0)bad.push("BACKFILL-P3");if(p4.indexOf("](./events.md)")<0)bad.push("BACKFILL-P4");const cfg=rd("docs/.vitepress/config.ts");const links=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering"];links.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-44 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-44", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "HIDDEN-", "HK-LIVE", "BACKFILL-", "NOTES-NO-"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>prettier `--write` / `--check` 通过;ESLint 0 error / 0 warning;`docs/` 路径类型报错 0;静态断言全绿(6 篇单 H1 / 边界节 / 无被禁写法 / 五篇接 live 且按键篇不接 / 5 个 demo 默认导出、无 DOM 属性,`texture-demo` 仅额外允许 `@motajs/render` 的 `Texture` / 侧边栏 12 条齐全 / 既有条目与高级 III 未丢 / 第 8 与第 12 篇 `hidden` 口径一致 / 第 3、4 篇跨页链接已回填);构建 green、无 dead link;NOTES 有 `### 10-44 门禁` 且含 `docs/ 路径类型报错 0` 与既有引擎报错摘要。</acceptance_criteria>
<done>第二批 6 篇 5 demo 通过六类门禁并已记录。</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 5: 用户目视 5 个 live 并抽查 6 篇正文</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 4 通过(六类门禁全绿、构建产物已生成、NOTES 已记录)。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/(本批 5 个 demo)</read_first>
<action>请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 6 篇,逐条确认:①侧边栏「元素与布局」补齐 6 条、「交互与数据」4 条,全部可点开;②纹理篇 live 能看到最小纹理与关抗锯齿后的像素边缘;③性能篇 live 能切换 `hidden` / `alpha` / `scale`,遮挡顺序正确;④响应式篇 live 的计数、计算值与监听输出一致变化;⑤事件篇 live 点击换色、悬停光标、滚轮改文字都生效;⑥条件循环篇 live 切换时状态保留、增删列表正常;⑦按键篇没有 live,正文明确说明原因;⑧抽查第 8 与第 12 篇:两处对 `hidden` 的说法一致。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-44):通过` + 下一行 `用户原文:`;发现问题则逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 4 后再复验。只有用户明确通过才可进入 10-45。</action>
<what-built>6 篇正文与 5 个 live demo,构建产物可在本地预览。</what-built>
<how-to-verify>按上面①–⑧逐条检查;重点看 `hidden` 切换是否真的不绘制不命中、事件三件套是否都生效、两篇的 `hidden` 口径是否一致。</how-to-verify>
<resume-signal>若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。</resume-signal>
<acceptance_criteria>用户明确回复 live 与正文均通过,且 NOTES 有人工验证标记与用户原文;否则问题清单已记录并进入修复循环。</acceptance_criteria>
<verify>
<human-check>用户已明确确认 6 篇可读、5 个 live 正常、按键篇不配 live 的说明清楚,并已把结论记入 NOTES。</human-check>
</verify>
<done>用户人工验证结论已记录。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 构建期(SSR)→ live demo | demo 必须由 `RenderDemo` 在浏览器端动态 import;页面不得静态 import demo |
| demo → 纹理创建 | 纹理只在本地用浏览器 API 造,不加载远程图片、不发请求 |
| 按键文档 → 读者 | 文档站没有游戏的按键系统,按键篇不提供可能被误认为引擎行为的 live |
| 侧边栏 → 页面 | 每条 link 必须对应已存在页面,否则构建 dead link 失败 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-134 | Denial of Service(构建不可用) | `.tsx` demo 与纹理创建 | high | mitigate | demo 只由 loader 动态 import、`<ClientOnly>` 包裹;纹理在 `onMounted` 或模块常量里造一次;构建门禁必须 `build complete` |
| T-10-135 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页同任务完成;静态断言复核 12 条链接与既有条目未丢;构建 0 dead link |
| T-10-136 | Information Disclosure | 按键篇误写成内部实现 | low | mitigate | 静态断言禁 `saveState` / `loadState` / `preventDefault`;正文只写 `useKey` / `implement` / 注册与分组 |
| T-10-137 | Repudiation | 命名与门禁无据可查 | medium | mitigate | NOTES 追加式记录命名确认、哈希比对、门禁与人工验证;每个 auto 任务复检 `用户确认(10-44):可以执行` |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告,不得临时安装 |
</threat_model>
<verification>
- 确认门禁:NOTES 含 `用户确认(10-44):可以执行` + `用户原文:`;Task 5 后含 `用户人工验证(10-44):通过` + `用户原文:`,无 `状态:待处理`。
- 内容门禁:6 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性。
- 一致性门禁:第 8 与第 12 篇都含「不显示、不交互」与「保留」;第 6 篇对第 17 篇仍是纯文本前瞻引用(链接由 10-46 回填),第 9 篇对第 13 篇同样是纯文本;本批未引入任何指向未创建页面的链接;第 3 / 4 篇的跨页链接已回填。
- 示例门禁:五篇接 live(`<ClientOnly>` + 动态 loader),按键篇不接;5 个 demo 默认导出、无 DOM 属性;`layer` / `events` / `reactivity` / `conditional` 不 import 引擎包,`texture-demo` 仅额外 import `@motajs/render` 的 `Texture`。
- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。
- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改 10-43 已验收的 6 篇与 5 个 demo 的语义;未改 `10-01`..`10-43` 计划;未 commit;ROADMAP / STATE 本计划不改。
</verification>
<success_criteria>
- 读者读完这一批,能用状态驱动画面、接住点击与滚轮、用按键收口操作,并知道 `hidden` 与三元的取舍。
- 6 篇正文与 5 个 live 全部可用;按键篇明确交代不配 live 的原因,不误导读者。
- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。
</success_criteria>
<output>
Create `.planning/phases/10-docs-restructure/10-44-SUMMARY.md` when done
</output>
@@ -0,0 +1,179 @@
---
phase: 10-docs-restructure
plan: 44
subsystem: docs
tags: [vitepress, tsx, ui, texture, reactivity, events, hotkey, conditional-rendering]
requires:
- phase: 10-docs-restructure
provides: 10-43 的 6 篇元素与布局正文、5 个 live demo、侧边栏子分组骨架
provides:
- Part 1 收尾两篇(图片与最小纹理、层级/变换与性能)
- Part 2 四篇(响应式、事件与交互、按键与快捷键、条件与循环渲染)
- 5 个 live demo 与侧边栏「交互与数据」分组
- 第 3 / 4 篇跨页链接回填
affects: [10-45, 10-46, 10-47]
actuals:
tokens: 9666
tasks: 5
commits: 0
tech-stack:
added: []
patterns:
- hidden 优先、三元只用于必须卸载/重置/释放的场景
- ref / reactive / computed / watch 的 UI 写作口径
- 事件 onXxx + 捕获变体,enter/leave 不按普通冒泡
- useKey 作用域跟随组件生命周期
key-files:
created:
- docs/advanced/ii/ui/image-and-texture.md
- docs/advanced/ii/ui/layer-transform-performance.md
- docs/advanced/ii/ui/reactivity.md
- docs/advanced/ii/ui/events.md
- docs/advanced/ii/ui/hotkey-in-ui.md
- docs/advanced/ii/ui/conditional-and-list-rendering.md
- docs/.vitepress/components/demos/ui/texture-demo.tsx
- docs/.vitepress/components/demos/ui/layer-demo.tsx
- docs/.vitepress/components/demos/ui/events-demo.tsx
- docs/.vitepress/components/demos/ui/reactivity-demo.tsx
- docs/.vitepress/components/demos/ui/conditional-demo.tsx
modified:
- docs/.vitepress/config.ts
- docs/advanced/ii/ui/container-and-coordinates.md
- docs/advanced/ii/ui/basic-shapes.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
key-decisions:
- "第 7 篇最小纹理用 document.createElement('canvas') 画棋盘再包成 Texture"
- "按键篇不配 live:文档站没有游戏按键系统,避免误导读者"
- "hidden 与三元的口径在第 8、12 篇保持逐字同义"
- "第 9 篇对第 13 篇、第 6 篇对第 17 篇仍为纯文本前瞻引用,链接留给后续批次回填"
requirements-completed: []
coverage:
- id: D1
description: "图片与最小纹理篇 + texture live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "live 的纹理放大效果需要人眼确认像素边缘是否清晰"
- id: D2
description: "层级、变换与性能篇 + layer live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "hidden / alpha / scale 切换与遮挡顺序需要人工目视"
- id: D3
description: "响应式篇 + reactivity live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "计数、计算值与监听输出的一致性需要人工目视"
- id: D4
description: "事件与交互篇 + events live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "点击、悬停光标、滚轮与坐标显示需要人工操作确认"
- id: D5
description: "按键与快捷键篇(无 live)"
verification:
- kind: automated_ui
ref: "静态断言禁止 <ClientOnly> 与内部接口"
status: pass
human_judgment: true
rationale: "正文是否清楚交代「不配 live 的原因」需要人工审阅"
- id: D6
description: "条件与循环渲染篇 + conditional live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "hidden 切换后的状态保留与列表增删需要人工目视"
duration: 15min
completed: 2026-10-31
status: complete
---
# Phase 10 Plan 44: 交互与数据批次 Summary
**六篇正文与五个 TSX live 落地,第 8/12 篇统一 hidden 口径,侧边栏补齐 12 条并回填两条跨页链接**
## Performance
- **Duration:** 15 min
- **Started:** 2026-10-31 17:57(本地时间)
- **Completed:** 2026-10-31 18:12(本地时间)
- **Tasks:** 5(Task 0 记录 + Task 1..4;Task 5 live 人工验证待最终审阅)
- **Files modified:** 15
## Accomplishments
- 新增 `image-and-texture.md` 与 `layer-transform-performance.md`,并配 `texture-demo` / `layer-demo`。
- 新增 `reactivity.md` 与 `events.md`,建立侧边栏「交互与数据」分组,并配 `reactivity-demo` / `events-demo`。
- 新增 `hotkey-in-ui.md`(不配 live)与 `conditional-and-list-rendering.md`,并配 `conditional-demo`。
- 回填第 3 篇指向第 8 篇、第 4 篇指向第 10 篇的跨页链接;只改链接,不改文字语义。
- 六类门禁全绿:prettier、ESLint、docs 类型、静态断言、全量构建。
## Files Created/Modified
- `docs/advanced/ii/ui/image-and-texture.md` - 图片元素、canvas 最小纹理、像素图设置
- `docs/advanced/ii/ui/layer-transform-performance.md` - zIndex、变换、hidden、缓存、noevent
- `docs/advanced/ii/ui/reactivity.md` - ref / reactive / computed / watch / shallowRef / markRaw
- `docs/advanced/ii/ui/events.md` - 命中、事件名、捕获冒泡、noevent、cursor、actionStroke
- `docs/advanced/ii/ui/hotkey-in-ui.md` - useKey / implement / addCommand / setGroup / 默认按键
- `docs/advanced/ii/ui/conditional-and-list-rendering.md` - hidden vs 三元、map 与 key
- `docs/.vitepress/components/demos/ui/*.tsx` - 5 个 live demo(texture / layer / events / reactivity / conditional)
- `docs/.vitepress/config.ts` - 元素与布局补 2 条、「交互与数据」新增 4 条
- `docs/advanced/ii/ui/container-and-coordinates.md` - 第 8 篇链接回填
- `docs/advanced/ii/ui/basic-shapes.md` - 第 10 篇链接回填
- `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md` - 10-44 命名确认、哈希复核、门禁与待审记录
## Decisions Made
- 纹理方案采用 canvas 自造棋盘,符合 Task 0 推荐方案。
- 按键篇不配 live,正文用一小节说明「文档站没有游戏按键系统」。
- `hidden` 与三元的选择写成判定表,第 8、12 篇共用同一口径。
- 第 9 篇对第 13 篇保持纯文本前瞻引用,等 10-45 建页后回填。
## Deviations from Plan
None - 计划内容按原样落地(仅执行机制上适配了 PowerShell 5.1 的引号/标准错误行为,未改任何断言)。
## Issues Encountered
- PowerShell 5.1 把 `node -e` 的内嵌引号剥离,导致计划里的 `<automated>` 片段不能原样执行;改为把同一段 JS 写入临时 `.cjs` 后运行,断言内容未变。
- PowerShell 把构建的标准错误输出当作终止错误;执行时将该段 `$ErrorActionPreference` 临时设为 `Continue`,构建结果仍按退出码、`build complete` 与 dead link 判定。
## Gates
| 门禁 | 结果 |
|------|------|
| prettier `--write` / `--check` | 通过,`All matched files use Prettier code style!` |
| ESLint | 0 error / 0 warning |
| `vue-tsc -p docs/tsconfig.json` | `docs/` 路径 0 报错;既有引擎报错 11 条(非本轮引入) |
| 静态断言 | `STATIC-OK` |
| 全量构建 | green,`build complete in 15.35s.`,无 dead link |
## Pending
- Task 5 live 目视与正文抽查:`live 人工验证(10-44):待最终人工审阅`。本轮未写「用户人工验证:通过」。
## Next Phase Readiness
- 10-45 可以直接使用本批建立的响应式、事件与 hidden 口径。
- 第 13 篇建页后需回填第 9 篇的纯文本前瞻引用。
@@ -0,0 +1,277 @@
---
phase: 10-docs-restructure
plan: 45
type: execute
wave: 3
depends_on:
- 10-44
files_modified:
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- docs/.vitepress/config.ts
- docs/advanced/ii/ui/reactivity.md
- docs/advanced/ii/ui/props.md
- docs/advanced/ii/ui/component-tsx.md
- docs/advanced/ii/ui/component-ts.md
- docs/advanced/ii/ui/slots-and-attrs.md
- docs/.vitepress/components/demos/ui/props-demo.tsx
- docs/.vitepress/components/demos/ui/component-demo.tsx
- docs/.vitepress/components/demos/ui/ts-component-demo.tsx
- docs/.vitepress/components/demos/ui/slots-demo.tsx
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 62000
raw_tokens: 38000
tasks: 5
confidence: low
must_haves:
truths:
- "Part 3 四篇(props、组件 TSX、组件 TS 元素层、slots 与 attrs)落地,每篇单 `#` H1、按 D-84 组织、末尾 `## 边界与注意`、CRLF"
- "props 篇讲清 `defineComponent<Props>` + `SetupComponentOptions` 的 `props` 数组、属性名 camelCase、默认值用 `props.x ?? 默认`、props 是响应式且不要解构、`emits` 与 `v-model:xxx` 的关系"
- "组件(TSX)篇给出完整组件结构、`setup` 返回 render 函数、`onMounted` / `onUnmounted`、`emit` / `expose`,并明确区分「组件」与「UI」:只有声明 `controller` / `instance` / `state` 且 Props 继承 `IGameUIPropsBase, DefaultProps` 的组件才能被 `GameUI` 打开"
- "组件(TS 元素层)篇只讲元素层类:继承容器或渲染元素、实现渲染方法、`appendChild`、`update`、离屏画布复用;明确元素层类不是 UI、不能直接交给 `GameUI`;不出现标签注册、`createElement` 与渲染器类名"
- "slots 与 attrs 篇讲清 TSX 里 slot 是函数、默认 / 具名 / 作用域 slot 的写法、`attrs` 透传与 `inheritAttrs`,并给出「什么时候用 slot、什么时候用 props」的判定"
- "4 个 live demo(props / component / ts-component / slots)默认导出、只 import vue 与元素标签、无 DOM 属性;页面用 `&lt;ClientOnly&gt;` + `() =&gt; import('...')`"
- "侧边栏新增「组件化」分组 4 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link"
- "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning"
- "未改 `packages/` / `packages-user/` / `src/`、未改 10-43 / 10-44 已验收的 12 篇正文与 10 个 demo 的语义(第 9 篇 `reactivity.md` 只回填一处跨页链接,不改文字语义)、未改 `10-01`..`10-44` 计划、未改既有 JSDoc/注释;不 commit"
artifacts:
- "docs/advanced/ii/ui/props.md、component-tsx.md、component-ts.md、slots-and-attrs.md"
- "docs/.vitepress/components/demos/ui/props-demo.tsx、component-demo.tsx、ts-component-demo.tsx、slots-demo.tsx"
- "docs/.vitepress/config.ts(高级 II 子分组内新增「组件化」分组 4 条)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-45 命名确认、门禁与人工验证记录)"
key_links:
- "第 13 篇的 props 写法是第 14 / 16 篇的前置:组件示例收 props、slot 组件接收 attrs,都回到同一套 `SetupComponentOptions` 声明"
- "第 14 篇的「组件 vs UI」判定必须与第 1 篇的模板一致:`IGameUIPropsBase` + `DefaultProps` + 三个 props 名,缺一不可;两篇口径不一致会让读者在 §1 与 §14 之间摇摆"
- "第 15 篇的元素层类与第 2 篇的元素层写法是同一层:`appendChild` 挂载、setter 改属性;区别只在于「类」封装了创建逻辑,不能把类当 UI 打开"
- "第 16 篇的 `attrs` 透传与第 17 篇内置组件(`Input` / `Textbox` 都用属性透传)呼应;本篇只讲机制,不提前展开内置组件"
---
<scope_justification>
本计划 5 个任务、11 个 `files_modified`,略超「2–3 任务 / ≤ 8 文件」默认上限:
- 四篇正文分两个写作任务(2 + 2),各带 2 个 demo 与侧边栏登记;门禁与人工验证各自独立。合并会得到「4 篇 + 4 demo + 侧边栏 + 全量门禁」的不可验证大块。
- 11 个文件里 4 篇正文、4 个 demo、1 篇**只回填链接**的 10-44 已验收页面(第 9 篇 `reactivity.md`——10-43 约定目标页不存在时只写纯文本,由本批创建第 13 篇后回填 markdown 链接)、1 个侧边栏、1 个记录文件,共享同一份哈希基线与同一套规则。
- 本批内容量小于前两批(无按键表、无性能表),但两篇「组件」是概念分水岭(Vue 组件 vs 元素层类),必须留出足够篇幅,不能压缩成接口清单(D-88)。
不删内容:四篇正文、4 个 live、组件 vs UI 判定、slots / attrs 判定、六类门禁、用户目视全部保留。
</scope_justification>
<objective>
落地 Part 3 组件化四篇:props、组件(TSX)、组件(TS 元素层)、slots 与 attrs。这一批把读者从「一个文件写完一个面板」推到「会拆组件、会传参、会开槽、会透传属性」,并明确划出「Vue 组件」与「元素层类」的界线。
Purpose: 后面的内置组件与完整示例都要复用组件化能力;如果读者在这里分不清组件与 UI、组件与元素层类,后面每一篇都会重新解释一次。
Output: 4 篇正文、4 个 `.tsx` live demo、侧边栏「组件化」分组、NOTES 追加记录。**不改源码、不改前两批已验收内容、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md
@.planning/phases/10-docs-restructure/10-44-PLAN.md
@docs/.vitepress/config.ts
@docs/advanced/ii/ui/ui-template.md
@docs/advanced/ii/ui/ui-template-ts.md
@docs/advanced/ii/ui/conditional-and-list-rendering.md
@docs/.vitepress/components/demos/ui/template-demo.tsx
**流程约定:**
- 只新增 / 修改本计划 `files_modified` 内文件;不改 `10-01`..`10-44` 计划;不重规划其它批次。
- **Task 0 是硬关卡**:汇报本计划 4 篇写什么、4 个 demo 名、组件 vs UI 与组件 vs 元素层类两条界线怎么讲,等用户明确回复「可以执行」。
- 4 篇文件名与侧边栏名已在 10-43 命名总表确认;Task 0 复述确认值,若用户本轮改名则先更新 NOTES 再落盘。
- 改文件前声明「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit。
**本批写作硬规则(与 10-43 / 10-44 一致):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。
**参考文件与哈希:** 以 NOTES 的「参考清单哈希基线」为准;本计划涉及 `packages/render-vue/src/types.ts`(`DefaultProps` / `SetupComponentOptions`)、`render-vue/src/props.ts`、`render/src/core/item.ts`、`render/src/core/container.ts`、`render/src/core/custom.ts`、`render/src/core/canvas2d.ts`、`client-base/src/types.ts`、`client-base/src/components/input.tsx` 与 `textbox.tsx`(只看 `attrs` 透传形态)。写作前逐条 `git hash-object` 比对;不一致或工作树被改即停下问用户。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报组件化四篇的边界讲法,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 13–16 篇;Vue / TSX Integration 全节)、docs/advanced/ii/ui/ui-template.md 与 ui-template-ts.md(已落地口径)、docs/.vitepress/config.ts</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——落地四篇:props、组件(TSX)、组件(TS 元素层)、slots 与 attrs;配 4 个 `.tsx` live。
**为什么**——读者到这一批必须会拆组件。这里有两个最容易混淆的界线:①「组件」不等于「UI」(UI 必须能拿到 `controller` / `instance` / `state` 且 Props 继承 `IGameUIPropsBase, DefaultProps`);②「Vue 组件」不等于「元素层类」(后者不是 UI,不能直接交给 `GameUI`)。这两条界线如果讲不清,后面的内置组件与完整示例就要反复解释。
**大致怎么做**——Task 1 写 props 篇与组件(TSX)篇 + `props-demo` / `component-demo`;Task 2 写组件(TS 元素层)篇与 slots / attrs 篇 + `ts-component-demo` / `slots-demo`;Task 3 跑六类门禁并写 NOTES;Task 4 由用户目视 4 个 live 并抽查正文。
**影响范围**——新增 `docs/advanced/ii/ui/` 下 4 个 `.md` 与 `demos/ui/` 下 4 个 `.tsx`;追加侧边栏「组件化」4 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、前两批已验收的 12 篇与 10 个 demo、ROADMAP / STATE。
**请用户确认:**
1. 四篇文件名与侧边栏名沿用 10-43 命名总表(`props.md` / `component-tsx.md` / `component-ts.md` / `slots-and-attrs.md`)。
2. 第 14 篇的示例组件用「带选中态的道具格子」还是「进度条」;推荐前者,因为第 23 篇的完整示例会复用同一个组件概念。
3. 「组件 vs UI」与「组件 vs 元素层类」两条界线是否都单独设小节(推荐都设,各控制在半页内)。
**参考文件:`packages/render-vue/src/types.ts`(`DefaultProps` / `SetupComponentOptions`)、`render-vue/src/props.ts`、`render/src/core/item.ts`、`render/src/core/container.ts`、`render/src/core/custom.ts`、`render/src/core/canvas2d.ts`、`client-base/src/types.ts`、`client-base/src/components/input.tsx` 与 `textbox.tsx`(只看 `attrs` 透传形态);策略:写作前逐条 `git hash-object -- <path>` 与 NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。</action>
<what-built>尚无产物;本任务只汇报四篇范围、示例选型与两条界线的讲法。</what-built>
<how-to-verify>确认:①是否同意四篇范围与 4 个 live;②第 14 篇示例组件选道具格子还是进度条;③两条界线是否各设一小节;④四篇命名是否沿用确认值。</how-to-verify>
<resume-signal>回复「可以执行」以继续(请同时给示例选型);其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且示例选型、两条界线是否分节、四篇命名三项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,示例组件选型与两条界线的分节方式已确定。</human-check>
</verify>
<done>用户回复「可以执行」且待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: props / 组件(TSX)两篇 + 两个 demo + 侧边栏「组件化」</name>
<files>docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/component-tsx.md, docs/.vitepress/components/demos/ui/props-demo.tsx, docs/.vitepress/components/demos/ui/component-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/reactivity.md</files>
<precondition>本计划的 Task 0 已记录 `用户确认(10-45):可以执行`;10-44 已验收且构建 green。本任务负责把该确认与用户原文追加进 NOTES。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 13、14 篇;Vue / TSX Integration 全节)、packages/render-vue/src/types.ts(`DefaultProps` / `SetupComponentOptions`)、packages/render-vue/src/props.ts:24-81、packages-user/client-base/src/types.ts:16-55、docs/advanced/ii/ui/ui-template.md(模板与 Props 基类口径)、dev.md:54、97-98</read_first>
<action>先向 NOTES 末尾追加 `## 10-45 命名确认`:独占一行 `用户确认(10-45):可以执行`、下一行 `用户原文:`、四篇与四个 demo 最终名、第 14 篇示例选型;再重跑本任务参考文件的哈希比对并追加结果。然后写两篇正文与两个 demo。
**(1)`props.md`(第 13 篇)**:先回答「组件怎么拿参数」。讲 `interface ItemCellProps extends DefaultProps`(普通组件不必继承 UI 基类),`const itemCellProps = { props: ['item', 'selected'] } satisfies SetupComponentOptions<ItemCellProps>`,以及为什么 `props` 数组必须把用到的键写全(没写就收不到)。讲:
- 属性名 camelCase(写错不报错也拿不到)。
- 默认值写法:`const size = props.size ?? 16`,并说明不使用其它默认值语法。
- props 是响应式对象:在 render 函数里读 `props.x` 会跟随更新;**不要解构**(解构会丢响应式),需要局部变量就在 render 函数里取。
- `emits`:声明后 `emit('select', item.id)`;`update:xxx` 只作为 `v-model:xxx` 的实现出现,演示父组件用 `v-model:selected` 绑定,**不教手动监听对应事件属性**。
- 一小节「props 与 `hidden` / 三元」:控制显示用 prop 传 `hidden`,不要用 prop 传「渲染什么组件」。
示例用 `ItemCell` + 父组件传三份不同 props。`## 边界与注意`:漏写 prop 名等于没传;解构丢响应式;默认值不要写成改写 props;子组件不要直接改 props。
**(2)`component-tsx.md`(第 14 篇)**:先讲一个 TSX 组件的完整结构(import → Props 接口 → `SetupComponentOptions` → `defineComponent` → render 函数 → 导出),用第 0 步选定的组件写完整实现(props + `computed` + `return () => (...)`)。然后讲生命周期:`onMounted` 做什么(需要实例的操作)、`onUnmounted` 做什么(清理)。讲 `emit` 与 `expose`:父组件怎么拿子组件方法(`ref` + `expose`),并给一小段示例。最后单设小节**「组件与 UI 的区别」**:UI 是「能被 `GameUI` 打开、由 UI 栈管理的组件」,因此它必须声明 `controller` / `instance` / `state`,且 Props `extends IGameUIPropsBase, DefaultProps`;普通组件没有这些,只负责画面的一部分。给一张两列对照表。`## 边界与注意`:组件不声明三个 props 就不是 UI,不能直接 `new GameUI` 打开;`defineComponent` 的第二个参数是 `SetupComponentOptions`;生命周期钩子必须在 `setup` 同步调用;`expose` 只暴露必要方法。
**(3)两个 demo**:`props-demo.tsx`(`PropsDemo`)父组件传不同 props 给 `ItemCell`,点击回调改选中态;`component-demo.tsx`(`ComponentDemo`)展示第 14 篇的完整组件 + 一个通过 `ref` 调用 `expose` 方法的按钮。都默认导出、只 import vue 与元素标签、无 DOM 属性;一个文件内可定义多个局部组件(ESLint 的 `vue/one-component-per-file` 只针对 `.vue`,`.tsx` 不受该规则约束)。
**(4)侧边栏**:在子分组 `items` 追加 `{ text: '组件化', collapsed: false, items: [...] }`,先放 `/advanced/ii/ui/props` 与 `/advanced/ii/ui/component-tsx` 两条。只做加法。
**(5)回填第 9 篇的跨页链接**:`docs/advanced/ii/ui/reactivity.md` 最后一小节现在写的是纯文本「第 13 篇『组件与 props』」(10-44 的约定:目标页不存在时只写纯文本)。本任务已创建第 13 篇,把该纯文本改成 `[第 13 篇「组件与 props」](./props.md)`。**只改这一处链接,不改任何文字语义、不动该页其它内容。**
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-45):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-45' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/props.md":["SetupComponentOptions","props:","camelCase","??","emits","v-model:","解构"],"docs/advanced/ii/ui/component-tsx.md":["defineComponent","SetupComponentOptions","onMounted","onUnmounted","emit","expose","IGameUIPropsBase","DefaultProps","controller","instance","state"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["props-demo.tsx","component-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/props","/advanced/ii/ui/component-tsx","/advanced/ii/ui/conditional-and-list-rendering","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});const p9=rd("docs/advanced/ii/ui/reactivity.md");if(p9.indexOf("](./props.md)")<0)bad.push("BACKFILL-P9");if(cfg.indexOf("组件化")<0)bad.push("CFG-NO-PART3");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-45", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "BACKFILL-P9", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 追加 10-45 命名确认(确认标记 + 用户原文 + 示例选型)与哈希比对;props 篇含 `SetupComponentOptions` / `props` 数组 / camelCase / `??` 默认值 / `emits` / `v-model:` / 解构警告;组件 TSX 篇含 `defineComponent` / 生命周期 / `emit` / `expose` 与「组件 vs UI」对照表(`IGameUIPropsBase` / `DefaultProps` / 三个 props 名);两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出、无 DOM 属性、不 import 任何引擎包;第 9 篇(`reactivity.md`)里对第 13 篇的纯文本引用已回填为 `./props.md` 链接且该页其它内容未变;侧边栏新增「组件化」两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>props 篇与组件 TSX 篇完成,「组件 vs UI」界线立起。</done>
</task>
<task type="auto">
<name>Task 2: 组件(TS 元素层)/ slots 与 attrs 两篇 + 两个 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/component-ts.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/.vitepress/components/demos/ui/ts-component-demo.tsx, docs/.vitepress/components/demos/ui/slots-demo.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-45):可以执行`;Task 1 两篇与「组件化」分组已存在且构建 green。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 15、16 篇;Render Elements;Vue / TSX Integration)、packages/render/src/core/container.ts(容器与绘制流程)、packages/render/src/core/item.ts:196-244(渲染入口与 `update`)、packages/render/src/core/custom.ts:6-59(`CustomRenderItem` / `bindings`)、packages/render/src/core/canvas2d.ts:25-30(离屏画布复用建议)、packages-user/client-base/src/components/input.tsx:261-270(`attrs` 透传形态)、packages-user/client-base/src/components/textbox.tsx:539-548</read_first>
<action>写两篇正文与两个 demo。
**(1)`component-ts.md`(第 15 篇)**:先讲清这一篇讲的是**元素层**,不是 UI:用类把「怎么画」封装起来,再用 `appendChild` 挂到画布容器上。内容:
- 最小自定义容器类:先 `interface IBadge { /* 本类对外暴露的成员,带 jsDoc */ }`,再 `class Badge extends Container implements IBadge`(`dev.md` 要求所有类先声明 `interface` 再由类 `implements`,不得出现没有 `implements` 的类);在类里组织子元素或在渲染入口里绘制;给完整片段(含 `interface`、`class`、import 与导出)。
- 元素层类的常用扩展点:绘制入口、`update()`(告诉父级自己脏了)、`appendChild`(组合子元素)、离屏画布复用(需要缓存时用 `requireCanvas` 申请、用 `deleteCanvas` 归还,而不是每次渲染都新建画布)。
- 在 UI 组件里使用:`ref` 拿容器 → `onMounted` 里 `host.value!.appendChild(new Badge())`(与第 2 篇同一套写法)。
- 什么时候值得写元素层类:同一套绘制要被多处以命令式方式复用、或者需要精细控制绘制与命中;普通界面结构用 TSX 组件即可。
- 单设小节**「组件 vs 元素层类」**:Vue 组件参与响应式与 UI 栈,元素层类不参与;元素层类不能被 `GameUI` 打开;两者可以组合(Vue 组件里挂元素层类)。
`## 边界与注意`:元素层类不是 UI;不要在这里注册自定义标签(那属于渲染器内部);忘了 `update()` 会导致画面不刷新;离屏画布不要每次渲染都新建。
**(2)`slots-and-attrs.md`(第 16 篇)**:先讲 slot 解决什么问题(父组件决定子组件里面放什么)。内容:
- 默认 slot:子组件里调用 `slots.default?.()`;父组件在标签之间写内容。
- 具名 slot:`slots.title?.(...)`,父组件用具名写法传入;说明 TSX 里 slot 是函数,不是标签。
- 作用域 slot:子组件把数据传给 slot 函数,父组件拿到参数再渲染。
- `attrs`:没被 `props` 声明、也没被 `emits` 消费的属性会进 `attrs`;用 `{...attrs}` 透传到底层元素或内置组件;讲 `inheritAttrs: false` 什么时候需要。提「第 17 篇的内置组件也用属性透传」时**只写纯文本**,不要写 `./builtin-text-and-input.md` 链接——该页在 10-46 创建,届时由 10-46 回填。
- 判定表:什么时候用 slot(结构由调用方决定)、什么时候用 props(数据与开关由调用方决定)、什么时候用 attrs(纯透传)。
示例写一个带标题 slot 与默认 slot 的面板,再加一个把 `fillStyle` / `font` 透传给文字元素的包装组件(证明属性名仍要 camelCase)。正文代码块可以同时给 `fillStyle` 与 `font`,其中 `font` 写成 `new Font('Verdana', 16, 'px', 400)`(**位置参数**;`Font` 构造签名是 `(family, size, sizeUnit, weight, italic)`,不存在对象参数形式);**live 里只透传 `fillStyle`**——`font` 需要 `Font` 实例,live 不为此引入引擎 import(见下条 demo 约束)。`## 边界与注意`:TSX 里 slot 是函数,忘记 `?.()` 什么都不显示;`attrs` 透传不会做 camelCase 转换,属性名照原样;`inheritAttrs: false` 只影响自动落到根元素,不阻止手动透传;slot 内容变化不会重置子组件状态。
**(3)两个 demo**:`ts-component-demo.tsx`(`TsComponentDemo`)用 TSX 等价展示第 15 篇的元素层类画面(类本身只出现在正文代码块);`slots-demo.tsx`(`SlotsDemo`)展示带标题 slot 与默认 slot 的面板 + 一个 attrs 透传包装组件(**只透传 `fillStyle`**)。都默认导出、无 DOM 属性,且**只** import vue 与元素标签——`slots-demo` 不 import 任何 `@motajs/*` / `@user/*`(`font` 的透传只留在正文代码块)。
**(4)侧边栏**:在「组件化」分组追加 `/advanced/ii/ui/component-ts` 与 `/advanced/ii/ui/slots-and-attrs` 两条。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-45):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-45' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/component-ts.md":["interface IBadge","implements IBadge","extends Container","appendChild","update(","onMounted","GameUI","requireCanvas","deleteCanvas"],"docs/advanced/ii/ui/slots-and-attrs.md":["slots.default","slots.title","attrs","inheritAttrs","camelCase"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const ts=fs.existsSync("docs/advanced/ii/ui/component-ts.md")?rd("docs/advanced/ii/ui/component-ts.md"):"";if(ts.indexOf("元素层")<0)bad.push("TS-NO-LAYER-WORD");if(ts.indexOf("不是 UI")<0&&ts.indexOf("不能直接")<0)bad.push("TS-NO-UI-BOUNDARY");const sa=rd("docs/advanced/ii/ui/slots-and-attrs.md");if(sa.indexOf("](./builtin-text-and-input.md)")>=0)bad.push("SA-FORWARD-LINK");["ts-component-demo.tsx","slots-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/component-ts","/advanced/ii/ui/slots-and-attrs","/advanced/ii/ui/props","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-45", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "TS-NO-", "SA-FORWARD-LINK", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>元素层篇含 `interface IBadge` + `implements IBadge` + `extends Container` / `appendChild` / `update(` / 离屏画布复用 / 「元素层不是 UI、不能直接被 `GameUI` 打开」的界线,且不出现标签注册与渲染器类名;slots 篇含 `slots.default` / `slots.title` / `attrs` / `inheritAttrs` / camelCase 提醒与判定表;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出、无 DOM 属性且不 import 任何引擎包(`slots-demo` 只透传 `fillStyle`,`font` 只在正文代码块);第 16 篇对第 17 篇只写纯文本前瞻引用(不含 `./builtin-text-and-input.md` 链接,由 10-46 回填);侧边栏补两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>元素层组件篇与 slots / attrs 篇完成,Part 3 四篇齐备。</done>
</task>
<task type="auto">
<name>Task 3: 六类门禁收口 + NOTES 记录</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1..2 的 4 篇与 4 个 demo 已落盘、侧边栏 4 条齐全、构建 green。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/(本批 4 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts</read_first>
<action>按固定顺序跑门禁并记录:
1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。
2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning;布尔 JSX 属性用简写。
3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:`docs/` 路径 0 报错;引擎既有报错记条数与摘要。
4. 静态断言:4 篇单 H1 / `## 边界与注意` / 无被禁写法 / 全部接 live 且 `<ClientOnly>` + 动态 loader / 4 个 demo 默认导出且只 import vue / 侧边栏 16 条(本批 4 + 前三批 12)都在 / 既有条目与高级 III 未丢。
5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。
6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-45 门禁`:六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、本批 4 篇与 4 个 demo 清单。
7. 交叉一致性:第 13 篇的 props 声明与第 14 篇的组件实现使用同一套写法;第 1 篇与第 14 篇的「UI 判定」三要素(`IGameUIPropsBase` / `DefaultProps` / 三个 props 名)表述一致。把核对结论写进该小节。
本任务不改正文语义。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-45):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-45' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const md=["props","component-tsx","component-ts","slots-and-attrs"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m)});["props-demo","component-demo","ts-component-demo","slots-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m)});const cfg=rd("docs/.vitepress/config.ts");const links=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering","props","component-tsx","component-ts","slots-and-attrs"];links.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");const u1=rd("docs/advanced/ii/ui/ui-template.md");const c14=rd("docs/advanced/ii/ui/component-tsx.md");["IGameUIPropsBase","DefaultProps"].forEach(function(k){if(u1.indexOf(k)<0||c14.indexOf(k)<0)bad.push("CONSIST:"+k)});if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-45 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-45", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "CONSIST:", "NOTES-NO-"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径类型报错 0;静态断言全绿(4 篇单 H1 / 边界节 / 无被禁写法 / 全部接 live / 4 个 demo 合规 / 侧边栏 16 条齐全 / 第 1 与第 14 篇 UI 判定口径一致);构建 green、无 dead link;NOTES 有 `### 10-45 门禁` 且含类型检查与引擎报错摘要。</acceptance_criteria>
<done>Part 3 四篇 4 demo 通过六类门禁并已记录。</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 4: 用户目视 4 个 live 并抽查四篇正文</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 通过(六类门禁全绿、构建产物已生成、NOTES 已记录)。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录)、docs/advanced/ii/ui/(本批 4 篇)、docs/.vitepress/components/demos/ui/(本批 4 个 demo)</read_first>
<action>请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 4 篇,逐条确认:①侧边栏「组件化」4 条可点开;②props 篇 live 的三个格子显示不同 props,点击回调生效;③组件 TSX 篇 live 的组件正常显示,`expose` 按钮能触发子组件方法;④元素层篇 live 与正文的类片段画面一致;⑤slots 篇 live 的标题 slot 与默认 slot 都渲染出来,attrs 透传的文字样式生效;⑥抽查第 13 / 14 篇:props 声明与组件实现是同一套写法,UI 判定三要素与第 1 篇一致;⑦抽查第 15 篇:明确写了「元素层不是 UI」,且没有出现标签注册与渲染器类名。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-45):通过` + 下一行 `用户原文:`;发现问题逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 3 后复验。只有用户明确通过才可进入 10-46。</action>
<what-built>4 篇正文与 4 个 live demo,构建产物可在本地预览。</what-built>
<how-to-verify>按上面①–⑦逐条检查;重点看 props 与组件两篇的写法是否一致、两条界线是否讲清、slot 是否真的渲染。</how-to-verify>
<resume-signal>若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。</resume-signal>
<acceptance_criteria>用户明确回复 live 与正文均通过,且 NOTES 有人工验证标记与用户原文;否则问题清单已记录并进入修复循环。</acceptance_criteria>
<verify>
<human-check>用户已明确确认 4 篇可读、4 个 live 正常、两条界线清楚,并已把结论记入 NOTES。</human-check>
</verify>
<done>用户人工验证结论已记录。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 构建期(SSR)→ live demo | demo 由 `RenderDemo` 在浏览器端动态 import;页面只静态 import 包装组件 |
| demo → 元素层类 | 文档正文展示类,demo 用 TSX 等价画面;不在 live 里动态注册标签 |
| 侧边栏 → 页面 | 每条 link 必须对应已存在页面,否则构建 dead link 失败 |
| 文档 → 读者 | 组件 / UI / 元素层类三条概念边界若写混,读者会写出无法打开的 UI |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-138 | Denial of Service(构建不可用) | `.tsx` demo | high | mitigate | demo 由 loader 动态 import、`<ClientOnly>` 包裹;构建门禁必须 `build complete` |
| T-10-139 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页同任务;静态断言复核 16 条链接与既有条目、高级 III 未丢 |
| T-10-140 | Information Disclosure | 元素层篇误写渲染器内部 | low | mitigate | 静态断言禁渲染器类名 / 标签注册 / core 命名空间;正文只写类 + `appendChild` |
| T-10-141 | Repudiation | 命名与门禁无据可查 | medium | mitigate | NOTES 追加式记录;每个 auto 任务复检 `用户确认(10-45):可以执行` |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 确认门禁:NOTES 含 `用户确认(10-45):可以执行` + `用户原文:`;Task 4 后含 `用户人工验证(10-45):通过` + `用户原文:`,无 `状态:待处理`。
- 内容门禁:4 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性。
- 概念门禁:第 1 与第 14 篇的 UI 判定三要素一致;第 15 篇明确「元素层不是 UI」。
- 示例门禁:4 篇全部接 live(`<ClientOnly>` + 动态 loader);4 个 demo 默认导出、只 import vue、无 DOM 属性。
- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。
- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改前两批已验收内容;未改 `10-01`..`10-44` 计划;未 commit;ROADMAP / STATE 本计划不改。
</verification>
<success_criteria>
- 读者能把面板拆成组件,会传 props、开 slot、透传属性,并分得清组件 / UI / 元素层类。
- 4 篇正文与 4 个 live 可用;第 1 与第 14 篇的 UI 判定口径一致。
- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。
</success_criteria>
<output>
Create `.planning/phases/10-docs-restructure/10-45-SUMMARY.md` when done
</output>
@@ -0,0 +1,327 @@
---
phase: 10-docs-restructure
plan: 46
type: execute
wave: 4
depends_on:
- 10-45
files_modified:
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- docs/.vitepress/config.ts
- docs/advanced/ii/ui/slots-and-attrs.md
- docs/advanced/ii/ui/text.md
- docs/advanced/ii/ui/builtin-text-and-input.md
- docs/advanced/ii/ui/builtin-list-and-containers.md
- docs/advanced/ii/ui/ui-controller-and-stack.md
- docs/advanced/ii/ui/replace-builtin-ui.md
- docs/advanced/ii/ui/ui-performance.md
- docs/.vitepress/components/demos/ui/builtin-text-demo.tsx
- docs/.vitepress/components/demos/ui/builtin-list-demo.tsx
- docs/.vitepress/components/demos/ui/controller-demo.tsx
- docs/.vitepress/components/demos/ui/strategy-demo.tsx
- docs/.vitepress/components/demos/ui/perf-demo.tsx
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 72000
raw_tokens: 45000
tasks: 6
confidence: low
must_haves:
truths:
- "Part 4 五篇(内置组件文本与输入、内置组件列表与容器、UIController 与 UI 栈、修改/替换内置 UI、UI 系统性能与注意事项)落地,每篇单 `#` H1、按 D-84 组织、末尾 `## 边界与注意`、CRLF"
- "内置组件篇只写公开契约(props / emits / expose):`TextContent` 的 `width` 必填与 `autoHeight`、`Textbox` 的标题与内边距、`Input` 用 `v-model:value`、`List` 用 `v-model:selected`、`Page` / `Scroll` / `Selection` 的对外用法;`Choices` 必须写,只按接口讲"
- "特殊组件 `InputBox` / `ConfirmBox` / `Choices` 按「单次调用型」讲:通过 UI 栈打开或调用封装函数、结果用 Promise 或事件拿到;不引用实现细节;`Choices` 正文标题保留 `Choices`,并说明「用户习惯叫 `ChoicesBox`,**源码导出名是 `Choices` / `ChoicesUI`**」——不得写成按 `ChoicesBox` 就能 import"
- "UIController 篇讲清四层模型(声明 / 控制 / 实例 / 显示)、栈与背景、`active` / `showBack`、`open` / `close` / `closeAll` / `hide` / `show`、`lastOnly` / `showAll` / `showCustom`、`keep` 防闪烁、场景 UI 与主 UI 的区别;并明确当前没有全局 UI 注册 / 覆盖入口"
- "替换内置 UI 篇先把「内置 UI」定义为 `src/client/ui` 里的 UI,再讲三种改法(打开处替换 / 包装组件 / 显示策略与背景),不教读者改 `packages`,也不引用不存在的全局注册接口"
- "UI 性能篇覆盖缓存与脏更新、HD / 抗锯齿、`hidden` 优先与三元取舍、列表 `key`、组件粒度、`Scroll` / `Page`、`keep` / `setBackground`、`createPropsBase` 每次渲染都会调用;明确本篇是 UI 系统性能,引擎级性能属于高级 III"
- "5 个 live demo(builtin-text / builtin-list / controller / strategy / perf)默认导出、无 DOM 属性;可以 import vue、元素标签、内置组件(内置组件只在 demo 内静态 import),或用 `@motajs/system` 构造最小控制器(`controller-demo` / `strategy-demo` / `perf-demo`),除此之外不得 import 其它 `@motajs/*` / `@user/*`;页面用 `&lt;ClientOnly&gt;` + `() =&gt; import('...')`"
- "侧边栏新增「内置组件与 UI 系统」分组 5 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link"
- "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning"
- "未改 `packages/` / `packages-user/` / `src/`、未改前三批已验收的 16 篇正文与 14 个 demo 的语义(第 6 / 16 篇各只回填一处跨页链接,不改文字语义)、未改 `10-01`..`10-45` 计划、未改既有 JSDoc/注释;不 commit;不引用 `src/client/ui/choices.tsx` 的实现细节(只按接口)"
artifacts:
- "docs/advanced/ii/ui/builtin-text-and-input.md、builtin-list-and-containers.md、ui-controller-and-stack.md、replace-builtin-ui.md、ui-performance.md"
- "docs/.vitepress/components/demos/ui/builtin-text-demo.tsx、builtin-list-demo.tsx、controller-demo.tsx、strategy-demo.tsx、perf-demo.tsx"
- "docs/.vitepress/config.ts(高级 II 子分组内新增「内置组件与 UI 系统」分组 5 条)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-46 命名确认、门禁与人工验证记录)"
key_links:
- "第 17 / 18 篇的内置组件契约必须与第 16 篇的 `attrs` 透传呼应:内置组件用属性透传接收样式,属性名仍 camelCase"
- "第 19 篇的 UI 栈是第 1 篇「打开 / 关闭」的系统化:第 1 篇给最小入口,本篇给栈、背景、显示策略与 `keep`;两处对 `controller` / `instance` 的用法必须一致"
- "第 20 篇的三种改法都落在「打开处」与「包装组件」,不依赖全局注册表;这与第 19 篇「没有全局覆盖入口」的结论一致,两篇不能互相矛盾"
- "第 21 篇的 `hidden` 口径必须与第 8、12 篇逐字同义;性能建议只做汇总与指向,不重新定义概念"
---
<scope_justification>
本计划 6 个任务、14 个 `files_modified`,超出默认上限,保持单计划:
- 五篇正文分三个写作任务(2 + 2 + 1),每篇都带 live;门禁与人工验证独立。第 21 篇单独成任务,是因为它要汇总前四批的所有性能结论并做交叉核对,不适合与其它篇混在一起写。
- 14 个文件里 5 篇正文、5 个 demo、2 篇**只回填链接**的更早已验收页面(第 6 篇 `text.md`、第 16 篇 `slots-and-attrs.md`——它们对第 17 篇只写了纯文本前瞻引用,由本批创建第 17 篇后回填 markdown 链接)、1 个侧边栏、1 个记录文件,共享同一份哈希基线与同一套规则。
- 内置组件篇的契约信息量大(`TextContent` / `Textbox` / `Input` / `List` / `ListPage` / `Page` / `Scroll` / `Selection` / `Choices`),压缩会让读者拿不到可用参数,违反 D-88。
不删内容:五篇正文、5 个 live、`Choices` 必写、特殊组件三种、UI 栈全接口、三种替换法、性能汇总、六类门禁、用户目视全部保留。
</scope_justification>
<objective>
落地 Part 4:内置组件(文本与输入、列表与容器)、UIController 与 UI 栈、修改 / 替换内置 UI、UI 系统性能与注意事项。这一批把读者从「自己写组件」带到「用现成组件 + 接 UI 栈 + 改内置 UI」,并给出一份可执行的性能清单。
Purpose: 背包面板不可能全部手写;`TextContent` / `Input` / `List` / `Page` / `Scroll` 覆盖了绝大多数界面需求,`UIController` 决定面板怎么叠、怎么关、背景怎么留。性能篇则是整批的唯一汇总口径,第 8 / 12 篇的 `hidden` 结论在这里收口。
Output: 5 篇正文、5 个 `.tsx` live demo、侧边栏「内置组件与 UI 系统」分组、NOTES 追加记录。**不改源码、不改前三批已验收内容、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md
@.planning/phases/10-docs-restructure/10-45-PLAN.md
@docs/.vitepress/config.ts
@docs/advanced/ii/ui/ui-template.md
@docs/advanced/ii/ui/layer-transform-performance.md
@docs/advanced/ii/ui/slots-and-attrs.md
@docs/.vitepress/components/demos/uiSystem.vue
@docs/.vitepress/components/demos/ui/component-demo.tsx
**流程约定:**
- 只新增 / 修改本计划 `files_modified` 内文件;不改 `10-01`..`10-45` 计划;不重规划其它批次。
- **Task 0 是硬关卡**:汇报五篇范围、5 个 demo 名、内置组件篇的契约取舍(哪些展开、哪些只给一行)、第 20 篇的示例力度,等用户明确回复「可以执行」。
- 五篇文件名与侧边栏名已在 10-43 命名总表确认;Task 0 复述确认值,若用户本轮改名先更新 NOTES 再落盘。
- 改文件前声明「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit。
**本批写作硬规则(延续前三批):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。
**参考文件与哈希:** 以 NOTES 的「参考清单哈希基线」为准;本计划涉及 `client-base/src/components/textbox.tsx`、`list.tsx`、`page.tsx`、`scroll.tsx`、`input.tsx`、`misc.tsx`、`system/src/ui/controller.ts`、`ui.ts`、`instance.ts`、`container.tsx`、`types.ts`、`client-modules/src/ui/func.ts`、`client-modules/src/client.ts`、`src/client/ui/inputBox.tsx`。`src/client/ui/choices.tsx` **只读 props / emits / 函数签名**,不引用实现;其工作树哈希与 HEAD 不同(Manifest I 已记录),若工作树哈希再变即停下问用户。其余 dirty 的 `src/client/ui/*` 一律不读。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报内置组件与 UI 系统的契约取舍,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 17–21 篇;Built-in Components;UI System;Performance;Open Questions Q5 / Q6)、docs/advanced/ii/ui/layer-transform-performance.md 与 slots-and-attrs.md(已落地口径)</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——落地五篇:内置组件(文本 / 输入)、内置组件(列表 / 容器)、UIController 与 UI 栈、修改 / 替换内置 UI、UI 系统性能与注意事项;配 5 个 `.tsx` live。
**为什么**——读者到这一步要开始「用现成的」:文本换行、输入框、列表、分页、滚动都不该手写。同时 `UIController` 决定面板怎么叠、怎么关、背景怎么留;性能篇则是整批的唯一汇总口径,第 8 / 12 篇的 `hidden` 结论在这里收口。
**大致怎么做**——Task 1 写文本 / 输入篇与列表 / 容器篇 + `builtin-text-demo` / `builtin-list-demo`;Task 2 写 UIController 篇与替换内置 UI 篇 + `controller-demo` / `strategy-demo`;Task 3 写性能篇 + `perf-demo`;Task 4 跑六类门禁并写 NOTES;Task 5 由用户目视 5 个 live 并抽查正文。
**影响范围**——新增 `docs/advanced/ii/ui/` 下 5 个 `.md` 与 `demos/ui/` 下 5 个 `.tsx`;追加侧边栏「内置组件与 UI 系统」5 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、前三批已验收的 16 篇与 14 个 demo、ROADMAP / STATE。
**请用户确认:**
1. 五篇文件名与侧边栏名沿用 10-43 命名总表。
2. **契约取舍**:内置组件篇给「属性表 + 完整示例」还是「示例为主、只在表里列常用项」;推荐后者(D-88 要求原理讲透、不堆接口表),但 `TextContent` 的 `width` 必填、`autoHeight`、`Input` 的 `v-model:value`、`List` 的 `v-model:selected`、`Scroll` 只对直接子元素生效这几条必须写全。
3. **第 20 篇力度**(研究 Q5):只讲「打开处替换 / 包装组件 / 显示策略与背景」三种改法,还是再加「复制内置 UI 源码再改」的完整示例;推荐只讲三种改法(当前没有全局注册表,复制源码不是推荐路径)。
4. **`Choices` 命名**(研究 Q6):正文标题用 `Choices(选项框)`,并说明「用户习惯叫 `ChoicesBox`,源码导出名是 `Choices` / `ChoicesUI`」;是否接受。
**参考文件:`client-base/src/components/textbox.tsx`、`list.tsx`、`page.tsx`、`scroll.tsx`、`input.tsx`、`misc.tsx`、`system/src/ui/controller.ts`、`ui.ts`、`instance.ts`、`container.tsx`、`types.ts`、`client-modules/src/ui/func.ts`、`client-modules/src/client.ts`、`src/client/ui/inputBox.tsx`(`choices.tsx` 只读 props / emits / 函数签名);策略:写作前逐条 `git hash-object -- <path>` 与 NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。</action>
<what-built>尚无产物;本任务只汇报五篇范围、契约取舍与第 20 / 18 篇的示例力度。</what-built>
<how-to-verify>确认:①是否同意五篇范围与 5 个 live;②内置组件篇用「示例为主 + 常用项表」是否可接受;③第 20 篇只讲三种改法是否可接受;④`Choices` 标题与 `ChoicesBox` 别名的处理是否可接受。</how-to-verify>
<resume-signal>回复「可以执行」以继续(请同时给出契约取舍与第 20 篇力度的选择);其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且契约取舍、第 20 篇力度、`Choices` 命名、五篇命名四项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,并已确定契约写法、第 20 篇力度与 `Choices` 命名。</human-check>
</verify>
<done>用户回复「可以执行」且待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 内置组件(文本/输入)/ 内置组件(列表/容器)两篇 + 两个 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/.vitepress/components/demos/ui/builtin-text-demo.tsx, docs/.vitepress/components/demos/ui/builtin-list-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/slots-and-attrs.md</files>
<precondition>本计划的 Task 0 已记录 `用户确认(10-46):可以执行`;10-45 已验收且构建 green。本任务负责把该确认与用户原文追加进 NOTES。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 17、18 篇;Built-in Components 全节;Open Questions Q6)、packages-user/client-base/src/components/textbox.tsx(`TextContentProps` / 事件 / expose / `TextboxProps`)、input.tsx(`InputProps` / `InputEmits`)、list.tsx(`ListProps` / `ListEmits` / `ListPageProps` / `ListPageSlots`)、page.tsx(`PageProps` / `PageEmits` / `PageExpose`)、scroll.tsx(`ScrollProps` / `ScrollExpose` 与平铺建议)、misc.tsx:280-320(`SelectionProps`)、src/client/ui/inputBox.tsx(`InputBox` 的对外用法与 `getInput` / `getInputNumber` 签名)、src/client/ui/choices.tsx(**只读** `ConfirmBoxProps` / `ChoicesProps` / emits / `getConfirm` / `getChoice` 签名)</read_first>
<action>先向 NOTES 末尾追加 `## 10-46 命名确认`(`用户确认(10-46):可以执行` + 下一行 `用户原文:` + 契约取舍、第 20 篇力度、`Choices` 命名结论),并重跑本任务参考文件的哈希比对追加结果。然后写两篇正文与两个 demo。
**(1)`builtin-text-and-input.md`(第 17 篇)**:按「用现成的」组织。
- `TextContent`:解决长文本换行与打字机。讲 `width` 必填、`autoHeight` 让高度自适应、`fill` / `stroke` 与文字样式配置;事件 `typeEnd` / `typeStart` / `updateHeight`;暴露的 `retype` / `showAll` / `getHeight` 怎么在父组件里用(`ref` + `expose`)。给一个完整示例:一段会逐字显示的说明文字 + 一个「立即显示全部」按钮。
- `Textbox`:在 `TextContent` 上加背景、标题、内边距、图标与皮肤;`icon` / `winskin` 只写成「可填名字」的占位,说明本篇不展开素材来源;讲 `show` / `hide` / `retype` / `showAll` 与「在组件外更新文本」的 `TextboxStore` 用法(一段话 + 一小段代码,不展开内部)。
- `Input`:模板外创建真实输入框对齐画布。讲 `value` 用 `v-model:value`、`multiline`、`placeholder`、边框与圆角、内边距;明确不要手动监听 `update:value` 对应的事件属性。
- 特殊组件 `InputBox`:单次调用型弹窗;讲 `getInput(controller, text, loc, width, props?)` 返回 `Promise<string>`、`getInputNumber` 返回 `Promise<number>`,以及需要自己打开时用 `InputBoxUI` 配 `controller.open`;给一段 `await getInput(...)` 的完整示例。
`## 边界与注意`:`TextContent` 不传 `width` 不能用;`autoHeight` 与固定高度二选一;`Input` 的 `v-model` 要带 `:value`;`InputBox` 依赖 UI 栈,关掉面板前要处理未完成的 Promise。
**(2)`builtin-list-and-containers.md`(第 18 篇)**:
- `List`:`list` 是 `[id, 文本]` 数组;选中用 `v-model:selected`;讲 `lineHeight` / `font` / 颜色与皮肤占位;说明初始选中以列表第一项为准,不要承诺用 `selected` 控制初始值。
- `ListPage`:在 `List` 上加左右分栏、`basis`、`right`、`close` 与关闭按钮位置;用动态 slot 按选中 key 渲染右侧内容,给完整示例骨架。
- `Page`:`pages` / `page` / `hideIfSingle`;事件 `pageChange` 与 `v-model:page`;暴露 `changePage` / `movePage` / `now`;默认 slot 拿到页码索引(从 0 开始)。
- `Scroll`:`hor` / `noscroll` / `padEnd`;暴露 `scrollTo` / `getScrollLength`;**明确只对视口的直接子元素做虚拟滚动**,给出推荐写法(子元素平铺)与不推荐写法(用一个容器包住全部内容),并用一句话说明容器自定义标签只写 `container-custom`。
- `Selection`:不接收事件的视觉光标;`color` / `border` / `alphaRange`;`winskin` 只作占位。
- 特殊组件 `ConfirmBox` 与 `Choices`:`getConfirm` 返回 `Promise<boolean>`;`getChoice` 返回 `Promise<T>`;`Choices` 的 `choices` 是 `[key, text]` 数组、`maxHeight` 超过时分页、`selected` 默认项;正文标题用 `Choices(选项框)`,并写明「用户习惯叫 `ChoicesBox`,**源码导出名是 `Choices` / `ChoicesUI`**」(避免读者按 `ChoicesBox` 去找 import);**只按接口讲,不描述实现**。
`## 边界与注意`:`Scroll` 里包一层容器会让虚拟滚动失效;`List` 的选中不要手动去改列表数据;`Page` 的索引从 0 开始;`Choices` / `ConfirmBox` 是一次性 UI,不要在它们上面再叠自己的面板而不处理返回值。
**(3)两个 demo**:`builtin-text-demo.tsx`(`BuiltinTextDemo`)展示 `TextContent` 打字机 + 「立即显示全部」按钮 + 一个 `Input`(`v-model:value`);`builtin-list-demo.tsx`(`BuiltinListDemo`)展示 `List` 选中 + `Page` 分页 + `Scroll` 平铺列表 + `Selection` 光标。两个 demo 可以静态 import 内置组件(demo 由 loader 动态 import,SSR 安全),但不得写 DOM 属性;若某个内置组件在文档站跑不起来,保留代码块与页面,不删内容,并在正文用一句话说明该示例依赖完整客户端环境。
**(4)侧边栏**:追加 `{ text: '内置组件与 UI 系统', collapsed: false, items: [...] }`,先放 `/advanced/ii/ui/builtin-text-and-input` 与 `/advanced/ii/ui/builtin-list-and-containers`。只做加法。
**(5)回填第 6 篇与第 16 篇的跨页链接**:本任务创建了第 17 篇 `builtin-text-and-input.md`,把两处纯文本前瞻引用改成链接——
- `docs/advanced/ii/ui/text.md`:把纯文本「第 17 篇『内置组件:文本与输入』」改成 `[第 17 篇「内置组件:文本与输入」](./builtin-text-and-input.md)`;
- `docs/advanced/ii/ui/slots-and-attrs.md`:把纯文本「第 17 篇的内置组件」改成 `[第 17 篇「内置组件:文本与输入」](./builtin-text-and-input.md)`。
**只改这两处链接,不改任何文字语义、不动这两页其它内容。**
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/builtin-text-and-input.md":["TextContent","Textbox","Input","InputBox","getInput","getInputNumber","autoHeight","v-model:value","width"],"docs/advanced/ii/ui/builtin-list-and-containers.md":["List","ListPage","Page","Scroll","Selection","Choices","ChoicesBox","ChoicesUI","ConfirmBox","getChoice","getConfirm","v-model:selected","scrollTo"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const l=rd("docs/advanced/ii/ui/builtin-list-and-containers.md");if(l.indexOf("直接子元素")<0)bad.push("LIST-NO-SCROLL-NOTE");if(l.indexOf("container-custom")<0)bad.push("LIST-NO-CONTAINER-NAME");["builtin-text-demo.tsx","builtin-list-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+f);if(/from\s+[\x22\x27]@user\/(?!client-base[\x22\x27])/.test(s))bad.push("DEMO-USER:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/builtin-text-and-input","/advanced/ii/ui/builtin-list-and-containers","/advanced/ii/ui/slots-and-attrs","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});const b6=rd("docs/advanced/ii/ui/text.md");const b16=rd("docs/advanced/ii/ui/slots-and-attrs.md");if(b6.indexOf("](./builtin-text-and-input.md)")<0)bad.push("BACKFILL-P6");if(b16.indexOf("](./builtin-text-and-input.md)")<0)bad.push("BACKFILL-P16");if(cfg.indexOf("内置组件与 UI 系统")<0)bad.push("CFG-NO-PART4");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-46", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "LIST-NO-", "CRLF:", "NO-DEMO", "DEMO-", "BACKFILL-P", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 追加 10-46 命名确认与哈希比对;文本 / 输入篇含 `TextContent` / `Textbox` / `Input` / `InputBox` 与 `getInput` / `getInputNumber` / `autoHeight` / `v-model:value`;列表 / 容器篇含 `List` / `ListPage` / `Page` / `Scroll` / `Selection` / `Choices`(并注明 `ChoicesBox` 是俗称、源码导出名是 `Choices` / `ChoicesUI`)/ `ConfirmBox` / `getChoice` / `getConfirm` / `v-model:selected` / `scrollTo`,并写明 `Scroll` 只对直接子元素生效与 `container-custom` 写法;两篇单 H1、有边界节、CRLF、无被禁写法;两个 demo 默认导出且无 DOM 属性;第 6 篇(`text.md`)与第 16 篇(`slots-and-attrs.md`)里对第 17 篇的纯文本前瞻引用已回填为 `./builtin-text-and-input.md` 链接且这两页其它内容未变;侧边栏新增「内置组件与 UI 系统」两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>内置组件两篇与两个 demo 完成,`Choices` 已按接口写入。</done>
</task>
<task type="auto">
<name>Task 2: UIController 与 UI 栈 / 修改与替换内置 UI 两篇 + 两个 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/.vitepress/components/demos/ui/controller-demo.tsx, docs/.vitepress/components/demos/ui/strategy-demo.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-46):可以执行`;Task 1 两篇与「内置组件与 UI 系统」分组已存在且构建 green。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 19、20 篇;UI System 全节;Open Questions Q5)、packages/system/src/ui/controller.ts(`open` / `close` / `closeAll` / `hide` / `show` / `keep` / `setBackground` / `lastOnly` / `showAll` / `showCustom` / `render`)、ui.ts(`GameUI` 与全局表现状)、instance.ts、container.tsx、types.ts、packages-user/client-modules/src/ui/func.ts、packages-user/client-modules/src/client.ts:101-105、src/client/ui/title.tsx:214、233(场景 UI 打开主场景)、docs/.vitepress/components/demos/uiSystem.vue(POC 的控制器用法)</read_first>
<action>写两篇正文与两个 demo。
**(1)`ui-controller-and-stack.md`(第 19 篇)**:先给系统模型(D-82):四层——声明(把名字和组件绑在一起)、控制(管栈、背景、显示策略)、实例(一次打开产生的 key / 绑定参数 / 隐藏状态)、显示(把背景与栈映射成组件树)。然后:
- 栈:`stack` 是打开顺序;`controller.open(ui, vBind)` 入栈并激活;`controller.close(instance)` 按策略出栈;`controller.closeAll()` 清空或按 UI 清理;`controller.hide(instance)` / `controller.show(instance)` 只改实例可见性、不动栈。
- 显示策略:默认「只显示最后一个」;`lastOnly` / `showAll` / `showCustom` 的差别;**明确在栈模式下关闭某个 UI 会连带关闭它之后打开的 UI**,而 `showAll` 默认不连带。给一张对照表。
- 背景:`setBackground` 放一个始终存在的背景实例;`hideBackground` / `showBackground` / `showingBack`。
- `keep`:关闭当前、打开下一个的间隙保持背景,避免闪烁;给 `const keep = controller.keep(); controller.close(a); controller.open(b, {}); keep.safelyUnload()` 的完整片段,并说明 `safelyUnload` 与 `unload` 的区别。
- 场景 UI 与主 UI:`sceneController`(加载、标题、主场景)与 `mainUIController`(游戏内主 UI 栈)的区别与打开位置;主 UI 栈由主场景的容器负责显示,作者不需要关心渲染位置。
- 基础 props 注入:`setPropsBaseCreator` 决定每个实例能拿到哪些基础参数(`instance` / `controller` / `state`);作者 UI 的 Props 必须 `extends IGameUIPropsBase, DefaultProps`。
- 明确一句:当前没有全局 UI 注册 / 覆盖入口,`GameUI` 的全局表不会被自动填充,因此不要指望按名字取到内置 UI。
`## 边界与注意`:`close` 在栈模式下会连带关闭上层;`alwaysShow` 的背景不会被 `hide` 关掉;`active` / `showBack` 是引用值,在 TSX 里要 `.value`;频繁 `open` / `close` 会重建组件。
**(2)`replace-builtin-ui.md`(第 20 篇)**:先把「内置 UI」定义清楚——指 `src/client/ui` 里的设置、存档、工具栏等**应用层 UI**,不是泛指内置组件。然后按用户 Task 0 的选择讲三种改法(默认只讲三种,不复制源码):
1. 打开处替换:找到调用 `open` 的那一行,换成自己的 UI;给前后对照片段。
2. 包装组件:写一个组件包住原 UI,转发 props / slots / emits,只改需要改的部分;重点讲「保持对外契约不变」,这样调用方不用改。
3. 改显示策略或背景:用 `showAll` / `lastOnly` / `showCustom` 与 `setBackground` 改变叠放与背景,而不是改原组件。
再给一张「改法 / 适用场景 / 代价」表,并明确:不要去改 `packages` / `packages-user` 里的内置实现;当前没有全局替换接口。
`## 边界与注意`:包装组件要转发全部 props,漏一个就会出现「某些设置不生效」;emit 名称必须原样转发;换打开处要同时检查 `keep` 的配对;改显示策略会影响同栈的其它 UI。
**(3)两个 demo**:`controller-demo.tsx`(`ControllerDemo`)自建一个最小 UI 栈:`new UIController()` + `setPropsBaseCreator` + 一个最小 `GameUI` + 打开 / 关闭按钮,并把栈长度与激活状态显示出来;`strategy-demo.tsx`(`StrategyDemo`)并排对比「只显示最后一个」与「显示全部」两种策略的叠放效果。都默认导出;可以在 demo 内静态 import `@motajs/system`(loader 动态 import,SSR 安全);不写 DOM 属性。
**(4)侧边栏**:在「内置组件与 UI 系统」分组追加 `/advanced/ii/ui/ui-controller-and-stack` 与 `/advanced/ii/ui/replace-builtin-ui`。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const need={"docs/advanced/ii/ui/ui-controller-and-stack.md":["open(","close(","closeAll","hide(","show(","lastOnly","showAll","showCustom","setBackground","keep(","safelyUnload","active","showBack","sceneController","mainUIController","setPropsBaseCreator","IGameUIPropsBase"],"docs/advanced/ii/ui/replace-builtin-ui.md":["src/client/ui","open(","showAll","setBackground","包装","props","emits","packages"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const r20=rd("docs/advanced/ii/ui/replace-builtin-ui.md");if(r20.indexOf("没有全局")<0&&r20.indexOf("没有全局替换")<0)bad.push("R20-NO-GLOBAL-NOTE");["controller-demo.tsx","strategy-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+f);if(/from\s+[\x22\x27]@user\/(?!client-base[\x22\x27])/.test(s))bad.push("DEMO-USER:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/ui-controller-and-stack","/advanced/ii/ui/replace-builtin-ui","/advanced/ii/ui/builtin-list-and-containers","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-46", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "R20-", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>UIController 篇含四层模型、栈与背景、`active` / `showBack`、全部 `open` / `close` / 策略 / `keep` 接口、场景 UI 与主 UI 的区别、`setPropsBaseCreator` 与 Props 基类,并明确没有全局注册 / 覆盖入口;替换篇把「内置 UI」定义为 `src/client/ui` 的应用层 UI,讲三种改法且不教改 `packages`;两篇单 H1、有边界节、CRLF、接 live、无被禁写法(含 `GameUI.get`);两个 demo 默认导出且无 DOM 属性;侧边栏补两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>UIController 篇与替换内置 UI 篇完成。</done>
</task>
<task type="auto">
<name>Task 3: UI 系统性能与注意事项 + perf demo + 侧边栏</name>
<files>docs/advanced/ii/ui/ui-performance.md, docs/.vitepress/components/demos/ui/perf-demo.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-46):可以执行`;Task 2 两篇已落盘且构建 green;第 8 / 12 篇的 `hidden` 口径已验收。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 21 篇;Performance 全节;旧性能文档可用结论)、packages/render/src/core/render.ts:182-186(脏更新)、packages/render/src/core/item.ts:229-244(脏标记冒泡)、packages/render-vue/src/tag.ts:103-115(缓存默认值)、packages/system/src/ui/container.tsx:14-47(每次渲染都会调用 creator)、packages/system/src/ui/controller.ts(`keep` / `active` / `showBack`)、docs/advanced/ii/ui/layer-transform-performance.md 与 conditional-and-list-rendering.md(本批要收口的 `hidden` 口径)</read_first>
<action>写性能篇与 demo,并登记侧边栏。
**`ui-performance.md`(第 21 篇)**:开头先划边界——本篇讲 **UI 系统**的性能(缓存、显示开关、组件粒度、栈与背景),引擎级性能(渲染管线、批处理)属于高级 III,给跨页链接。然后按「先省掉不该做的事 → 再减少重绘 → 再减少重建」的顺序组织:
1. **显示开关**:重申 `hidden` 优先——不显示、不交互、保留元素与状态、跳过绘制与命中;三元只在必须真正不存在 / 需要重置状态或生命周期 / 子树很重且长期不用 / 必须彻底摘掉事件监听或不能接受隐藏元素继续占内存时用(与第 8、12 篇逐字同义)。给一张判定表。
2. **缓存**:哪些标签默认缓存、哪些默认不缓存;`nocache` 优先于 `cache`;简单文字不要开缓存,复杂且不常变的图形可以试;说明元素的脏标记会向上冒泡,父级已脏时提前返回。
3. **画面质量**:`hd` / `anti` / `noanti`;像素图建议关高清与抗锯齿(与第 7 篇一致,不重复展开)。
4. **列表与分页**:大量列表优先 `Scroll`(只对直接子元素生效),分页优先 `Page`;`.map()` 与 `key` 按 `dev.md:122`,不把 `key` 当性能开关。
5. **组件粒度**:把高频更新与低频更新拆到不同容器里,但不要嵌套过深;一次状态变化影响的组件越少越好。
6. **UI 栈**:能用 `hide` / `show` 就不重建;`setBackground` 把稳定背景移出栈;`keep` 只在「关一个开一个」的间隙用;栈越深,每次渲染的映射与隐藏切换越多。
7. **基础 props**:每个实例渲染时都会走一次基础参数创建,自定义 creator 里不要做重活。
8. 末尾给一张「症状 → 先查什么 → 怎么改」的排查表(卡顿、切页闪烁、频繁重建、列表滚动掉帧)。
`## 边界与注意`:缓存不是越多越好;`hidden` 的子树仍在内存里;`keep` 用完必须卸载;性能建议先测再改,不要凭感觉堆 `nocache`。
**`perf-demo.tsx`**(`PerfDemo`):一个切换 `hidden` / `cache` 的小面板,并把 `active` / `showBack` 的状态显示出来(用最小控制器或直接传静态值,二者择一,不引入引擎初始化)。默认导出、无 DOM 属性。
**侧边栏**:在「内置组件与 UI 系统」分组追加 `/advanced/ii/ui/ui-performance`。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const f="docs/advanced/ii/ui/ui-performance.md";if(!fs.existsSync(f))bad.push("MISSING:"+f);else{const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1");if(s.indexOf("## 边界与注意")<0)bad.push("EDGE");forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+r)});["hidden","不显示、不交互","cache","nocache","hd","noanti","Scroll","Page","key","keep","setBackground","createPropsBase","高级 III"].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY");if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER");if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF");const L=rd("docs/advanced/ii/ui/layer-transform-performance.md");const C=rd("docs/advanced/ii/ui/conditional-and-list-rendering.md");[L,C].forEach(function(t,i){if(t.indexOf("不显示、不交互")<0)bad.push("HIDDEN-DRIFT:"+i)})}const d="docs/.vitepress/components/demos/ui/perf-demo.tsx";if(!fs.existsSync(d))bad.push("NO-DEMO");else{const s=rd(d);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT");if(/style=|class=/.test(s))bad.push("DEMO-DOM");if(s.indexOf("hidden")<0)bad.push("DEMO-NO-HIDDEN")}const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/ui-performance","/advanced/ii/ui/ui-controller-and-stack","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-46", "PAGE-ASSERT", "MISSING:", "H1", "EDGE", "FORBID:", "KEY:", "HIDDEN-DRIFT", "CLIENTONLY", "LOADER", "CRLF", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>性能篇覆盖 `hidden` 优先、缓存与 `nocache`、`hd` / `anti`、`Scroll` / `Page`、`key` 规则、组件粒度、`keep` / `setBackground`、`createPropsBase`,并与高级 III 划清边界;`hidden` 表述与第 8 / 12 篇一致;单 H1、有边界节、CRLF、接 live、无被禁写法;demo 合规;侧边栏补一条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>性能篇与 perf demo 完成,Part 4 五篇齐备。</done>
</task>
<task type="auto">
<name>Task 4: 六类门禁收口 + NOTES 记录</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1..3 的 5 篇与 5 个 demo 已落盘、侧边栏 5 条齐全、构建 green。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/(本批 5 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts</read_first>
<action>按固定顺序跑门禁并记录:
1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。
2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning。
3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:`docs/` 路径 0 报错;引擎既有报错记条数与摘要。
4. 静态断言:5 篇单 H1 / `## 边界与注意` / 无被禁写法 / 全部接 live / 5 个 demo 默认导出且无 DOM 属性 / 侧边栏 21 条(本批 5 + 前三批 16)齐全 / 既有条目与高级 III 未丢 / 三篇(第 8、12、21)的 `hidden` 表述都含「不显示、不交互」。
5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。
6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-46 门禁`:六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、本批 5 篇与 5 个 demo 清单。
7. 交叉一致性:第 19 篇「没有全局注册 / 覆盖入口」与第 20 篇「没有全局替换接口」表述一致;第 17 篇 `v-model:value`、第 18 篇 `v-model:selected` 与第 13 篇的 `v-model:xxx` 口径一致。写进该小节。
本任务不改正文语义。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const md=["builtin-text-and-input","builtin-list-and-containers","ui-controller-and-stack","replace-builtin-ui","ui-performance"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+m);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m)});["builtin-text-demo","builtin-list-demo","controller-demo","strategy-demo","perf-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+m);if(/from\s+[\x22\x27]@user\/(?!client-base[\x22\x27])/.test(s))bad.push("DEMO-USER:"+m)});const cfg=rd("docs/.vitepress/config.ts");const links=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering","props","component-tsx","component-ts","slots-and-attrs","builtin-text-and-input","builtin-list-and-containers","ui-controller-and-stack","replace-builtin-ui","ui-performance"];links.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");["layer-transform-performance","conditional-and-list-rendering","ui-performance"].forEach(function(m){const s=rd("docs/advanced/ii/ui/"+m+".md");if(s.indexOf("不显示、不交互")<0)bad.push("HIDDEN-DRIFT:"+m)});if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-46 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-46", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "HIDDEN-DRIFT", "NOTES-NO-"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径类型报错 0;静态断言全绿(5 篇单 H1 / 边界节 / 无被禁写法 / 全部接 live / 5 个 demo 合规 / 侧边栏 21 条齐全 / 第 8、12、21 篇 `hidden` 表述一致);构建 green、无 dead link;NOTES 有 `### 10-46 门禁` 且含类型检查与引擎报错摘要。</acceptance_criteria>
<done>Part 4 五篇 5 demo 通过六类门禁并已记录。</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 5: 用户目视 5 个 live 并抽查五篇正文</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 4 通过(六类门禁全绿、构建产物已生成、NOTES 已记录)。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录)、docs/advanced/ii/ui/(本批 5 篇)、docs/.vitepress/components/demos/ui/(本批 5 个 demo)</read_first>
<action>请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 5 篇,逐条确认:①侧边栏「内置组件与 UI 系统」5 条可点开;②文本 / 输入篇 live 的打字机能逐字显示、「立即显示全部」生效、输入框能输入;③列表 / 容器篇 live 的选中、分页、滚动、光标正常;④UI 栈篇 live 能打开 / 关闭最小 UI,栈长度与激活状态随之变化;⑤策略篇 live 能看出「只显示最后一个」与「显示全部」的叠放差别;⑥性能篇 live 能切换 `hidden` / `cache` 并显示状态;⑦抽查第 19 / 20 篇:都写明「没有全局注册 / 覆盖入口」,替换只发生在打开处或包装层;⑧抽查第 18 篇:`Choices` 已按接口写入并注明 `ChoicesBox` 别名。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-46):通过` + 下一行 `用户原文:`;发现问题逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 4 后复验。只有用户明确通过才可进入 10-47。</action>
<what-built>5 篇正文与 5 个 live demo,构建产物可在本地预览。</what-built>
<how-to-verify>按上面①–⑧逐条检查;重点看内置组件 live 是否真实可用、栈与策略的差别是否看得出来、`Choices` 是否按接口写。</how-to-verify>
<resume-signal>若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。</resume-signal>
<acceptance_criteria>用户明确回复 live 与正文均通过,且 NOTES 有人工验证标记与用户原文;否则问题清单已记录并进入修复循环。</acceptance_criteria>
<verify>
<human-check>用户已明确确认 5 篇可读、5 个 live 正常、第 19 / 20 篇口径一致,并已把结论记入 NOTES。</human-check>
</verify>
<done>用户人工验证结论已记录。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 构建期(SSR)→ live demo(含内置组件) | 内置组件可能间接依赖浏览器 API,因此 demo 必须由 loader 动态 import |
| demo → 输入框 | `Input` 会在 `document.body` 创建真实输入元素;demo 只做本地输入,不持久化、不发请求 |
| 文档 → 读者(替换内置 UI) | 建议路径只有「打开处替换 / 包装 / 显示策略」,避免读者去改内置包 |
| 侧边栏 → 页面 | 每条 link 必须对应已存在页面 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-142 | Denial of Service(构建不可用) | 内置组件 demo 进入 SSR | high | mitigate | demo 由 loader 动态 import、`<ClientOnly>` 包裹;构建门禁必须 `build complete` |
| T-10-143 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页同任务;静态断言复核 21 条链接与既有条目、高级 III 未丢 |
| T-10-144 | Information Disclosure | `choices.tsx` 实现细节被写入正文 | medium | mitigate | 只读 props / emits / 函数签名;正文不描述实现;工作树哈希变化即停下问用户 |
| T-10-145 | Elevation of Privilege | 教读者改 `packages` 内置实现 | medium | mitigate | 替换篇只讲三种应用层改法,并明确当前没有全局替换接口 |
| T-10-146 | Repudiation | 命名与门禁无据可查 | medium | mitigate | NOTES 追加式记录;每个 auto 任务复检 `用户确认(10-46):可以执行` |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 确认门禁:NOTES 含 `用户确认(10-46):可以执行` + `用户原文:`;Task 5 后含 `用户人工验证(10-46):通过` + `用户原文:`,无 `状态:待处理`。
- 内容门禁:5 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性、`GameUI.get`。
- 契约门禁:`TextContent` 的 `width` 必填与 `autoHeight`、`Input` 的 `v-model:value`、`List` 的 `v-model:selected`、`Scroll` 只对直接子元素生效、`Choices` 按接口写且有「`ChoicesBox` 是俗称、源码导出名 `Choices` / `ChoicesUI`」的说明。
- 一致性门禁:第 8 / 12 / 21 篇的 `hidden` 表述一致;第 19 / 20 篇「没有全局注册 / 覆盖入口」一致。
- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。
- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改前三批已验收内容;未改 `10-01`..`10-45` 计划;未 commit;ROADMAP / STATE 本计划不改。
</verification>
<success_criteria>
- 读者能用现成组件拼出文本、输入、列表、分页、滚动与一次性选择框,并知道 `Choices` 怎么用。
- 读者能接 UI 栈、用背景与 `keep` 控制叠放与闪烁,并知道替换内置 UI 只有三种应用层做法。
- 性能篇成为整批的唯一汇总口径,且与第 8 / 12 篇不冲突。
- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。
</success_criteria>
<output>
Create `.planning/phases/10-docs-restructure/10-46-SUMMARY.md` when done
</output>
@@ -0,0 +1,202 @@
---
phase: 10-docs-restructure
plan: 46
subsystem: docs
tags: [vitepress, tsx, ui, builtin-components, ui-stack, performance]
requires:
- phase: 10-docs-restructure
provides: 10-45 的 props / 组件 / slots 四篇正文、4 个 live demo、侧边栏「组件化」分组
provides:
- Part 4 五篇(内置组件文本/输入、内置组件列表/容器、UIController 与 UI 栈、修改/替换内置 UI、UI 系统性能)
- 5 个 live demo 与侧边栏「内置组件与 UI 系统」分组
- 第 6 / 16 篇对第 17 篇的跨页链接回填
affects: [10-47, 10-48]
actuals:
tokens: 29000
tasks: 5
commits: 0
tech-stack:
added: []
patterns:
- 内置组件按公开契约使用,属性名保持 camelCase
- v-model:value / v-model:selected 双向绑定口径与第 13 篇一致
- 四层 UI 模型、栈与背景、lastOnly / showAll / showCustom
- keep 防闪烁,safelyUnload 只在栈空时关背景
- hidden 优先、缓存只给稳定子树、createPropsBase 不做重活
key-files:
created:
- docs/advanced/ii/ui/builtin-text-and-input.md
- docs/advanced/ii/ui/builtin-list-and-containers.md
- docs/advanced/ii/ui/ui-controller-and-stack.md
- docs/advanced/ii/ui/replace-builtin-ui.md
- docs/advanced/ii/ui/ui-performance.md
- docs/.vitepress/components/demos/ui/builtin-text-demo.tsx
- docs/.vitepress/components/demos/ui/builtin-list-demo.tsx
- docs/.vitepress/components/demos/ui/controller-demo.tsx
- docs/.vitepress/components/demos/ui/strategy-demo.tsx
- docs/.vitepress/components/demos/ui/perf-demo.tsx
modified:
- docs/.vitepress/config.ts
- docs/advanced/ii/ui/text.md
- docs/advanced/ii/ui/slots-and-attrs.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
key-decisions:
- "内置组件篇用「示例为主 + 常用项表」,但 TextContent 的 width 必填、autoHeight、Input 的 v-model:value、List 的 v-model:selected、Scroll 只对直接子元素生效写全"
- "第 20 篇只讲打开处替换 / 包装组件 / 显示策略与背景三种改法,不复制源码"
- "Choices 正文标题用 Choices(选项框),并注明 ChoicesBox 是俗称、源码导出名是 Choices / ChoicesUI"
- "文档站无法 import client-base 内置组件时,正文保留真实代码块,live 用等价元素演示并明确说明"
requirements-completed: []
coverage:
- id: D1
description: "内置组件:文本与输入篇 + builtin-text live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "打字机、立即显示全部与输入框交互需要人工目视"
- id: D2
description: "内置组件:列表与容器篇 + builtin-list live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "List / Page / Scroll / Selection 的交互与平铺要求需要人工确认"
- id: D3
description: "UIController 与 UI 栈篇 + controller live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "打开 / 关闭、栈长度与 active 状态需要人工操作确认"
- id: D4
description: "修改 / 替换内置 UI 篇 + strategy live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "lastOnly 与 showAll 的叠放差别需要人工目视"
- id: D5
description: "UI 系统性能与注意事项篇 + perf live"
verification:
- kind: automated_ui
ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"
status: pass
human_judgment: true
rationale: "hidden / cache 切换与 active / showBack 状态显示需要人工确认"
- id: D6
description: "第 6 / 16 篇跨页链接回填与侧边栏 5 条"
verification:
- kind: automated_ui
ref: "静态断言:5 篇单 H1 / 边界节 / 无被禁写法 / 21 条链接 / 回填链接"
status: pass
human_judgment: true
rationale: "链接位置与侧边栏显示名需要人工抽查"
duration: 24min
completed: 2026-10-31
status: complete
---
# Phase 10 Plan 46: 内置组件与 UI 系统 Summary
**Part 4 五篇与五个 live 落地:内置组件按公开契约讲、UI 栈讲清四层模型与 keep、替换只走三种应用层改法、性能篇收口 hidden 口径**
## Performance
- **Duration:** 24 min
- **Started:** 2026-10-31 18:28(本地时间)
- **Completed:** 2026-10-31 18:52(本地时间)
- **Tasks:** 5(Task 0 记录 + Task 1..4;Task 5 live 人工验证按用户要求留待最终审阅)
- **Files modified:** 14
## Accomplishments
- 新增 `builtin-text-and-input.md`:`TextContent` / `Textbox` / `Input` / `InputBox`,含打字机、`v-model:value`、`getInput` / `getInputNumber`。
- 新增 `builtin-list-and-containers.md`:`List` / `ListPage` / `Page` / `Scroll` / `Selection` / `Choices` / `ConfirmBox`,讲明 `Scroll` 只对直接子元素生效与 `ChoicesBox` 别名。
- 新增 `ui-controller-and-stack.md`:四层模型、栈与背景、`lastOnly` / `showAll` / `showCustom`、`keep`、场景 UI 与主 UI、基础 props 注入。
- 新增 `replace-builtin-ui.md`:内置 UI 定义、打开处替换 / 包装组件 / 显示策略与背景三种改法,明确没有全局替换接口。
- 新增 `ui-performance.md`:`hidden` 优先、缓存、HD / 抗锯齿、列表、组件粒度、UI 栈、`createPropsBase` 与排查表。
- 侧边栏新增「内置组件与 UI 系统」5 条;第 6 / 16 篇对第 17 篇的纯文本前瞻引用回填为链接。
- 六类门禁全绿:prettier、ESLint、docs 类型、静态断言、全量构建。
## Files Created/Modified
- `docs/advanced/ii/ui/builtin-text-and-input.md` - 文本、输入、Textbox、InputBox
- `docs/advanced/ii/ui/builtin-list-and-containers.md` - 列表、分页、滚动、选中框、一次性选择框
- `docs/advanced/ii/ui/ui-controller-and-stack.md` - UIController 四层模型与 UI 栈
- `docs/advanced/ii/ui/replace-builtin-ui.md` - 修改 / 替换内置 UI 的三种做法
- `docs/advanced/ii/ui/ui-performance.md` - UI 系统性能与注意事项
- `docs/.vitepress/components/demos/ui/*.tsx` - 5 个 live demo(builtin-text / builtin-list / controller / strategy / perf)
- `docs/.vitepress/config.ts` - 「内置组件与 UI 系统」新增 5 条
- `docs/advanced/ii/ui/text.md` - 第 17 篇链接回填
- `docs/advanced/ii/ui/slots-and-attrs.md` - 第 17 篇链接回填
- `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md` - 10-46 命名确认、哈希复核、门禁与待审记录
## Decisions Made
- 契约写法采用「示例为主 + 常用项表」,关键约束(`width`、`autoHeight`、`v-model:value`、`v-model:selected`、`Scroll` 直接子元素)全部写全。
- 第 20 篇不复制内置源码,只讲打开处替换 / 包装 / 显示策略与背景。
- `Choices` 按接口讲,正文标题用 `Choices(选项框)`,并注明 `ChoicesBox` 只是俗称。
- 文档站无法 import `client-base` 内置组件时,正文保留真实代码块,live 用等价元素演示并在「运行效果」说明。
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] 内置组件无法在文档站静态 import,live 改为等价元素演示**
- **Found during:** Task 1
- **Issue:** 导入 `@user/client-base` 触发 `Could not resolve "../renderer" from "packages-user/client-base/src/elements/index.ts"`;`packages-user/client-base/src/renderer` 在当前工作树不存在(`elements/index.ts` 与 `components/misc.tsx` 的 `../renderer` 引用未解析,属既有中间态,非本轮引入)。
- **Fix:** 正文保留真实内置组件代码块;`builtin-text-demo.tsx` / `builtin-list-demo.tsx` 用等价渲染元素演示交互,并在正文「运行效果」写明「文档站缺少完整客户端环境,示例用等价元素演示」。
- **Files modified:** `docs/.vitepress/components/demos/ui/builtin-text-demo.tsx`、`docs/.vitepress/components/demos/ui/builtin-list-demo.tsx`、两篇正文的「运行效果」段。
- **Commit:** 无(按用户要求不 commit)。
### Execution Environment Adaptation
- PowerShell 5.1 会把 `node -e` 的内嵌引号剥离,计划里的 `<automated>` 片段不能原样执行;改为把同一段 JS 提取到临时文件后运行,断言内容未变。
- PowerShell 把构建的标准错误输出当作终止错误;按退出码、`build complete` 与 dead link 判定,构建结果为 green。
## Issues Encountered
- `packages-user/client-base/src/renderer` 缺失导致内置组件无法进入文档站点构建;未修改任何源码,按计划允许的 fallback 处理。
- 既有引擎类型报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条),非本轮引入,保持不动。
## Gates
| 门禁 | 结果 |
|------|------|
| prettier `--write` / `--check` | 通过,`All matched files use Prettier code style!` |
| ESLint | 0 error / 0 warning |
| `vue-tsc -p docs/tsconfig.json` | `docs/` 路径 0 报错;既有引擎报错 11 条(非本轮引入) |
| 静态断言 | `STATIC-OK`(5 篇 + 5 demo + 21 条侧边栏 + 回填链接 + hidden 一致) |
| 全量构建 | green,`build complete in 22.06s.`,无 dead link |
## Known Stubs
- `builtin-text-demo.tsx` / `builtin-list-demo.tsx` 用等价元素而不是真实内置组件(原因见上)。正文已说明;真实组件需在完整客户端环境验证,留待 10-48 读者/用户审阅。
## Pending
- Task 5 live 目视与正文抽查:`live 人工验证(10-46):待最终人工审阅`。本轮未写「用户人工验证:通过」。
## Next Phase Readiness
- 10-47 可以直接复用本批的内置组件契约、UI 栈口径与性能结论。
- 10-48 审阅时需重点确认:内置组件 live 的等价演示是否可接受、`Choices` 别名说明是否清楚、第 19 / 20 篇「没有全局入口」是否一致。
## Self-Check: PASSED
- 5 篇正文存在,单 H1、`## 边界与注意`、CRLF。
- 5 个 demo 存在,默认导出、无 DOM 属性。
- 侧边栏 5 条与前三批 16 条齐全。
- 门禁全绿;本轮未 commit。
@@ -0,0 +1,332 @@
---
phase: 10-docs-restructure
plan: 47
type: execute
wave: 5
depends_on:
- 10-46
files_modified:
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- docs/.vitepress/config.ts
- docs/advanced/ii/ui/inventory-example-1-skeleton.md
- docs/advanced/ii/ui/inventory-example-2-grid.md
- docs/advanced/ii/ui/inventory-example-3-detail.md
- docs/advanced/ii/ui/inventory-example-4-scroll.md
- docs/advanced/ii/ui/inventory-example-5-state.md
- docs/advanced/ii/ui/inventory-example-6-animation-and-register.md
- docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx
- docs/.vitepress/components/demos/ui/inventory-2-grid.tsx
- docs/.vitepress/components/demos/ui/inventory-3-detail.tsx
- docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx
- docs/.vitepress/components/demos/ui/inventory-5-state.tsx
- docs/.vitepress/components/demos/ui/inventory-6-full.tsx
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 84000
raw_tokens: 52000
tasks: 6
confidence: low
must_haves:
truths:
- "完整示例六篇(目标与骨架 / 道具网格 / 详情区 / 滚动与列表 / 交互与状态 / 动画、拆分与注册)按顺序递增,每篇只在上一步基础上加一小段代码,不重复贴整份实现"
- "每篇配一个 live 检查点(6 个 `.tsx` demo),页面用 `&lt;ClientOnly&gt;` + `() =&gt; import('...')`;6 个 demo 默认导出、无 DOM 属性,只 import vue 与元素标签,**允许但不要求** `@motajs/system` 的 `GameUI` / `UIController`,除此之外不得 import 其它 `@motajs/*` / `@user/*`;文档正文不展示 demo 源码,只给正文代码块"
- "六篇的组件拆分从第一天定好并在后续只填内容:`InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar`;最终篇给出文件结构与 `GameUI` 注册、打开处替换"
- "面板 Props 一律 `extends IGameUIPropsBase, DefaultProps`、`props` 数组含 `controller` / `instance` / `state`;示例数据只用 `g-rect` / `g-rectr` / `text` 造假数据,不引入真实素材、不出现 Thumbnail / Tip、不出现 core 命名空间"
- "显示与列表口径与前面一致:频繁切换用 `hidden`,必须卸载 / 重置时才用三元;循环用 `.map()`,`key` 只在会重排 / 增删且需要保留身份时加"
- "交互篇只用手写按钮与 `useKey(...)!`(不配按键 live 可用按钮替代),状态用 `ref` / `computed` / `watch` 驱动;动画篇的 live 用 `requestAnimationFrame` 驱动并在 `onUnmounted` 取消(不在 live 里用返回 `ITransitionedController | null` 的渐变工具;正文若提及必须写明可空并做 null 判断)"
- "最终篇的 live 是完整背包面板:网格、详情、滚动、装备 / 使用、关闭、动画都能用;跑不起来不删内容,但要保留代码与说明"
- "侧边栏新增「完整示例」分组 6 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link"
- "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning"
- "未改 `packages/` / `packages-user/` / `src/`、未改前四批已验收的 21 篇正文与 19 个 demo 的语义、未改 `10-01`..`10-46` 计划、未改既有 JSDoc/注释;不 commit"
artifacts:
- "docs/advanced/ii/ui/inventory-example-1-skeleton.md、inventory-example-2-grid.md、inventory-example-3-detail.md、inventory-example-4-scroll.md、inventory-example-5-state.md、inventory-example-6-animation-and-register.md"
- "docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx、inventory-2-grid.tsx、inventory-3-detail.tsx、inventory-4-scroll.tsx、inventory-5-state.tsx、inventory-6-full.tsx"
- "docs/.vitepress/config.ts(高级 II 子分组内新增「完整示例」分组 6 条)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-47 命名确认、门禁与人工验证记录)"
key_links:
- "六篇是同一个面板的六步:每一步的 live 必须是「上一步 + 本步新增」,读者按顺序看能对上;任何一步另起一套实现都会让读者无法对照"
- "第 22 篇的组件拆分决定第 23–27 篇的落点;第 27 篇的「拆分与注册」必须与第 22 篇的拆分一致,不能到结尾才换结构"
- "第 23 篇的 `ItemCell` props 写法必须复用第 13 篇;第 26 篇的 `useKey` 必须复用第 11 篇;第 27 篇的动画必须复用第 8 篇的 `alpha` / `scale` 与第 21 篇的性能口径"
- "第 27 篇的最终 live 是本批唯一的「完整面板」,也是 10-48 读者审阅的终点页;它必须能独立看懂,不依赖前五篇的 live"
---
> **编号变更(2026-11-01):** 本文件中的旧 10-49 / 10-50 分工已重排,完整映射见文末「编号变更」小节。
<scope_justification>
本计划 6 个任务、14 个 `files_modified`,超出默认上限,保持单计划:
- 六篇分三个写作任务(2 + 2 + 2),每篇都带 live;门禁与人工验证独立。合并会让「6 篇 + 6 demo + 侧边栏 + 全量门禁」成为不可验证的大块。
- 14 个文件里 6 篇正文、6 个 demo(每步一个,便于读者对照)、1 个侧边栏、1 个记录文件。demo 逐级递增是本批的核心价值(锁定决策 16「每步只加一小段代码 + 一个 live 检查点」),合并成 1 个 demo 会破坏检查点。
- 六篇正文天然短于前几批(每篇只讲一个增量),但单个 demo 是完整可运行组件,代码量集中;拆成两个计划会让同一份面板在两次执行里重复读上下文。
不删内容:六篇正文、6 个 live、组件拆分、交互与按键、动画与注册、六类门禁、用户目视全部保留。
</scope_justification>
<objective>
用六篇把一个完整可用的背包 / 装备面板写出来:目标与骨架 → 道具网格 → 详情区 → 滚动与列表 → 交互与状态 → 动画、拆分与注册。每一步只加一小段代码,并配一个 live 检查点。
Purpose: 这是整批的收束:读者在前面学到的模板、元素、响应式、事件、组件、内置组件、UI 栈,全部在同一个面板里汇合。它也是 10-48 独立读者审阅的终点页——如果读者能照着这六篇把面板跑起来,这批文档就成立了。
Output: 6 篇正文、6 个逐级递增的 `.tsx` live demo、侧边栏「完整示例」分组、NOTES 追加记录。**不改源码、不改前四批已验收内容、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md
@.planning/phases/10-docs-restructure/10-46-PLAN.md
@docs/.vitepress/config.ts
@docs/advanced/ii/ui/ui-template.md
@docs/advanced/ii/ui/props.md
@docs/advanced/ii/ui/conditional-and-list-rendering.md
@docs/advanced/ii/ui/builtin-list-and-containers.md
@docs/advanced/ii/ui/ui-performance.md
@docs/.vitepress/components/demos/ui/conditional-demo.tsx
**流程约定:**
- 只新增 / 修改本计划 `files_modified` 内文件;不改 `10-01`..`10-46` 计划;不重规划其它批次。
- **Task 0 是硬关卡**:汇报六篇的增量划分、6 个 demo 的命名与目录、示例组件拆分与最终文件结构、示例技术选型(网格用容器还是 `Scroll`、滚动用 `Scroll` 还是 `ListPage`),等用户明确回复「可以执行」。
- 六篇文件名与侧边栏名已在 10-43 命名总表确认;Task 0 复述确认值,若用户本轮改名先更新 NOTES 再落盘。
- 改文件前声明「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit。
**本批写作硬规则(延续前四批):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。
**参考文件与哈希:** 以 NOTES 的「参考清单哈希基线」为准;本计划涉及 `render/src/core/item.ts`、`render/src/core/container.ts`、`render-vue/src/props.ts`、`system/src/ui/controller.ts`、`system/src/ui/ui.ts`、`client-base/src/components/list.tsx`、`scroll.tsx`、`textbox.tsx`、`use/hotkey.ts`、`client-modules/src/render/use.ts`(渐变工具)。写作前逐条 `git hash-object` 比对;不一致或工作树被改即停下问用户。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报六步增量划分与最终文件结构,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 22–27 篇;Open Questions Q3)、docs/advanced/ii/ui/(前四批已落地篇目体例)、docs/.vitepress/config.ts</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——用六篇写一个完整背包 / 装备面板,每篇只加一小段代码并配一个 live:①目标与骨架;②道具网格;③详情区;④滚动与列表;⑤交互与状态;⑥动画、拆分与注册。
**为什么**——前四批讲的是零件,这一批必须证明零件能拼成能用的面板;它同时是最后独立读者审阅的终点页,读者能不能照着跑起来,就是这批文档是否成立的判据。
**大致怎么做**——Task 1 写第 22、23 篇 + `inventory-1-skeleton` / `inventory-2-grid`;Task 2 写第 24、25 篇 + `inventory-3-detail` / `inventory-4-scroll`;Task 3 写第 26、27 篇 + `inventory-5-state` / `inventory-6-full`;Task 4 跑六类门禁并写 NOTES;Task 5 由用户目视 6 个 live 并抽查正文。
**影响范围**——新增 `docs/advanced/ii/ui/` 下 6 个 `.md` 与 `demos/ui/` 下 6 个 `.tsx`;追加侧边栏「完整示例」6 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、前四批已验收的 21 篇与 19 个 demo、ROADMAP / STATE。
**必须请用户确认:**
| 项 | 建议值 |
|----|--------|
| 六篇文件名 | `inventory-example-1-skeleton.md` … `inventory-example-6-animation-and-register.md`(沿用 10-43 命名总表) |
| 六篇侧边栏名 | 示例(一)目标与骨架 / (二)道具网格 / (三)详情区 / (四)滚动与列表 / (五)交互与状态 / (六)动画、拆分与注册 |
| demo 目录与命名 | `demos/ui/inventory-1-skeleton.tsx`、`-2-grid.tsx`、`-3-detail.tsx`、`-4-scroll.tsx`、`-5-state.tsx`、`-6-full.tsx` |
| 面板尺寸 | 720×480 根容器 |
| 组件拆分(第 22 篇定下,后续不改) | `InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar` |
| 假数据 | 8–12 个道具,用 `g-rect` / `g-rectr` / `text` 绘制图标与名称,不引入真实素材 |
| 第 25 篇的滚动方案 | 先给 `Scroll` 平铺(推荐),末尾用一小节对比 `ListPage` 左列表右详情;两者都讲、不二选一 |
| 第 27 篇的注册与打开 | `export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)` + 打开处替换;不写全局注册表 |
同时说明:六篇的 live 是**逐级递增的六个独立 demo**(不是同一个文件改六次),读者可以在每篇看到「到这一步为止」的样子;第 27 篇的 `inventory-6-full.tsx` 是最终版,也是 10-48 的审阅终点。**参考文件:`packages/render/src/core/item.ts`、`core/container.ts`、`render-vue/src/props.ts`、`system/src/ui/controller.ts`、`system/src/ui/ui.ts`、`client-base/src/components/list.tsx`、`scroll.tsx`、`textbox.tsx`、`use/hotkey.ts`、`client-modules/src/render/use.ts`(渐变工具);策略:写作前逐条 `git hash-object -- <path>` 与 NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。</action>
<what-built>尚无产物;本任务只汇报六步增量、demo 命名、组件拆分与示例技术选型。</what-built>
<how-to-verify>确认:①是否同意六篇的增量划分与 6 个 demo 命名;②组件拆分五个名字是否可用;③第 25 篇「`Scroll` 为主 + `ListPage` 对比」是否可接受;④假数据与 720×480 尺寸是否可接受。</how-to-verify>
<resume-signal>回复「可以执行」以继续(可同时给出命名或拆分调整);其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且六篇命名、6 个 demo 命名、五个组件名、第 25 篇取舍、面板尺寸五项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,六篇与 6 个 demo 的命名、组件拆分、第 25 篇取舍已确定。</human-check>
</verify>
<done>用户回复「可以执行」且待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 示例(一)目标与骨架 /(二)道具网格 + 两个 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx, docs/.vitepress/components/demos/ui/inventory-2-grid.tsx, docs/.vitepress/config.ts</files>
<precondition>本计划的 Task 0 已记录 `用户确认(10-47):可以执行`;10-46 已验收且构建 green。本任务负责把该确认与用户原文追加进 NOTES。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 22、23 篇;Author Entry;UI System 的 open / close)、docs/advanced/ii/ui/ui-template.md(模板与 Props 基类)、docs/advanced/ii/ui/props.md(`ItemCell` props 写法)、docs/advanced/ii/ui/conditional-and-list-rendering.md(`.map()` 与 `key` 规则)、dev.md:116-123</read_first>
<action>先向 NOTES 末尾追加 `## 10-47 命名确认`(`用户确认(10-47):可以执行` + 下一行 `用户原文:` + 六篇与 6 个 demo 最终名 + 五个组件名 + 面板尺寸),并重跑本任务参考文件的哈希比对追加结果。然后写前两篇与两个 demo。
**(1)`inventory-example-1-skeleton.md`(第 22 篇)**:先给目标与最终效果(文字描述 + 一张结构示意,不用图片),再给**文件拆分**:`inventory-panel.tsx` 里放 `InventoryPanel`,同目录下 `item-grid.tsx` / `item-cell.tsx` / `item-detail.tsx` / `action-bar.tsx`(正文说明每个文件负责什么)。然后写骨架:
- 720×480 根容器 + `g-rectr` 背景 + 标题文字 + 关闭按钮(点击 `props.controller.close(props.instance)`)。
- 内容区用两个占位容器(左网格 / 右详情),先各放一行 `text` 占位。
- Props:`interface InventoryPanelProps extends IGameUIPropsBase, DefaultProps {}`,`props: ['controller', 'instance', 'state']`,`export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)`。
- 打开处:给 `client.sceneController.open(InventoryUI, {})` 与 `props.controller.open(InventoryUI, {})` 两种调用。
live 用 `inventory-1-skeleton`。`## 边界与注意`:骨架阶段就把组件拆分定下来,后面只填内容;不用真实素材,图标一律用图形 + 文字;关闭按钮必须在骨架阶段就能用,否则后面无法验证。
**(2)`inventory-example-2-grid.md`(第 23 篇)**:先给数据模型 `interface Item { id: string; name: string; count: number; desc: string }` 与一份假数据;再写 `ItemCell`(props:`item` / `selected` / `onSelect`,复用第 13 篇的写法),格子用 `g-rectr` + `text` 画名称与数量,选中用边框或 `alpha` 区分;再写 `ItemGrid` 用 `.map()` 排出 5 列网格,`selectedId` 用 `ref`。讲 `key`:这一页的列表顺序固定、格子无内部状态,**先不加** `key`,并说明原因;如果读者后续要增删,再加。live 用 `inventory-2-grid`(点击格子选中)。`## 边界与注意`:网格列宽与间距用常量算,不要手写每格坐标;选中态只由 `selectedId` 决定,不要在每个格子里各存一份;`.map()` 返回的每一项结构必须一致。
**(3)两个 demo**:`inventory-1-skeleton.tsx`(`Inventory1Skeleton`)只显示骨架与关闭按钮(关闭按钮在 live 里可改为显示一行提示,因为没有真实 UI 栈);`inventory-2-grid.tsx`(`Inventory2Grid`)在骨架上加网格与选中态。两者都要能被单独看懂,且第 2 个必须是「第 1 个 + 网格」。默认导出、只 import vue 与元素标签、无 DOM 属性。
**(4)侧边栏**:追加 `{ text: '完整示例', collapsed: false, items: [...] }`,先放两篇。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/inventory-example-1-skeleton.md":["InventoryPanel","ItemGrid","ItemCell","ItemDetail","ActionBar","IGameUIPropsBase","DefaultProps","GameUI","sceneController.open","720","480"],"docs/advanced/ii/ui/inventory-example-2-grid.md":["ItemCell","ItemGrid",".map(","selectedId","g-rectr","key"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["inventory-1-skeleton.tsx","inventory-2-grid.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/inventory-example-1-skeleton","/advanced/ii/ui/inventory-example-2-grid","/advanced/ii/ui/ui-performance","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(cfg.indexOf("完整示例")<0)bad.push("CFG-NO-PART5");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-47", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 追加 10-47 命名确认与哈希比对;骨架篇含五个组件名、Props 基类、`GameUI` 注册、两种打开处、720×480;网格篇含数据模型、`ItemCell` / `ItemGrid`、`.map(`、`selectedId`、`g-rectr` 与 `key` 取舍说明;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出且无 DOM 属性;侧边栏新增「完整示例」两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>示例(一)(二)完成,组件拆分与网格落地。</done>
</task>
<task type="auto">
<name>Task 2: 示例(三)详情区 /(四)滚动与列表 + 两个 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/.vitepress/components/demos/ui/inventory-3-detail.tsx, docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-47):可以执行`;Task 1 两篇与「完整示例」分组已存在且构建 green。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 24、25 篇;Built-in Components 的 `TextContent` / `Scroll` / `Page` / `ListPage`)、docs/advanced/ii/ui/builtin-text-and-input.md(`TextContent` 的 `width` 必填与 `autoHeight`)、docs/advanced/ii/ui/builtin-list-and-containers.md(`Scroll` 只对直接子元素生效、`ListPage` 用法)、docs/.vitepress/components/demos/ui/inventory-2-grid.tsx</read_first>
<action>写第 24、25 篇与两个 demo,均在上一步之上增量。
**(1)`inventory-example-3-detail.md`(第 24 篇)**:写 `ItemDetail`:
- 布局:右侧面板的背景、名称、数量、描述区域;用 `g-rectr` / `text` 搭出来。
- 用 `computed` 取当前道具:`const selectedItem = computed(() => items.value.find(v => v.id === selectedId.value))`(数据与选中态从父组件传入或提升到父组件,按第 22 篇的拆分决定)。
- 条件显示:没有选中时显示「请选择道具」;有选中时显示详情。**优先 `hidden`**(两块都渲染、用 `hidden` 切换),并说明为什么这里适合 `hidden`(切换频繁、需要保留状态)。
- 长描述用 `TextContent` 并给 `width`(必填)与 `autoHeight`;说明为什么不用文字元素硬排(不换行)。
live 用 `inventory-3-detail`(选中不同格子,详情随之更新;无选中时提示)。**live 与正文代码块不是同一份代码**:live 用元素层等价画面(`text` + `alpha` / 尺寸放着,不引入 `@user/client-base` 的内置组件),正文代码块才用 `TextContent`;正文必须用一句话说明这一点,避免读者以为 live 就是那一段代码。`## 边界与注意`:`computed` 里不要写副作用;`find` 返回 `undefined` 时要处理;`TextContent` 不给 `width` 不能用;两块都渲染时注意 `zIndex` 与遮挡。
**(2)`inventory-example-4-scroll.md`(第 25 篇)**:讲道具变多之后的两条路:
- `Scroll` 平铺(推荐):把网格的每一格作为 `Scroll` 的**直接子元素**(不要用一个容器包住全部内容),给 `Scroll` 的 `loc` 与 `padEnd`;用 `ref` 拿 `scrollTo` / `getScrollLength` 做一个「滚到最上面」按钮。
- `ListPage` 左列表右详情:把现有网格换成 `ListPage`,讲 `basis` / `right` / `close` 与动态 slot;说明它在「左列表右详情」场景下省掉自己算分栏。
- 给一张「什么时候用 `Scroll`、什么时候用 `ListPage`、什么时候用 `Page`」的判定表。
live 用 `inventory-4-scroll`(20–50 个假道具可滚动,滚动条与滚轮可用)。**同样地,live 用元素层等价画面演示滚动**(`Scroll` 只在正文代码块展示),正文用一句话点明「live 展示的是滚动效果,代码块给出 `Scroll` / `ListPage` 的真实写法」。`## 边界与注意`:`Scroll` 里包一层容器会让虚拟滚动失效;列表项高度不一致时 `padEnd` 可能要调;`ListPage` 的 slot 按选中 key 渲染,key 必须与 `list` 里的 id 对应;容器自定义标签只写 `container-custom`。
**(3)两个 demo**:`inventory-3-detail.tsx`(`Inventory3Detail`)= 上一步 + 详情区;`inventory-4-scroll.tsx`(`Inventory4Scroll`)= 上一步 + 滚动列表。都要能被单独看懂且体现增量。默认导出、无 DOM 属性。
**(4)侧边栏**:在「完整示例」分组追加两篇。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/inventory-example-3-detail.md":["ItemDetail","computed(","hidden","TextContent","width","autoHeight","请选择道具"],"docs/advanced/ii/ui/inventory-example-4-scroll.md":["Scroll","ListPage","Page","scrollTo","getScrollLength","直接子元素","container-custom","padEnd"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["inventory-3-detail.tsx","inventory-4-scroll.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const d4=fs.existsSync("docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx")?rd("docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx"):"";if(d4.indexOf("Scroll")<0&&d4.indexOf("scroll")<0)bad.push("DEMO4-NO-SCROLL");const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/inventory-example-3-detail","/advanced/ii/ui/inventory-example-4-scroll","/advanced/ii/ui/inventory-example-2-grid","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-47", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "DEMO4-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>详情篇含 `ItemDetail`、`computed`、`hidden` 优先、`TextContent` + `width` + `autoHeight`、无选中提示;滚动篇含 `Scroll` / `ListPage` / `Page` 三者取舍、`scrollTo` / `getScrollLength`、`padEnd`、`Scroll` 只对直接子元素生效、`container-custom`;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出且无 DOM 属性、第 4 个 demo 含滚动;侧边栏补两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>示例(三)(四)完成,详情区与滚动落地。</done>
</task>
<task type="auto">
<name>Task 3: 示例(五)交互与状态 /(六)动画、拆分与注册 + 两个 demo + 侧边栏</name>
<files>docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md, docs/.vitepress/components/demos/ui/inventory-5-state.tsx, docs/.vitepress/components/demos/ui/inventory-6-full.tsx, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户确认(10-47):可以执行`;Task 2 两篇已落盘且构建 green。</precondition>
<read_first>10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 26、27 篇;UI System 的 `keep` / `setBackground`;Performance 的 `hidden` 与 `alpha`)、docs/advanced/ii/ui/reactivity.md(`watch` 用法)、docs/advanced/ii/ui/hotkey-in-ui.md(`useKey(...)!` 口径)、docs/advanced/ii/ui/layer-transform-performance.md(`alpha` / `scale` / `hidden`)、docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx、packages-user/client-modules/src/render/use.ts(渐变工具签名)</read_first>
<action>写第 26、27 篇与两个 demo,完成整条示例。
**(1)`inventory-example-5-state.md`(第 26 篇)**:写 `ActionBar` 与状态驱动:
- 「装备」按钮:`equippedId` 用 `ref`,点一下把当前选中道具设为已装备;已装备的格子在 `ItemCell` 上用边框或 `alpha` 表现。
- 「使用」按钮:`items` 里对应道具 `count` 减一;数量为 0 时按钮不可用(用 `alpha` + `hidden` 表现禁用视觉,并让点击回调直接返回)。
- `computed` 派生「当前是否能使用 / 是否能装备」;`watch` 做一个副作用(例如数量变化时更新一行提示文字),并说明什么时候该用 `watch`、什么时候该用 `computed`。
- 键盘收口:`const key = useKey(props.state.hotkey.system)!;`,把 `@common/exit` 接到关闭面板;说明组件卸载会自动离开作用域。若 live 环境没有按键系统,页面注明「live 里用关闭按钮替代,按键写法见代码块」。
- `noevent` 遮罩:面板背后放一层遮罩让点击不穿透;说明 `noevent` 与 `hidden` 的区别。
live 用 `inventory-5-state`(点击装备 / 使用,数量与提示变化)。`## 边界与注意`:不要在 `watch` 里改同一个状态造成循环;按钮禁用只是视觉 + 早返回,不要靠 `hidden` 藏起来当禁用;`useKey` 只在 `setup` 里调用;遮罩层注意 `zIndex`。
**(2)`inventory-example-6-animation-and-register.md`(第 27 篇)**:收尾:
- 动画:**live 用 `requestAnimationFrame`(配 `onUnmounted` 取消)**让选中格的边框 / 详情区透明度平滑变化——不依赖任何返回可空值的渐变控制器,避免 `null` 分支;给出 `onUnmounted` 清理;说明动画只改 `alpha` / `scale` / 颜色,不要每帧重建组件。若正文额外展示仓库的渐变工具(`transitioned` 一类),**必须写明其返回值是 `ITransitionedController | null` 并做 null 判断**,且 live 不得使用它。
- 拆分回顾:把前五步的代码按第 22 篇的结构落到五个文件,给**最终文件结构**(目录树)与每个文件的职责。
- 注册与打开:`export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)`;打开处替换(游戏内主 UI 栈用 `props.state.mainUIController.open(InventoryUI, {})`,场景 UI 用 `controller.open`);`keep` 防闪烁的用法一句带过并链接第 19 篇。
- 性能自查:用第 21 篇的清单逐条对照(`hidden` 优先、列表 `Scroll`、`key` 规则、组件粒度),给一张勾选表。
- 最后一段:完整面板的 live。
live 用 `inventory-6-full`(网格 + 详情 + 滚动 + 装备 / 使用 + 关闭 + 动画)。`## 边界与注意`:渐变在卸载后必须停;拆分后 Props 要逐层传,不要用全局变量绕过;注册只是把名字和组件绑在一起,不写入全局表,因此不要按名字取 UI;最终 live 跑不起来不删内容,保留代码与说明。
**(3)两个 demo**:`inventory-5-state.tsx`(`Inventory5State`)= 上一步 + 交互与状态;`inventory-6-full.tsx`(`Inventory6Full`)= 完整面板,必须包含网格、详情、滚动、装备 / 使用、关闭、动画。默认导出、无 DOM 属性;动画**统一用 `requestAnimationFrame` + `onUnmounted` 取消**(不要在 live 里用返回 `ITransitionedController | null` 的渐变工具),不要引入新依赖。
**(4)侧边栏**:在「完整示例」分组追加最后两篇。只做加法。
写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const need={"docs/advanced/ii/ui/inventory-example-5-state.md":["ActionBar","ref(","computed(","watch(","useKey(","@common/exit","noevent","equippedId","alpha"],"docs/advanced/ii/ui/inventory-example-6-animation-and-register.md":["InventoryPanel","ItemGrid","ItemCell","ItemDetail","ActionBar","GameUI","onUnmounted","alpha","scale","hidden","keep"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const d5="docs/.vitepress/components/demos/ui/inventory-5-state.tsx";const d6="docs/.vitepress/components/demos/ui/inventory-6-full.tsx";[[d5,["selectedId"]],[d6,["selectedId","InventoryPanel"]]].forEach(function(pair,i){const p=pair[0];if(!fs.existsSync(p)){bad.push("NO-DEMO:"+i);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+i);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+i);pair[1].forEach(function(k){if(s.indexOf(k)<0)bad.push("DEMO-KEY:"+i+":"+k)})});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/inventory-example-5-state","/advanced/ii/ui/inventory-example-6-animation-and-register","/advanced/ii/ui/inventory-example-4-scroll","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-47", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>交互篇含 `ActionBar` / `equippedId` / `ref` / `computed` / `watch` / `useKey(...)` / `@common/exit` / `noevent`,并说明禁用只是视觉 + 早返回;动画注册篇含五个组件名、`GameUI` 注册、`onUnmounted` 清理、`alpha` / `scale` / `hidden` 与 `keep`,并给最终文件结构与性能自查表;两篇单 H1、有边界节、CRLF、接 live、无被禁写法(含 `GameUI.get`);两个 demo 默认导出、无 DOM 属性、第 6 个是完整面板;侧边栏补两条且既有条目未丢;构建 green、无 dead link。</acceptance_criteria>
<done>示例(五)(六)完成,完整面板可运行。</done>
</task>
<task type="auto">
<name>Task 4: 六类门禁收口 + NOTES 记录 + 全批交叉核对</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1..3 的 6 篇与 6 个 demo 已落盘、侧边栏 6 条齐全、构建 green。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区与前面四批记录)、docs/advanced/ii/ui/(本批 6 篇 + 前四批 21 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts</read_first>
<action>按固定顺序跑门禁并记录:
1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。
2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning。
3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:`docs/` 路径 0 报错;引擎既有报错记条数与摘要。
4. 静态断言:6 篇单 H1 / `## 边界与注意` / 无被禁写法 / 全部接 live / 6 个 demo 默认导出且无 DOM 属性(只允许 vue、元素标签与 `@motajs/system`;不得出现其它 `@motajs/*` 或任何 `@user/*`) / 侧边栏 27 条(10-43 的 6 + 10-44 的 6 + 10-45 的 4 + 10-46 的 5 + 本批 6)齐全 / 既有条目与高级 III 未丢 / 第 22 与第 27 篇的五个组件名一致。
5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。
6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-47 门禁`:六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、本批 6 篇与 6 个 demo 清单。
7. **全批交叉核对**(写进该小节,逐条给结论):①27 篇是否都在侧边栏出现且无重复;②六个 Part 分组的顺序是否与 10-43 命名总表一致;③`hidden` 口径在第 8 / 12 / 21 / 24 篇是否一致;④`v-model:xxx` 口径在第 13 / 17 / 18 篇是否一致;⑤第 22 与第 27 篇的组件拆分是否一致;⑥是否有任何页面出现被禁写法。若发现不一致,**只记录、不改前几批正文**,留给 10-48 的独立读者审阅记录,由用户在 10-49 的修订环节裁决。
本任务不改本批正文语义。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const md=["inventory-example-1-skeleton","inventory-example-2-grid","inventory-example-3-detail","inventory-example-4-scroll","inventory-example-5-state","inventory-example-6-animation-and-register"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+m);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m)});["inventory-1-skeleton","inventory-2-grid","inventory-3-detail","inventory-4-scroll","inventory-5-state","inventory-6-full"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+m);if(/from\s+[\x22\x27]@user\//.test(s))bad.push("DEMO-USER:"+m)});const cfg=rd("docs/.vitepress/config.ts");const all=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering","props","component-tsx","component-ts","slots-and-attrs","builtin-text-and-input","builtin-list-and-containers","ui-controller-and-stack","replace-builtin-ui","ui-performance","inventory-example-1-skeleton","inventory-example-2-grid","inventory-example-3-detail","inventory-example-4-scroll","inventory-example-5-state","inventory-example-6-animation-and-register"];all.forEach(function(m){const hit=(cfg.match(new RegExp("/advanced/ii/ui/"+m.replace(/[-.]/g,"\\$&")+"[\x27\x22]","g"))||[]).length;if(hit<1)bad.push("CFG-MISSING:"+m);if(hit>1)bad.push("CFG-DUP:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");const p22=rd("docs/advanced/ii/ui/inventory-example-1-skeleton.md");const p27=rd("docs/advanced/ii/ui/inventory-example-6-animation-and-register.md");["InventoryPanel","ItemGrid","ItemCell","ItemDetail","ActionBar"].forEach(function(k){if(p22.indexOf(k)<0||p27.indexOf(k)<0)bad.push("SPLIT-DRIFT:"+k)});if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-47 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; if($np -notmatch '全批交叉核对'){ Write-Error 'NOTES-NO-CROSSCHECK' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONFIRM-10-47", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "CFG-DUP", "SPLIT-DRIFT", "NOTES-NO-"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径类型报错 0;静态断言全绿(6 篇单 H1 / 边界节 / 无被禁写法 / 全部接 live / 6 个 demo 默认导出、无 DOM 属性、只 import vue + 元素标签 +(可选)`@motajs/system` / 27 条侧边栏链接各出现一次且无重复 / 既有条目与高级 III 未丢 / 第 22 与第 27 篇组件名一致);构建 green、无 dead link;NOTES 有 `### 10-47 门禁`、`全批交叉核对` 小节与类型检查 / 引擎报错摘要。</acceptance_criteria>
<done>Part 5 六篇 6 demo 通过六类门禁,全批 27 篇已在侧边栏就位并有交叉核对记录。</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 5: 用户目视 6 个 live 并抽查六篇正文</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 4 通过(六类门禁全绿、构建产物已生成、NOTES 已记录、交叉核对已完成)。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录与交叉核对)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/(本批 6 个 demo)</read_first>
<action>请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 6 篇,逐条确认:①侧边栏「完整示例」6 条可点开;②第 1 个 live 是骨架 + 关闭;③第 2 个 live 有网格且能选中;④第 3 个 live 选中后详情更新、无选中时有提示;⑤第 4 个 live 能滚动;⑥第 5 个 live 装备 / 使用生效、数量变化;⑦第 6 个 live 是完整面板(网格 + 详情 + 滚动 + 装备 / 使用 + 关闭 + 动画);⑧逐篇对照:每一步都是「上一步 + 增量」,没有另起一套实现;⑨第 27 篇的最终文件结构与第 22 篇一致。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-47):通过` + 下一行 `用户原文:`;发现问题逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 4 后复验。只有用户明确通过才可进入 10-48 的独立读者审阅;本次 live 的最终全站复验仍由 10-49 Task 4 覆盖。</action>
<what-built>6 篇正文与 6 个逐级递增的 live demo,最终版是完整背包面板。</what-built>
<how-to-verify>按上面①–⑨逐条检查;重点看六步是否真的递增、最终面板是否可用、第 22 与第 27 篇的拆分是否一致。</how-to-verify>
<resume-signal>若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。</resume-signal>
<acceptance_criteria>用户明确回复 6 篇可读、6 个 live 正常且递增关系清楚,并已把结论记入 NOTES;否则问题清单已记录并进入修复循环。</acceptance_criteria>
<verify>
<human-check>用户已明确确认六篇增量关系成立、最终面板可用,并已把结论记入 NOTES。</human-check>
</verify>
<done>用户人工验证结论已记录。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 构建期(SSR)→ live demo | 六个 demo 由 loader 动态 import;页面只静态 import 包装组件 |
| demo → 假数据 | 只使用本地写死的假道具,不读存档、不发请求、不持久化 |
| 文档 → 读者 | 读者会照抄六个文件结构;拆分不一致会让读者拼不起来 |
| 侧边栏 → 页面 | 每条 link 必须对应已存在页面 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-147 | Denial of Service(构建不可用) | 六个 `.tsx` demo | high | mitigate | 全部由 loader 动态 import、`<ClientOnly>` 包裹;构建门禁必须 `build complete` |
| T-10-148 | Tampering | 侧边栏 27 条链接 | medium | mitigate | 静态断言逐条计数:每条恰好出现一次(缺失与重复都失败);既有条目与高级 III 未丢 |
| T-10-149 | Repudiation | 组件拆分前后不一致 | medium | mitigate | 静态断言比对第 22 与第 27 篇的五个组件名;不一致即失败 |
| T-10-150 | Information Disclosure | 示例泄露内部实现 | low | mitigate | 静态断言禁渲染器类名 / 标签注册 / core 命名空间 / `GameUI.get`;只写应用层用法 |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包(动画只用 vue 或仓库已有工具);缺依赖即停止报告 |
</threat_model>
<verification>
- 确认门禁:NOTES 含 `用户确认(10-47):可以执行` + `用户原文:`;Task 5 后含 `用户人工验证(10-47):通过` + `用户原文:`,无 `状态:待处理`。
- 增量门禁:六篇按顺序递增,每篇只在本步加一段;第 22 与第 27 篇的五个组件名一致。
- 内容门禁:6 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性、`GameUI.get`。
- 示例门禁:6 篇全部接 live;6 个 demo 默认导出、无 DOM 属性;最终 demo 含网格 / 详情 / 滚动 / 交互 / 关闭 / 动画。
- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。
- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改前四批已验收内容;未改 `10-01`..`10-46` 计划;未 commit;ROADMAP / STATE 本计划不改。
</verification>
<success_criteria>
- 读者能按六篇顺序把背包 / 装备面板跑起来,并且知道每一步新增了什么。
- 27 篇正文全部在侧边栏就位、无重复、无 dead link;全批交叉核对结论在案。
- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。
</success_criteria>
<output>
Create `.planning/phases/10-docs-restructure/10-47-SUMMARY.md` when done
</output>
## 编号变更(2026-11-01)
本文件写作期提到的「10-49 的用户修订裁决」「10-49 Task 4」与「10-50」,现按下列映射理解(原文保持不变):
- 读者审阅 → `10-53-PLAN.md`(Round 2/3;Round 1 记录保留在 `10-49-READER-REVIEW.md`)。
- 用户修订、最终门禁、全站 live、落位评估与收尾 → `10-54-PLAN.md`。
- 新增的 `10-49`..`10-52` 是 25 篇的 Part 0–1 / 2–3 / 4 / 5 深度扩写(D-93)。
- 旧 `10-49-PLAN.md` / `10-50-PLAN.md` 已被新计划替换;本文件不因编号变更而改正文。
@@ -0,0 +1,131 @@
---
phase: 10-docs-restructure
plan: 47
subsystem: docs
tags:
- docs
- vitepress
- ui
- inventory-example
requires:
- 10-46
provides:
- advanced-ii-ui-part5
- inventory-example-pages
- inventory-demos
affects:
- docs/advanced/ii/ui
- docs/.vitepress/config.ts
tech-stack:
added: []
patterns:
- client-only-live-demo
- progressive-incremental-example
key-files:
created:
- docs/advanced/ii/ui/inventory-example-1-skeleton.md
- docs/advanced/ii/ui/inventory-example-2-grid.md
- docs/advanced/ii/ui/inventory-example-3-detail.md
- docs/advanced/ii/ui/inventory-example-4-scroll.md
- docs/advanced/ii/ui/inventory-example-5-state.md
- docs/advanced/ii/ui/inventory-example-6-animation-and-register.md
- docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx
- docs/.vitepress/components/demos/ui/inventory-2-grid.tsx
- docs/.vitepress/components/demos/ui/inventory-3-detail.tsx
- docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx
- docs/.vitepress/components/demos/ui/inventory-5-state.tsx
- docs/.vitepress/components/demos/ui/inventory-6-full.tsx
modified:
- docs/.vitepress/config.ts
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
decisions:
- 六篇按「上一步 + 一小段增量」推进,配六个独立递增的 live,而不是同一个 demo 改六次。
- 组件拆分从第 22 篇定死为 InventoryPanel / ItemGrid / ItemCell / ItemDetail / ActionBar,第 27 篇只回顾不改结构。
- 面板尺寸 720×480,假数据 10–40 个道具,只用 g-rect / g-rectr / text 绘制。
- 第 25 篇以 Scroll 平铺为主,ListPage 作左列表右详情对比,并给 Scroll / ListPage / Page 判定表。
- 第 27 篇动画在 live 中用 requestAnimationFrame + onUnmounted 取消,不依赖可空的渐变控制器;正文提及 transitioned 时要求判空。
- 文档站缺少 client-base 渲染器时,live 用元素层等价画面,正文代码块保留 TextContent / Scroll / ListPage 的真实写法。
metrics:
duration: ~16m
completed: 2026-10-31
status: complete
human_verification: deferred-to-10-49
actuals:
tokens: 23000
tasks: 5
commits: 0
plan_head_before: b94b4c3b41da8184312bc9f264654dc9a54adf69
---
# Phase 10 Plan 47: 完整示例(背包 / 装备面板) Summary
用六篇递增文档与六个逐级 live,把完整的背包 / 装备面板从骨架写到动画、拆分与注册;侧边栏新增「完整示例」分组,六类门禁全绿。
## What Was Built
- **第 22 篇「示例(一)目标与骨架」**:最终效果、五文件拆分、720×480 骨架、标题与关闭按钮、ItemGrid / ItemDetail 占位、Props 基类与 `GameUI('inventory-panel', InventoryPanel)` 注册、两种打开方式。
- **第 23 篇「示例(二)道具网格」**:`Item` 数据模型与 10 个假道具、`ItemCell` 的 props / emits、`ItemGrid` 的 `.map()` 与行列计算、`selectedId` 提升到父组件、`key` 取舍说明。
- **第 24 篇「示例(三)详情区」**:`computed` 派生选中项、`ItemDetail` 的名称 / 数量 / 描述、`hidden` 优先的未选中提示、`TextContent` 的 `width` 与 `autoHeight`、live 与正文代码块差异说明。
- **第 25 篇「示例(四)滚动与列表」**:`Scroll` 平铺(直接子元素、`padEnd`、`scrollTo` / `getScrollLength`)、`ListPage` 左列表右详情(`basis` / `right` / `close` / slot)、`Scroll` / `ListPage` / `Page` 判定表。
- **第 26 篇「示例(五)交互与状态」**:`ActionBar`、`equippedId`、`ref` / `computed` / `watch`、使用后数量减一、`useKey(...)!` 接 `@common/exit`、`noevent` 遮罩。
- **第 27 篇「示例(六)动画、拆分与注册」**:`requestAnimationFrame` + `onUnmounted` 动画、`transitioned` 可空说明、最终文件结构、`GameUI` 注册与主 UI 栈 / 场景 UI 打开、`keep` 提示、性能自查表、完整面板 live。
- **六个 demo**:从 `inventory-1-skeleton` 到 `inventory-6-full`,每一步只增加上一篇的内容;第 6 个含网格、详情、滚动、装备 / 使用、关闭与动画。
- **侧边栏**:`docs/.vitepress/config.ts` 的「自定义 UI 与渲染」内新增「完整示例」分组 6 条,原有 21 条与高级 III 均保留。
## Verification
| 门禁 | 结果 |
|------|------|
| prettier `--write` / `--check` | exit 0;`All matched files use Prettier code style!` |
| ESLint | 0 error / 0 warning |
| `vue-tsc --noEmit -p docs/tsconfig.json` | `docs/` 路径类型报错 0;既有引擎报错 11 条(非本轮引入) |
| 静态断言 | `STATIC-OK`;27 条侧边栏链接各出现一次、无重复;6 篇单 H1 / 边界节 / CRLF / live;6 个 demo 默认导出、无 DOM 属性、只 import vue |
| `pnpm docs:build` | green,`build complete in 24.63s.`,无 dead link |
| 全批交叉核对 | 27 篇齐全;六个 Part 顺序一致;`hidden`、`v-model:xxx`、第 22/27 拆分、被禁写法六项均通过 |
## Deviations from Plan
### Process / Checkpoint
**1. Task 5(live 人工验证)按调度指令跳过并顺延**
- **Found during:** 执行上下文
- **Issue:** 10-47 末尾的 `checkpoint:human-verify` 要求用户目视 6 个 live;调度指令要求在 10-48 独立读者审阅与 10-49 用户修订前停下。
- **Fix:** 未写「用户人工验证(10-47):通过」,NOTES 记录「live 人工验证(10-47):待最终人工审阅」。Task 5 未执行。
- **Files modified:** `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md`
**2. 正文 / demo 采用内联执行,而非派发子代理**
- **Found during:** Task 1 开始前
- **Issue:** 本执行环境未提供子代理派发工具;计划约定正文 / demo 由子代理执行。
- **Fix:** 按调度器可直接编辑的能力内联落盘,并在执行开始时声明「内联执行」;未调用 `opencode` 命令。
- **Files modified:** 本计划全部产物
**3. 未执行 git add / commit / push / stash / 分支切换**
- **Found during:** 全流程
- **Issue:** 标准执行器流程要求逐任务提交与最终元数据提交;本次调度指令明确不提交。
- **Fix:** 所有改动保留在工作树;SUMMARY 中 `commits: 0`,未改 STATE / ROADMAP。
- **Files modified:** 无
## Known Limitations
- 文档站缺少 `packages-user/client-base/src/renderer`,无法静态 import 内置组件。第 24 / 25 篇 live 用元素层等价画面(`text`、`alpha`、尺寸与滚动窗口)演示,正文代码块保留 `TextContent` / `Scroll` / `ListPage` 的真实写法;两篇正文均已写明「live 与正文代码块不是同一份代码」。这是 10-46 已记录的既有中间态,不是本计划引入的缺陷。
## Threat Flags
None — 六个 demo 只 import `vue` 与本框架元素标签,使用本地假数据,不读写存储、不发请求、不引入新依赖。
## Self-Check: PASSED
- [x] 6 篇正文与 6 个 demo 全部存在
- [x] 侧边栏共 27 条 `/advanced/ii/ui/` 链接,27 个唯一值,无重复
- [x] prettier / ESLint / docs 类型 / 静态断言 / 构建全部通过
- [x] NOTES 含 10-47 确认、参考哈希、门禁记录与全批交叉核对
- [x] 未执行 10-48 / 10-49;未提交 git;未改 `packages/` / `packages-user/` / `src/`
## 编号变更(2026-11-01)
本文件中的 `deferred-to-10-49` 与「10-49 用户修订前停止」是写作期编号;重排后:
- 读者审阅 → `10-53-PLAN.md`(Round 2/3;Round 1 记录保留在 `10-49-READER-REVIEW.md`)。
- 用户修订与收尾 → `10-54-PLAN.md`。
- 新增 `10-49`..`10-52` 为 25 篇的 Part 0–1 / 2–3 / 4 / 5 深度扩写(D-93);`10-48` 仍为 pre-review 修复。
- 本文件的 live 复验仍由 `10-54` Task 4 的全站 live 统一覆盖;历史正文不改写。
@@ -0,0 +1,414 @@
---
phase: 10-docs-restructure
plan: 48
type: execute
wave: 6
depends_on:
- 10-47
files_modified:
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- docs/.vitepress/config.ts
- docs/advanced/ii/index.md
- docs/advanced/index.md
- docs/advanced/ii/ui/ui-template.md
- docs/advanced/ii/ui/container-and-coordinates.md
- docs/advanced/ii/ui/basic-shapes.md
- docs/advanced/ii/ui/curves-and-paths.md
- docs/advanced/ii/ui/text.md
- docs/advanced/ii/ui/image-and-texture.md
- docs/advanced/ii/ui/layer-transform-performance.md
- docs/advanced/ii/ui/reactivity.md
- docs/advanced/ii/ui/events.md
- docs/advanced/ii/ui/hotkey-in-ui.md
- docs/advanced/ii/ui/conditional-and-list-rendering.md
- docs/advanced/ii/ui/props.md
- docs/advanced/ii/ui/component-tsx.md
- docs/advanced/ii/ui/slots-and-attrs.md
- docs/advanced/ii/ui/builtin-text-and-input.md
- docs/advanced/ii/ui/builtin-list-and-containers.md
- docs/advanced/ii/ui/ui-controller-and-stack.md
- docs/advanced/ii/ui/replace-builtin-ui.md
- docs/advanced/ii/ui/ui-performance.md
- docs/advanced/ii/ui/inventory-example-1-skeleton.md
- docs/advanced/ii/ui/inventory-example-2-grid.md
- docs/advanced/ii/ui/inventory-example-3-detail.md
- docs/advanced/ii/ui/inventory-example-4-scroll.md
- docs/advanced/ii/ui/inventory-example-5-state.md
- docs/advanced/ii/ui/inventory-example-6-animation-and-register.md
- docs/advanced/ii/ui/ui-template-ts.md
- docs/advanced/ii/ui/component-ts.md
- docs/.vitepress/components/demos/ui/template-demo.tsx
- docs/.vitepress/components/demos/ui/container-demo.tsx
- docs/.vitepress/components/demos/ui/shapes-demo.tsx
- docs/.vitepress/components/demos/ui/curves-demo.tsx
- docs/.vitepress/components/demos/ui/text-demo.tsx
- docs/.vitepress/components/demos/ui/texture-demo.tsx
- docs/.vitepress/components/demos/ui/layer-demo.tsx
- docs/.vitepress/components/demos/ui/reactivity-demo.tsx
- docs/.vitepress/components/demos/ui/events-demo.tsx
- docs/.vitepress/components/demos/ui/conditional-demo.tsx
- docs/.vitepress/components/demos/ui/props-demo.tsx
- docs/.vitepress/components/demos/ui/component-demo.tsx
- docs/.vitepress/components/demos/ui/slots-demo.tsx
- docs/.vitepress/components/demos/ui/builtin-text-demo.tsx
- docs/.vitepress/components/demos/ui/builtin-list-demo.tsx
- docs/.vitepress/components/demos/ui/controller-demo.tsx
- docs/.vitepress/components/demos/ui/strategy-demo.tsx
- docs/.vitepress/components/demos/ui/perf-demo.tsx
- docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx
- docs/.vitepress/components/demos/ui/inventory-2-grid.tsx
- docs/.vitepress/components/demos/ui/inventory-3-detail.tsx
- docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx
- docs/.vitepress/components/demos/ui/inventory-5-state.tsx
- docs/.vitepress/components/demos/ui/inventory-6-full.tsx
- docs/.vitepress/components/demos/ui/ts-component-demo.tsx
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 96000
raw_tokens: 60000
tasks: 6
confidence: low
must_haves:
truths:
- "删去 2 篇独立 TS 页与 1 个 TS demo 后,`docs/advanced/ii/ui` 恰好 25 篇 Markdown、`docs/.vitepress/components/demos/ui` 恰好 24 个 `.tsx`;侧边栏、两页导览与全批交叉引用同步到 25 条(D-46 / D-78 / D-89 / D-90 不变)"
- "相关页面的 TSX 示例后附有简短 TS 元素层演示(至少覆盖模板、容器、图形、文字、组件 TSX 篇之后、UIController/UI 栈);演示不写 Vue 组件、不写类型标注、不要求运行;不新增独立页面或 demo"
- "全批不出现全局 `client`:所有打开 / 关闭示例从 `props.state` 取 ClientCore(如 `props.state.sceneController.open(...)`);模板与 UIController 篇明确说明没有全局 `client`"
- "25 篇正文的所有代码块与 24 个 demo 都补了有价值注释;注释只新增、不修改既有注释;只新增整行 `//` 或单行 `{/* ... */}` 注释,不改变任何非注释代码"
- "最终门禁:prettier `--write` / `--check` 通过、ESLint 0/0、`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错、`pnpm docs:build` green + `build complete` + 0 dead link、`public/_docs/advanced/ii/ui` 恰好 25 个 HTML"
- "10-48 在修复结束即停止:不进入 10-49 独立读者审阅、不写 SUMMARY / ROADMAP / STATE、不改 `packages*` / `src`、不 commit"
artifacts:
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-48 修复范围、基线、删除清单、25/24 计数、注释代码哈希与门禁)"
- "docs/advanced/ii/ui(25 篇正文,含内联 TS 片段、无全局 client、代码块注释)"
- "docs/.vitepress/components/demos/ui(24 个 demo,含注释)"
- "docs/.vitepress/config.ts、docs/advanced/ii/index.md、docs/advanced/index.md(25 条侧边栏与导览、篇号引用一致)"
key_links:
- "先记基线再删改:修复前 docs / demo 快照哈希与 ROADMAP / STATE 哈希必须在第一次删除之前落盘"
- "删除与内联同步:删掉独立 TS 页后,模板、容器、图形、文字、组件、UIController 六处必须补上简短 TS 片段,否则读者失去元素层入口"
- "客户端取法统一:任何示例写全局 `client` 都会让读者在真实组件里找不到该对象;必须改为 `props.state`"
- "注释只加不改:用整行注释 + 去注释代码哈希证明行为未变;修改既有注释或改代码都会使哈希不一致"
- "修复与审阅分离:10-48 只做三项 pre-review 修复,读者审阅仍由 10-49 独立执行"
---
> **编号变更(2026-11-01):** 本文件中的旧 10-49 / 10-50 分工已重排,完整映射见文末「编号变更」小节。
<scope_justification>
本计划是新增的 pre-review 修复计划,只承担用户在独立审阅前点名的三项修复:
- 三项修复都必须在 10-49 独立读者审阅之前完成,否则读者会读到已被删除的页面、全局 `client` 与无注释示例,审阅结论会混入已知缺陷。
- 6 个任务对应不能合并的顺序:用户关卡 → 删除与计数收口 → `client` 取法统一 → Part 0–1 注释 → Part 2–5 注释 → 门禁与记录。注释任务必须排在删除与 `client` 修复之后,才能对最终文本补注释并证明行为未变。
- 不删减任何已验收内容:除删除 2 篇独立 TS 页与 1 个 TS demo、内联 TS 片段、`client` 取法与注释外,10-43..10-47 的正文语义、示例结构、live 与 demo 行为全部保留。
- 本计划只追加 NOTES、修改 `docs/` 与 `docs/.vitepress/`;不写 SUMMARY、不改 ROADMAP / STATE、不 commit,审阅由 10-49、修订由 10-50 执行。
</scope_justification>
<objective>
在独立读者审阅之前完成三项修复:①删去 `ui-template-ts.md`、`component-ts.md` 与 `ts-component-demo.tsx`,在相关页面内联简短 TS 元素层演示,把全批收口为 25 篇正文 / 24 个 demo;②去掉所有全局 `client`,改为从 `props.state` 取 ClientCore,并在模板与 UIController 篇说明原因;③给 25 篇正文的所有代码块与 24 个 demo 补有价值注释。
Purpose: 独立读者只读文档、不读源码(D-46 / D-89)。如果文档还留着独立 TS 页、全局 `client` 或无注释的长示例,读者会被结构问题与不可运行的写法挡住,无法把问题集中在内容本身。把这三项修复前置成独立计划,才能让 10-49 的审阅结论干净可用。
Output: 修复后的 25 篇正文、24 个 demo、侧边栏与导览,以及 NOTES 中的基线、删除清单、计数、注释代码哈希与门禁记录。**不写 SUMMARY、不改 ROADMAP / STATE、不改源码、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md
@.planning/phases/10-docs-restructure/10-47-PLAN.md
@.planning/phases/10-docs-restructure/10-47-SUMMARY.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
@docs/.vitepress/config.ts
**流程约定:**
- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-47` 计划文件与 POC 文件、不改 `ROADMAP.md` / `STATE.md`、不改 `packages/` / `packages-user/` / `src/`。
- **Task 0 是硬关卡**:汇报修复范围、删除清单、25/24 计数、内联位置、注释规则与门禁,等用户明确回复「可以执行」。
- 改文件前声明「内联执行」还是「派发子代理执行」;本计划所有正文与 demo 写入一律派发子代理执行。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit(D-90)。
- 本计划**不进入审阅**:修复结束即停止;独立读者审阅由 10-49 执行,用户修订与收尾由 10-50 执行。
- 参考哈希基线保持不动:`10-CUSTOM-UI-NOTES.md` 的 `## 参考清单哈希基线` 与各批复核表是写作期记录,不得改写。
- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。
**本批事实:**
- 10-43..10-47 已执行,当前工作区为 27 篇正文与 25 个 demo;本计划执行后应为 25 篇正文与 24 个 demo。
- 侧边栏在 `docs/.vitepress/config.ts` 的高级 II 分组内,两层嵌套:子分组 → 6 个 Part → 篇目。
- 两页导览:`docs/advanced/ii/index.md`(本层包含什么、阅读路径)与 `docs/advanced/index.md`(三层结构、边界)。
- 25 篇正文的 Part 划分:Part 0 起步 1 篇;Part 1 元素与布局 6 篇;Part 2 交互与数据 4 篇;Part 3 组件化 3 篇;Part 4 内置组件与 UI 系统 5 篇;Part 5 完整示例 6 篇。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报三项修复范围、删除清单、25/24 计数、内联位置、注释规则与门禁,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CONTEXT.md(D-46 / D-78 / D-89 / D-90)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、六 Part 顺序与前五批门禁)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md(UI 子分组范围)、.planning/phases/10-docs-restructure/10-47-PLAN.md 与 10-47-SUMMARY.md、docs/advanced/ii/index.md、docs/advanced/index.md、docs/.vitepress/config.ts、docs/advanced/ii/ui/ui-template.md、docs/advanced/ii/ui/ui-template-ts.md、docs/advanced/ii/ui/component-ts.md、docs/advanced/ii/ui/component-tsx.md、docs/advanced/ii/ui/ui-controller-and-stack.md</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——只做三项 pre-review 修复:①删去 `docs/advanced/ii/ui/ui-template-ts.md`、`docs/advanced/ii/ui/component-ts.md` 与 `docs/.vitepress/components/demos/ui/ts-component-demo.tsx`,从侧边栏与两页导览删去对应 2 条与链接,并在模板、容器、图形、文字、组件 TSX 篇、UIController/UI 栈六处内联简短 TS 元素层演示;全批收口为 25 篇正文 / 24 个 demo。②去掉全局 `client`,所有示例改为从 `props.state` 取 ClientCore,并在模板与 UIController 篇说明「没有全局 client」。③给 25 篇正文的所有代码块与 24 个 demo 补有价值注释。**本计划不进入读者审阅、不写 SUMMARY / ROADMAP / STATE、不改源码、不 commit。**
**为什么**——独立读者只读文档、不读源码;独立 TS 页会让 Part 0 / Part 3 的入口分裂,全局 `client` 在真实组件里不存在,无注释的长示例会让读者无法判断关键行。三项修复必须在 10-49 审阅前完成,审阅结论才不会被结构问题污染。
**大致怎么做**——Task 1 先写 NOTES 基线(修复前 docs / demo 快照、ROADMAP / STATE 哈希、基线 HEAD),再删除 2 页与 1 个 demo、删侧边栏与导览链接、补六处内联 TS 片段、把篇号引用按删除后的顺序重排;Task 2 全批替换 `client.` 为 `props.state.` 并改模板 / controller 文案;Task 3 给 Part 0–1 的 7 篇与 7 个 demo 补注释并记录去注释代码哈希;Task 4 给 Part 2–5 的 18 篇与 17 个 demo 补注释并记录哈希;Task 5 跑 prettier / ESLint / docs 类型 / 构建 / 25 个 HTML / 静态断言,写入 NOTES 后停止。
**影响范围**——删除 3 个文件;修改 `docs/advanced/ii/ui/` 下 25 篇正文、`docs/.vitepress/components/demos/ui/` 下 24 个 demo、`docs/.vitepress/config.ts`、`docs/advanced/ii/index.md`、`docs/advanced/index.md`;只追加 `10-CUSTOM-UI-NOTES.md`。不动 `packages/`、`packages-user/`、`src/`、`10-01`..`10-47` 计划文件、POC 文件、`ROADMAP.md`、`STATE.md`、任何既有 JSDoc / 注释。
**请用户确认:**
1. **删除范围**:只删 `ui-template-ts.md`、`component-ts.md`、`ts-component-demo.tsx`;不删其它页面或 demo。
2. **内联范围**:只在 `ui-template.md`、`container-and-coordinates.md`、`basic-shapes.md`、`text.md`、`component-tsx.md`、`ui-controller-and-stack.md` 六处的 TSX 示例后追加简短 `ts` 片段;不新增独立页面 / demo,不要求运行。
3. **client 取法**:全批示例不出现全局 `client`;`client.sceneController.open(...)` 改为 `props.state.sceneController.open(...)`;模板与 UIController 篇写明「没有全局 client,UI 组件通过传入的 `props.state` 拿到 ClientCore」。
4. **注释规则**:只新增整行 `//` 或单行 `{/* ... */}` 注释,不修改既有注释;注释说明目的、关键步骤、关键属性 / 参数 / 生命周期;禁止「// 设置属性」这类无信息注释;不改变任何非注释代码。
5. **计数与门禁**:25 篇正文 / 24 个 demo / 25 个 HTML;prettier、ESLint 0/0、`docs/` 路径 0 类型错误、`pnpm docs:build` green、0 dead link。
6. **停止条件**:修复结束即停止,不进入 10-49 审阅;不写 SUMMARY / ROADMAP / STATE;不改导览以外内容;不 commit。
7. 本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释。
**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报三项修复范围、删除清单、计数、内联位置、注释规则与门禁。</what-built>
<how-to-verify>确认:①只删 2 页 1 demo;②只补六处内联 TS;③全批无全局 client;④注释只加不改、无无信息注释;⑤25/24/25 计数与门禁;⑥修复结束即停止、不写 SUMMARY / ROADMAP / STATE、不 commit;⑦派发子代理。</how-to-verify>
<resume-signal>回复「可以执行」以继续;其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且删除范围、内联位置、client 取法、注释规则、计数与门禁、停止条件六项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,三项修复的范围、删除清单、内联位置、注释规则、计数门禁与停止条件均已确认。</human-check>
</verify>
<done>用户回复「可以执行」且待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 基线快照 + 删除 2 页 1 demo + 侧边栏 / 导览 / 篇号收口 + 六处内联 TS</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md, docs/advanced/ii/ui/ui-template-ts.md, docs/advanced/ii/ui/component-ts.md, docs/.vitepress/components/demos/ui/ts-component-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/index.md, docs/advanced/index.md, docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/component-tsx.md, docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/advanced/ii/ui/ui-performance.md, docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md</files>
<precondition>`10-CUSTOM-UI-NOTES.md` 含 `用户确认(10-47):可以执行`;`10-47-SUMMARY.md` 存在;用户已在 Task 0 回复「可以执行」;`docs/advanced/ii/ui` 下当前 27 篇 `.md`、demos 下当前 25 个 `.tsx`。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、六 Part 顺序、参考哈希基线)、.planning/ROADMAP.md(Phase 10 的 `**Plans:**` 行与受保护行)、.planning/STATE.md(frontmatter)、docs/advanced/ii/index.md、docs/advanced/index.md、docs/.vitepress/config.ts、docs/advanced/ii/ui/ui-template.md、docs/advanced/ii/ui/container-and-coordinates.md、docs/advanced/ii/ui/basic-shapes.md、docs/advanced/ii/ui/text.md、docs/advanced/ii/ui/component-tsx.md、docs/advanced/ii/ui/ui-controller-and-stack.md</read_first>
<action>**先写基线,再删除;哈希必须早于第一次删除。**
**(1)向 NOTES 末尾追加 `## 10-48 pre-review 修复` 小节**,依次写入以下固定行(各独占一行,后续任务与 verify 按字面量断言):
1. `修复范围:` + `①删去 2 篇独立 TS 页与 1 个 TS demo 并内联 TS 片段;②去掉全局 client、改用 props.state;③给 25 篇正文代码块与 24 个 demo 补注释。`
2. `删除清单:` + `docs/advanced/ii/ui/ui-template-ts.md、docs/advanced/ii/ui/component-ts.md、docs/.vitepress/components/demos/ui/ts-component-demo.tsx`。
3. `基线 HEAD(10-48 记录):` + `git rev-parse HEAD` 的完整 sha。
4. `修复前 docs 快照哈希:` + 对 `docs/advanced/ii/ui` 下全部 `.md`(当前 27 篇)+ `docs/advanced/ii/index.md` + `docs/advanced/index.md` 取哈希:按完整路径排序、逐个 `git hash-object -- <path>`、用 `,` 拼接后取 SHA-256(小写 hex,64 位)。参考命令与 10-49 Task 1 相同。
5. `修复前 demo 快照哈希:` + 对 `docs/.vitepress/components/demos/ui` 下全部 `.tsx`(当前 25 个)取哈希:按完整路径排序、逐个 `git hash-object -- <path>`、用 `,` 拼接后取 SHA-256(小写 hex,64 位)。参考命令:`$demo = Get-ChildItem -Recurse -File -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx; $files = @($demo) | Sort-Object FullName; $joined = ($files | ForEach-Object { (git hash-object -- $_.FullName) }) -join ','; $sha = [BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($joined))).Replace('-','').ToLower()`。
6. `ROADMAP 受保护行哈希:` + 对 ROADMAP 受保护行取 SHA-256(匹配 `^\s*-\s\[[ x]\]\s+10-(06|11|12)-PLAN\.md` 的三行,以及 `^\*\*10-42 增量说明:` 开头的一行;64 位小写 hex)。
7. `ROADMAP 全文哈希:` + 对 `.planning/ROADMAP.md` 全文 UTF-8 字节取 SHA-256(64 位小写 hex)。
8. `STATE 全文哈希:` + 对 `.planning/STATE.md` 全文 UTF-8 字节取 SHA-256(64 位小写 hex)。
**(2)删除文件**:删除 `docs/advanced/ii/ui/ui-template-ts.md`、`docs/advanced/ii/ui/component-ts.md`、`docs/.vitepress/components/demos/ui/ts-component-demo.tsx`。不得删除 `template-demo.tsx`(`ui-template.md` 仍在使用)。
**(3)侧边栏**:从 `docs/.vitepress/config.ts` 删除两个条目——`同一 UI 的 TS 元素层写法`(`/advanced/ii/ui/ui-template-ts`)与 `组件(TS 直调)`(`/advanced/ii/ui/component-ts`)。只删这两个条目,不改 6 个 Part 的标题与顺序,不删其它条目。
**(4)两页导览**:
- `docs/advanced/ii/index.md`:把「另有『自定义 UI 与渲染』子分组 27 篇」改为「25 篇」;把入口句改为只从 [UI 通用模板](./ui/ui-template.md) 开始,删去 `[同一 UI 的 TS 元素层写法](./ui/ui-template-ts.md)` 链接与「与」连接;把「第 21 篇」改为「第 19 篇」。
- `docs/advanced/index.md`:把「第 21 篇」改为「第 19 篇」。该页没有 TS 页链接;若发现 `ui-template-ts` / `component-ts` 字样一并删除。
**(5)删除跨页链接**:`docs/advanced/ii/ui/container-and-coordinates.md` 末尾的「完整写法见[同一 UI 的 TS 元素层写法](./ui-template-ts.md)」改为「元素层的 `appendChild` 与 `removeChild` 可以在运行时增删子元素;日常布局仍然优先用 TSX 描述结构。」不得保留指向已删除页面的链接。
**(6)按删除后的顺序重排篇号引用**(删除 2 篇后 old→new 映射:3→2、4→3、5→4、6→5、7→6、8→7、9→8、10→9、11→10、12→11、13→12、14→13、16→14、17→15、18→16、19→17、20→18、21→19、22→20、23→21、24→22、25→23、26→24、27→25)。按下表逐条改,**不得全局替换数字**(22→20 与 20→18 会互相覆盖):
- `basic-shapes.md`:`第 10 篇「事件与交互」` → `第 9 篇「事件与交互」`。
- `container-and-coordinates.md`:`第 8 篇「层级、变换与性能」` → `第 7 篇「层级、变换与性能」`。
- `events.md`:`第 4 篇「基础图形」` → `第 3 篇「基础图形」`。
- `inventory-example-1-skeleton.md`:`第 19 篇「UIController 与 UI 栈」` → `第 17 篇「UIController 与 UI 栈」`。
- `inventory-example-2-grid.md`:`第 13 篇「props」` → `第 12 篇「props」`。
- `inventory-example-6-animation-and-register.md`:`第 22 篇的结构` → `第 20 篇的结构`;`第 22 篇完全一致` → `第 20 篇完全一致`;`第 20 篇「修改 / 替换内置 UI」` → `第 18 篇「修改 / 替换内置 UI」`;`第 19 篇「UIController 与 UI 栈」` → `第 17 篇「UIController 与 UI 栈」`;`按第 21 篇的清单` → `按第 19 篇的清单`。
- `layer-transform-performance.md`:`第 12 篇「条件渲染与循环渲染」` → `第 11 篇「条件渲染与循环渲染」`;`第 7 篇「图片与最小纹理」` → `第 6 篇「图片与最小纹理」`。
- `reactivity.md`:`第 13 篇「props」` → `第 12 篇「props」`(按该页实际标题文字匹配)。
- `slots-and-attrs.md`:`第 17 篇「内置组件:文本与输入」` → `第 15 篇「内置组件:文本与输入」`。
- `text.md`:`第 17 篇「内置组件:文本与输入」` → `第 15 篇「内置组件:文本与输入」`。
- `ui-performance.md`:`第 8 篇「层级、变换与性能」` → `第 7 篇「层级、变换与性能」`;`第 12 篇「条件渲染与循环渲染」` → `第 11 篇「条件渲染与循环渲染」`;`第 7 篇「图片与最小纹理」` → `第 6 篇「图片与最小纹理」`。
**(7)六处内联 TS 元素层演示**(只加 `ts` 代码块,不写 Vue 组件、不写类型标注、不要求运行;每段不超过 20 行;先写简短注释,Task 3 再补足):
- `ui-template.md`:在第一个 TSX 模板代码块之后、「代码里只有三个元素」之前,加一段:`new Container()` 设 `loc(0, 0, 480, 320)`,`new Rect()` 设 `pos` / `size` / `setFillStyle`,`new Text()` 设 `pos` / `setText` / `setStyle`,最后 `appendChild(rect, text)`。
- `container-and-coordinates.md`:在「一个嵌套示例」的 TSX 代码块之后,加一段:创建根容器与子容器,用 `pos` / `size` 设几何,用 `appendChild` 挂子容器与矩形,说明子元素坐标相对父容器。
- `basic-shapes.md`:在「四个图形」一节的 TSX 示例之后,加一段:`new Rect()`、`new Circle()`、`new Ellipse()`、`new Line()` 各设几何与填充 / 描边;类名以该页已用元素对应的元素层类为准。
- `text.md`:在「一行文字」的 TSX 代码块之后,加一段:`new Text()` 设 `pos`、`setText`、`setStyle`、`setFont(new Font(...))`。
- `component-tsx.md`:在「一个完整组件的结构」的 TSX 代码块之后、「各段职责固定」之前,加一段:不用 `defineComponent`,直接用 `Container`、`Rect`、`Text` 搭出与 `ItemCell` 相同的画面,并用 `appendChild` 组合。
- `ui-controller-and-stack.md`:在「场景 UI 与主 UI」的表格之后,加一段:`props.state.sceneController.open(TitleUI, {})`、`props.state.mainUIController.open(InventoryUI, {})`、`props.state.mainUIController.close(instance)`;注释说明两个控制器都来自 `props.state`,没有全局 `client`。
**(8)本任务只做上述删改与内联,不补全量注释、不改 `client` 的其它出现(Task 2 处理)、不改 ROADMAP / STATE、不写 SUMMARY、不 commit。** 完成后在 NOTES 的 `## 10-48 pre-review 修复` 下追加 `删除完成:3 个文件` 与 `页面计数(删除后):25`、`demo 计数(删除后):24`。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); foreach($k in @('## 10-48 pre-review 修复','修复范围:','删除清单:','基线 HEAD(10-48 记录):','修复前 docs 快照哈希:','修复前 demo 快照哈希:','ROADMAP 受保护行哈希:','ROADMAP 全文哈希:','STATE 全文哈希:','删除完成:3 个文件','页面计数(删除后):25','demo 计数(删除后):24')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-48 记录):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('修复前 docs 快照哈希','修复前 demo 快照哈希','ROADMAP 受保护行哈希','ROADMAP 全文哈希','STATE 全文哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; foreach($d in @('docs/advanced/ii/ui/ui-template-ts.md','docs/advanced/ii/ui/component-ts.md','docs/.vitepress/components/demos/ui/ts-component-demo.tsx')){ if(Test-Path -LiteralPath $d){ Write-Error "NOT-DELETED $d" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:' + $md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:' + $demo.Count) }; $cfg=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); $cfgLinks=([regex]::Matches($cfg,'/advanced/ii/ui/[a-z0-9-]+')).Count; if($cfgLinks -ne 25){ Write-Error ('CFG-COUNT:' + $cfgLinks) }; if($cfg -match 'ui-template-ts|/advanced/ii/ui/component-ts[\x27\x22]'){ Write-Error 'CFG-STILL-TS' }; $idx=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); if($idx -match 'ui-template-ts|27 篇'){ Write-Error 'INDEX-STILL-OLD' }; if($idx.IndexOf('25 篇') -lt 0){ Write-Error 'INDEX-NO-25' }; $top=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/index.md')); if($top -match 'ui-template-ts|component-ts'){ Write-Error 'TOP-STILL-TS' }; $all=Get-ChildItem docs -Recurse -File -Include *.md,*.ts | Select-String -Pattern 'ui-template-ts|component-ts\.md|/advanced/ii/ui/component-ts(?!x)' ; if($all){ $all | ForEach-Object { Write-Output $_.Path }; Write-Error 'STILL-REFERENCE-DELETED' }; $cc=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/ui/container-and-coordinates.md')); if($cc -match 'ui-template-ts'){ Write-Error 'CONTAINER-STILL-LINK' }; foreach($pair in @(@('docs/advanced/ii/ui/basic-shapes.md','第 10 篇「事件与交互」','第 9 篇「事件与交互」'),@('docs/advanced/ii/ui/container-and-coordinates.md','第 8 篇「层级、变换与性能」','第 7 篇「层级、变换与性能」'),@('docs/advanced/ii/ui/events.md','第 4 篇「基础图形」','第 3 篇「基础图形」'),@('docs/advanced/ii/ui/inventory-example-1-skeleton.md','第 19 篇「UIController 与 UI 栈」','第 17 篇「UIController 与 UI 栈」'),@('docs/advanced/ii/ui/inventory-example-2-grid.md','第 13 篇「props」','第 12 篇「props」'),@('docs/advanced/ii/ui/layer-transform-performance.md','第 12 篇「条件渲染与循环渲染」','第 11 篇「条件渲染与循环渲染」'),@('docs/advanced/ii/ui/slots-and-attrs.md','第 17 篇「内置组件:文本与输入」','第 15 篇「内置组件:文本与输入」'),@('docs/advanced/ii/ui/text.md','第 17 篇「内置组件:文本与输入」','第 15 篇「内置组件:文本与输入」'),@('docs/advanced/ii/ui/ui-performance.md','第 8 篇「层级、变换与性能」','第 7 篇「层级、变换与性能」')){ $p=$pair[0]; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t.IndexOf($pair[1]) -ge 0){ Write-Error ("OLD-REF:" + $p + ":" + $pair[1]) }; if($t.IndexOf($pair[2]) -lt 0){ Write-Error ("NEW-REF-MISSING:" + $p + ":" + $pair[2]) } }; foreach($p in @('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/ui-controller-and-stack.md')){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -notmatch '(?m)^```ts\s*$'){ Write-Error ("NO-INLINE-TS:" + $p) } }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NOT-DELETED", "MD-COUNT", "DEMO-COUNT", "CFG-COUNT", "CFG-STILL-TS", "INDEX-STILL-OLD", "INDEX-NO-25", "TOP-STILL-TS", "STILL-REFERENCE-DELETED", "CONTAINER-STILL-LINK", "OLD-REF", "NEW-REF-MISSING", "NO-INLINE-TS"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 的 `## 10-48 pre-review 修复` 含基线八行(修复范围、删除清单、基线 HEAD、修复前 docs 快照、修复前 demo 快照、ROADMAP 受保护行、ROADMAP 全文、STATE 全文)与 `删除完成:3 个文件`、`页面计数(删除后):25`、`demo 计数(删除后):24`;3 个文件已删除;`docs/advanced/ii/ui` 恰好 25 篇、demos 恰好 24 个;配置 25 条 UI 链接且无 TS 页条目;两页导览无 TS 页链接、`ii/index` 为 25 篇;六处已加 `ts` 内联片段;篇号引用按映射更新;未改 ROADMAP / STATE。</acceptance_criteria>
<done>删除、侧边栏 / 导览 / 篇号收口与六处内联 TS 完成,基线已落盘。</done>
</task>
<task type="auto">
<name>Task 2: 去掉全局 client,全批改为 props.state,并补模板 / UIController 文案</name>
<files>docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/advanced/ii/ui/hotkey-in-ui.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/component-tsx.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/advanced/ii/ui/ui-performance.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md</files>
<precondition>Task 1 已删除 2 页 1 demo 并完成计数收口;当前 25 篇正文已落盘。</precondition>
<read_first>docs/advanced/ii/ui/ui-template.md(打开与关闭一节)、docs/advanced/ii/ui/ui-controller-and-stack.md(场景 UI 与主 UI 表)、docs/advanced/ii/ui/inventory-example-1-skeleton.md(打开处)、packages-user/client-base/src/types.ts(`IGameUIPropsBase.state` 与 `IClientBase.sceneController` / `mainUIController`,只读确认 `props.state` 可用)</read_first>
<action>**先全批扫描,再逐处替换;不得保留全局 `client`。**
1. 用 `Get-ChildItem docs/advanced/ii/ui -Filter *.md | Select-String -Pattern '(?<![\w-])client\.'` 扫描 25 篇,列出全部命中。已知至少三处:`ui-template.md` 的 `client.sceneController.open(MyPanelUI, {})`、`ui-controller-and-stack.md` 表格里的 `client.sceneController.open(...)`、`inventory-example-1-skeleton.md` 的 `client.sceneController.open(InventoryUI, {})`;若扫描出更多,一并处理。
2. 全部改为从 `props.state` 取 ClientCore:`client.sceneController.open(...)` → `props.state.sceneController.open(...)`;`client.mainUIController.open(...)` → `props.state.mainUIController.open(...)`;其它 `client.` 同理改为 `props.state.` 上的同名成员。不得写成新的局部 `client` 变量,也不得保留全局对象。
3. `ui-template.md`:把「打开与关闭」的三个示例统一到组件内视角——主入口示例写 `props.state.sceneController.open(MyPanelUI, {})`;在说明段明确「没有全局 `client`;UI 组件通过传入的 `props.state` 拿到 ClientCore;`props.state` 来自 `IGameUIPropsBase`,所以 `props` 列表必须包含 `state`;不要在文档示例里使用全局对象」。若必须说明主入口,写成「在主入口你持有的客户端核心实例上调用」,不给出全局变量名。
4. `ui-controller-and-stack.md`:把表格 `client.sceneController.open(...)` 改为 `props.state.sceneController.open(...)`;在「场景 UI 与主 UI」小节加一句「两个控制器都从 `props.state` 取,没有全局 `client`;`props.state` 是运行时注入的 ClientCore,`sceneController` 与 `mainUIController` 都在它上面」。
5. `inventory-example-1-skeleton.md`:把 `client.sceneController.open(InventoryUI, {})` 改为 `props.state.sceneController.open(InventoryUI, {})`;保留其后的 `props.state.mainUIController.open(...)` 推荐写法。
6. 不得把 `@user/client-base` 包名当成全局 `client` 删掉;只处理 `client.` 成员访问。
7. 本任务只改上述取法与文案,不补注释(Task 3 / 4 处理),不改行为、不改 ROADMAP / STATE、不 commit。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $hits=@(Get-ChildItem docs/advanced/ii/ui -Filter *.md -File | Select-String -Pattern '(?<![\w-])client\.'); if($hits.Count -gt 0){ $hits | ForEach-Object { Write-Output ("$($_.Path):$($_.LineNumber):$($_.Line)") }; Write-Error 'GLOBAL-CLIENT-REMAINS' }; foreach($p in @('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/ui-controller-and-stack.md','docs/advanced/ii/ui/inventory-example-1-skeleton.md')){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t.IndexOf('props.state.sceneController') -lt 0){ Write-Error ("NO-PROPS-STATE:" + $p) } }; $tpl=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/ui/ui-template.md')); if($tpl.IndexOf('没有全局') -lt 0 -or $tpl.IndexOf('props.state') -lt 0){ Write-Error 'TPL-NO-GLOBAL-NOTE' }; $ctl=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/ui/ui-controller-and-stack.md')); if($ctl.IndexOf('没有全局') -lt 0 -or $ctl.IndexOf('props.state.sceneController.open') -lt 0){ Write-Error 'CTL-NO-GLOBAL-NOTE' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "GLOBAL-CLIENT-REMAINS", "NO-PROPS-STATE", "TPL-NO-GLOBAL-NOTE", "CTL-NO-GLOBAL-NOTE"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>25 篇正文无 `client.` 成员访问(`@user/client-base` 包名除外);`ui-template.md`、`ui-controller-and-stack.md`、`inventory-example-1-skeleton.md` 含 `props.state.sceneController`;模板与 controller 篇含「没有全局」说明与 `props.state` 取法;未引入新的局部 `client` 变量;未改 ROADMAP / STATE。</acceptance_criteria>
<done>全批去掉全局 client,模板与 UIController 篇文案已说明 props.state 取法。</done>
</task>
<task type="auto">
<name>Task 3: Part 0–1 的 7 篇正文与 7 个 demo 补注释(只加注释)</name>
<files>docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/.vitepress/components/demos/ui/template-demo.tsx, docs/.vitepress/components/demos/ui/container-demo.tsx, docs/.vitepress/components/demos/ui/shapes-demo.tsx, docs/.vitepress/components/demos/ui/curves-demo.tsx, docs/.vitepress/components/demos/ui/text-demo.tsx, docs/.vitepress/components/demos/ui/texture-demo.tsx, docs/.vitepress/components/demos/ui/layer-demo.tsx, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1 与 Task 2 已完成(25 篇收口、`client` 已替换、六处内联 TS 已加);本任务开始前未补过注释。</precondition>
<read_first>dev.md(注释规范:`// ` 空格、只写有价值注释、不得修改既有注释、CRLF)、docs/advanced/ii/ui/ui-template.md、docs/advanced/ii/ui/container-and-coordinates.md、docs/advanced/ii/ui/basic-shapes.md、docs/advanced/ii/ui/curves-and-paths.md、docs/advanced/ii/ui/text.md、docs/advanced/ii/ui/image-and-texture.md、docs/advanced/ii/ui/layer-transform-performance.md、对应 7 个 demo</read_first>
<action>**先记录去注释代码哈希,再只加整行注释。**
**(1)记录基线**:先对 7 篇正文与 7 个 demo 跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`,让基线处于格式化状态;再按以下算法计算聚合哈希并写入 NOTES 的 `## 10-48 pre-review 修复` 下:
- 单文件代码内容 = 文件文本删除所有匹配 `^\s*//.*$` 的行与匹配 `^\s*\{/\*.*\*/\}\s*$` 的行(只删整行注释;不动行内代码)。
- 单文件哈希 = 对代码内容的 UTF-8 字节取 SHA-256(小写 hex)。
- 聚合哈希 = 对「按完整路径排序后的 `path:单文件哈希` 用换行拼接」取 SHA-256(小写 hex,64 位)。
- 写入独占一行 `Part 0-1 注释前代码哈希:<64 位 hex>`。
**(2)补注释**(只新增整行 `//` 或单行 `{/* ... */}`,不得写行尾注释、不得改既有注释、不得改任何非注释代码):
- 每段代码块至少一条注释;超过 15 行的代码块至少 3 条,按逻辑段说明「这段在做什么、为什么这样做、关键属性 / 参数从哪里来」。
- 注释必须有信息量:说明目的、关键步骤、关键属性 / 参数 / 生命周期;禁止「// 设置属性」「// 定义变量」「// 循环」这类复述代码的注释(`dev.md` 注释规范)。
- 正文页面重点:`ui-template.md` 说明 Props 基类 / props 列表 / GameUI 注册 / 内联 TS 的等价关系;`container-and-coordinates.md` 说明原点、父容器相对坐标、锚点与 `appendChild`;`basic-shapes.md` 说明四个图形的几何参数、`fill` / `stroke` 是模式开关、`actionStroke` 只改命中;`curves-and-paths.md` 说明控制点与路径构造;`text.md` 说明字体构造、锚点居中、不会自动换行;`image-and-texture.md` 说明纹理创建时机与释放;`layer-transform-performance.md` 说明 `zIndex`、变换与缓存边界。
- demo 重点:文件头说明这个 live 演示什么;`ref` / `computed` / `onMounted` / `onUnmounted` 处说明生命周期与清理;事件处理处说明触发条件;纹理 / 定时器 / 监听必须有对应释放注释。
- 对已经存在的注释逐字保留;需要补充时在相邻位置新增,不改原文。
**(3)复核**:再跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`,然后按同一算法计算聚合哈希,写入独占一行 `Part 0-1 注释后代码哈希:<64 位 hex>`;该值必须与 `Part 0-1 注释前代码哈希:` 完全相同。若不同,说明改到了非注释代码或 prettier 重排了代码,必须回退该处再重算,不得只改哈希值。
**(4)本任务不跑构建、不改 ROADMAP / STATE、不写 SUMMARY、不 commit。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $m1=[regex]::Match($np,'(?m)^Part 0-1 注释前代码哈希:([0-9a-f]{64})'); $m2=[regex]::Match($np,'(?m)^Part 0-1 注释后代码哈希:([0-9a-f]{64})'); if(-not $m1.Success -or -not $m2.Success){ Write-Error 'NO-PART01-HASH' }; if($m1.Groups[1].Value -ne $m2.Groups[1].Value){ Write-Error 'PART01-CODE-CHANGED' }; $pages=@('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); $demos=@('template-demo','container-demo','shapes-demo','curves-demo','text-demo','texture-demo','layer-demo'); $js='const fs=require("fs");const pages=' + ($pages | ConvertTo-Json -Compress) + ';const demos=' + ($demos | ConvertTo-Json -Compress) + ';const bad=[];const isC=l=>/^\s*\/\//.test(l)||/^\s*\{\/\*.*\*\/\}\s*$/.test(l);pages.forEach(f=>{const s=fs.readFileSync(f,"utf8");const re=/```[^\n]*\r?\n([\s\S]*?)```/g;let m;let i=0;while((m=re.exec(s))){i++;const lines=m[1].split(/\r?\n/);const code=lines.filter(l=>l.trim()!=="");const cs=code.filter(isC).length;if(cs<1)bad.push("BLOCK-NO-COMMENT:"+f+":"+i);if(code.length>15&&cs<3)bad.push("BLOCK-FEW-COMMENTS:"+f+":"+i);}});demos.forEach(d=>{const f="docs/.vitepress/components/demos/ui/"+d+".tsx";const lines=fs.readFileSync(f,"utf8").split(/\r?\n/);const cs=lines.filter(isC).length;const need=lines.length>200?6:(lines.length>80?4:2);if(cs<need)bad.push("DEMO-FEW-COMMENTS:"+d+":"+cs+"<"+need);});if(bad.length){console.error(bad.join("|"));process.exit(1)}console.log("COMMENTS-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'COMMENT-ASSERT-FAIL' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-PART01-HASH", "PART01-CODE-CHANGED", "BLOCK-NO-COMMENT", "BLOCK-FEW-COMMENTS", "DEMO-FEW-COMMENTS", "COMMENT-ASSERT-FAIL"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>Part 0–1 的 7 篇正文每个代码块至少一条有价值注释、超 15 行的块至少 3 条;7 个 demo 按长度至少有 2 / 4 / 6 条注释;NOTES 有 `Part 0-1 注释前代码哈希` 与 `Part 0-1 注释后代码哈希` 且两者相同;既有注释逐字未改;未改任何非注释代码;CRLF 与 prettier 后续可过。</acceptance_criteria>
<done>Part 0–1 的 7 篇正文与 7 个 demo 注释补齐,代码哈希未变。</done>
</task>
<task type="auto">
<name>Task 4: Part 2–5 的 18 篇正文与 17 个 demo 补注释(只加注释)</name>
<files>docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/advanced/ii/ui/hotkey-in-ui.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/component-tsx.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/advanced/ii/ui/ui-performance.md, docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md, docs/.vitepress/components/demos/ui/reactivity-demo.tsx, docs/.vitepress/components/demos/ui/events-demo.tsx, docs/.vitepress/components/demos/ui/conditional-demo.tsx, docs/.vitepress/components/demos/ui/props-demo.tsx, docs/.vitepress/components/demos/ui/component-demo.tsx, docs/.vitepress/components/demos/ui/slots-demo.tsx, docs/.vitepress/components/demos/ui/builtin-text-demo.tsx, docs/.vitepress/components/demos/ui/builtin-list-demo.tsx, docs/.vitepress/components/demos/ui/controller-demo.tsx, docs/.vitepress/components/demos/ui/strategy-demo.tsx, docs/.vitepress/components/demos/ui/perf-demo.tsx, docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx, docs/.vitepress/components/demos/ui/inventory-2-grid.tsx, docs/.vitepress/components/demos/ui/inventory-3-detail.tsx, docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx, docs/.vitepress/components/demos/ui/inventory-5-state.tsx, docs/.vitepress/components/demos/ui/inventory-6-full.tsx, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 已完成并写入 `Part 0-1 注释后代码哈希`;任务开始前 Part 2–5 未补过注释。</precondition>
<read_first>dev.md(注释规范)、docs/advanced/ii/ui/reactivity.md、docs/advanced/ii/ui/events.md、docs/advanced/ii/ui/hotkey-in-ui.md、docs/advanced/ii/ui/conditional-and-list-rendering.md、docs/advanced/ii/ui/props.md、docs/advanced/ii/ui/component-tsx.md、docs/advanced/ii/ui/slots-and-attrs.md、docs/advanced/ii/ui/builtin-text-and-input.md、docs/advanced/ii/ui/builtin-list-and-containers.md、docs/advanced/ii/ui/ui-controller-and-stack.md、docs/advanced/ii/ui/replace-builtin-ui.md、docs/advanced/ii/ui/ui-performance.md、六个 inventory 示例页与对应 17 个 demo</read_first>
<action>**先记录去注释代码哈希,再只加整行注释。**
**(1)记录基线**:先对 18 篇正文与 17 个 demo 跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`;再使用与 Task 3 完全相同的算法(删除整行 `//` 与单行 `{/* ... */}` 注释后计算单文件 SHA-256,再对排序后的 `path:hash` 取聚合 SHA-256),写入独占一行 `Part 2-5 注释前代码哈希:<64 位 hex>`。
**(2)补注释**(规则与 Task 3 相同:只新增整行 `//` 或单行 `{/* ... */}`;不改既有注释;不改非注释代码;禁止无信息注释):
- `reactivity.md`:说明哪些值需要 `ref` / `computed`、何时触发重渲染、为什么不要在渲染函数里做重活。
- `events.md`:说明事件绑定位置、参数来源、命中与 `actionStroke` 的关系、阻止冒泡 / 清理监听的边界。
- `hotkey-in-ui.md`:说明 `useKey` 取到的按键系统、分组注册与注销的时机。
- `conditional-and-list-rendering.md`:说明 `v-if` / `v-for` 在本框架中的等价写法、列表 key 的使用边界(`dev.md`:仅重排 / 插入 / 删除且需要保留身份时用)。
- `props.md`:说明 Props 接口、`SetupComponentOptions`、默认值与响应式读取。
- `component-tsx.md`:说明六段结构、`computed`、`emit` / `expose` 与生命周期;内联 TS 片段说明与 TSX 的等价关系。
- `slots-and-attrs.md`:说明透传内容与属性的边界、什么时候需要插槽。
- `builtin-text-and-input.md`、`builtin-list-and-containers.md`:说明内置组件的 props、暴露方法、数据来源与容器组合方式。
- `ui-controller-and-stack.md`:说明四层模型、`open` / `close` / `hide` / `show`、显示策略、背景 `keep`、两个控制器都来自 `props.state`。
- `replace-builtin-ui.md`:说明替换发生在打开处或包装层、为什么没有全局注册入口。
- `ui-performance.md`:说明缓存、显示策略与引擎级性能边界。
- 六个 inventory 页面:说明每一步新增的文件、组件职责、共享状态与注册 / 打开时机。`inventory-example-6-animation-and-register.md` 的 `text` 文件结构块在首行加 `// 目录结构:五个文件各负责一段`,不改树本身;该块的注释只用于说明结构,不引入代码。
- 17 个 demo:文件头说明演示目标;`ref` / `computed` / `onMounted` / `onUnmounted` / 事件处理 / 定时器 / 纹理创建处说明生命周期与清理;长 demo(>200 行)至少 6 条,80–200 行至少 4 条,≤80 行至少 2 条。
**(3)复核**:再跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`,重新计算聚合并写入 `Part 2-5 注释后代码哈希:<64 位 hex>`;必须与 `Part 2-5 注释前代码哈希:` 完全相同。不同则回退非注释改动后重算。
**(4)本任务不跑构建、不改 ROADMAP / STATE、不写 SUMMARY、不 commit。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $m1=[regex]::Match($np,'(?m)^Part 2-5 注释前代码哈希:([0-9a-f]{64})'); $m2=[regex]::Match($np,'(?m)^Part 2-5 注释后代码哈希:([0-9a-f]{64})'); if(-not $m1.Success -or -not $m2.Success){ Write-Error 'NO-PART25-HASH' }; if($m1.Groups[1].Value -ne $m2.Groups[1].Value){ Write-Error 'PART25-CODE-CHANGED' }; $pages=@('docs/advanced/ii/ui/reactivity.md','docs/advanced/ii/ui/events.md','docs/advanced/ii/ui/hotkey-in-ui.md','docs/advanced/ii/ui/conditional-and-list-rendering.md','docs/advanced/ii/ui/props.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/slots-and-attrs.md','docs/advanced/ii/ui/builtin-text-and-input.md','docs/advanced/ii/ui/builtin-list-and-containers.md','docs/advanced/ii/ui/ui-controller-and-stack.md','docs/advanced/ii/ui/replace-builtin-ui.md','docs/advanced/ii/ui/ui-performance.md','docs/advanced/ii/ui/inventory-example-1-skeleton.md','docs/advanced/ii/ui/inventory-example-2-grid.md','docs/advanced/ii/ui/inventory-example-3-detail.md','docs/advanced/ii/ui/inventory-example-4-scroll.md','docs/advanced/ii/ui/inventory-example-5-state.md','docs/advanced/ii/ui/inventory-example-6-animation-and-register.md'); $demos=@('reactivity-demo','events-demo','conditional-demo','props-demo','component-demo','slots-demo','builtin-text-demo','builtin-list-demo','controller-demo','strategy-demo','perf-demo','inventory-1-skeleton','inventory-2-grid','inventory-3-detail','inventory-4-scroll','inventory-5-state','inventory-6-full'); $js='const fs=require("fs");const pages=' + ($pages | ConvertTo-Json -Compress) + ';const demos=' + ($demos | ConvertTo-Json -Compress) + ';const bad=[];const isC=l=>/^\s*\/\//.test(l)||/^\s*\{\/\*.*\*\/\}\s*$/.test(l);pages.forEach(f=>{const s=fs.readFileSync(f,"utf8");const re=/```[^\n]*\r?\n([\s\S]*?)```/g;let m;let i=0;while((m=re.exec(s))){i++;const lines=m[1].split(/\r?\n/);const code=lines.filter(l=>l.trim()!=="");const cs=code.filter(isC).length;if(cs<1)bad.push("BLOCK-NO-COMMENT:"+f+":"+i);if(code.length>15&&cs<3)bad.push("BLOCK-FEW-COMMENTS:"+f+":"+i);}});demos.forEach(d=>{const f="docs/.vitepress/components/demos/ui/"+d+".tsx";const lines=fs.readFileSync(f,"utf8").split(/\r?\n/);const cs=lines.filter(isC).length;const need=lines.length>200?6:(lines.length>80?4:2);if(cs<need)bad.push("DEMO-FEW-COMMENTS:"+d+":"+cs+"<"+need);});if(bad.length){console.error(bad.join("|"));process.exit(1)}console.log("COMMENTS-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'COMMENT-ASSERT-FAIL' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-PART25-HASH", "PART25-CODE-CHANGED", "BLOCK-NO-COMMENT", "BLOCK-FEW-COMMENTS", "DEMO-FEW-COMMENTS", "COMMENT-ASSERT-FAIL"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>Part 2–5 的 18 篇正文每个代码块至少一条有价值注释、超 15 行的块至少 3 条;17 个 demo 按长度至少有 2 / 4 / 6 条注释;NOTES 有 `Part 2-5 注释前代码哈希` 与 `Part 2-5 注释后代码哈希` 且两者相同;既有注释逐字未改;未改任何非注释代码。</acceptance_criteria>
<done>Part 2–5 的 18 篇正文与 17 个 demo 注释补齐,代码哈希未变。</done>
</task>
<task type="auto">
<name>Task 5: 门禁(prettier / ESLint / docs 类型 / 构建 / 25 HTML / 静态断言 / 哈希)+ NOTES 记录 + 停止</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1–4 已完成;NOTES 含删除清单、25/24 计数、两组注释代码哈希;`client` 已清零;六处内联 TS 已加。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-48 pre-review 修复` 全部基线)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/index.md、docs/.vitepress/config.ts</read_first>
<action>**顺序不可颠倒;本任务只校验与记录,不改正文内容(prettier 格式化除外)。**
1. **prettier**:`cmd /c "pnpm exec prettier --write docs/advanced/ii docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/index.md"`,再跑同路径 `--check`。
2. **ESLint**:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,要求 exit 0 且输出无 `error` / `warning`。
3. **docs 类型**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,只要求 `docs/` 路径 0 个 `error TS`;既有引擎报错不计入本次失败,但要记录条数。
4. **静态断言**:25 篇 `.md`、24 个 `.tsx`;3 个被删文件不存在;全批无 `client.` 成员访问、无 `ui-template-ts` / `component-ts.md` 引用;配置 25 条 UI 链接;`ii/index` 含 `25 篇`、无 `27 篇`;25 篇与 24 个 demo 的每段代码块都有注释;所有 `.md` 与 `.tsx` 为 CRLF;25 篇均有单 H1 与 `## 边界与注意`;24 个 demo 均有 `export default` 且无 `style=` / `class=` DOM 属性。
5. **构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,要求 exit 0、输出含 `build complete`、不含 `dead link`;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。
6. **哈希复核**:重算 `ROADMAP 受保护行哈希`、`ROADMAP 全文哈希`、`STATE 全文哈希`,必须与 Task 1 基线逐字相同;重算 `Part 0-1` 与 `Part 2-5` 的去注释聚合哈希,必须与 NOTES 记录的「注释前 / 注释后」一致。
7. **写 NOTES**:在 `## 10-48 pre-review 修复` 下追加:
- `修复后 docs 快照哈希:` + 25 篇 UI 正文 + 两页导览按 Task 1 算法重算的 SHA-256。
- `修复后 demo 快照哈希:` + 24 个 demo 按 Task 1 算法重算的 SHA-256。
- `页面计数:25`、`demo 计数:24`、`构建产物:25`。
- `10-48 门禁:prettier 通过;ESLint 0/0;docs 类型 0 报错;构建 green;0 dead link;25 HTML;静态断言通过。`
- `停止点:10-48 修复结束,未进入 10-49 独立审阅;未改 ROADMAP / STATE;未写 SUMMARY;未 commit。`
8. **立即停止**:不创建 `10-48-SUMMARY.md` / `10-49-READER-REVIEW.md` / `10-50-USER-REVIEW.md` / 任何 SUMMARY,不进入读者审阅,不改 ROADMAP / STATE,不 commit。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); foreach($k in @('修复后 docs 快照哈希:','修复后 demo 快照哈希:','页面计数:25','demo 计数:24','构建产物:25','10-48 门禁:','停止点:10-48 修复结束')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; foreach($h in @('修复后 docs 快照哈希','修复后 demo 快照哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; if($np -notmatch '(?m)^基线 HEAD(10-48 记录):[0-9a-f]{7,40}'){ Write-Error 'NO-BASE-HEAD' }; $baseDocs=[regex]::Match($np,'(?m)^修复前 docs 快照哈希:([0-9a-f]{64})'); if(-not $baseDocs.Success){ Write-Error 'NO-PRE-DOCS' }; $baseDemo=[regex]::Match($np,'(?m)^修复前 demo 快照哈希:([0-9a-f]{64})'); if(-not $baseDemo.Success){ Write-Error 'NO-PRE-DEMO' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:' + $md.Count) }; if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:' + $demo.Count) }; foreach($d in @('docs/advanced/ii/ui/ui-template-ts.md','docs/advanced/ii/ui/component-ts.md','docs/.vitepress/components/demos/ui/ts-component-demo.tsx')){ if(Test-Path -LiteralPath $d){ Write-Error "NOT-DELETED $d" } }; $hits=@(Get-ChildItem docs/advanced/ii/ui -Filter *.md -File | Select-String -Pattern '(?<![\w-])client\.'); if($hits.Count -gt 0){ $hits | ForEach-Object { Write-Output ("$($_.Path):$($_.LineNumber):$($_.Line)") }; Write-Error 'GLOBAL-CLIENT-REMAINS' }; $cfg=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); $cfgLinks=([regex]::Matches($cfg,'/advanced/ii/ui/[a-z0-9-]+')).Count; if($cfgLinks -ne 25){ Write-Error ('CFG-COUNT:' + $cfgLinks) }; if($cfg -match 'ui-template-ts|/advanced/ii/ui/component-ts[\x27\x22]'){ Write-Error 'CFG-STILL-TS' }; $idx=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); if($idx -match 'ui-template-ts|27 篇'){ Write-Error 'INDEX-STILL-OLD' }; if($idx.IndexOf('25 篇') -lt 0){ Write-Error 'INDEX-NO-25' }; $p01=@('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md','docs/.vitepress/components/demos/ui/template-demo.tsx','docs/.vitepress/components/demos/ui/container-demo.tsx','docs/.vitepress/components/demos/ui/shapes-demo.tsx','docs/.vitepress/components/demos/ui/curves-demo.tsx','docs/.vitepress/components/demos/ui/text-demo.tsx','docs/.vitepress/components/demos/ui/texture-demo.tsx','docs/.vitepress/components/demos/ui/layer-demo.tsx'); $p25=@('docs/advanced/ii/ui/reactivity.md','docs/advanced/ii/ui/events.md','docs/advanced/ii/ui/hotkey-in-ui.md','docs/advanced/ii/ui/conditional-and-list-rendering.md','docs/advanced/ii/ui/props.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/slots-and-attrs.md','docs/advanced/ii/ui/builtin-text-and-input.md','docs/advanced/ii/ui/builtin-list-and-containers.md','docs/advanced/ii/ui/ui-controller-and-stack.md','docs/advanced/ii/ui/replace-builtin-ui.md','docs/advanced/ii/ui/ui-performance.md','docs/advanced/ii/ui/inventory-example-1-skeleton.md','docs/advanced/ii/ui/inventory-example-2-grid.md','docs/advanced/ii/ui/inventory-example-3-detail.md','docs/advanced/ii/ui/inventory-example-4-scroll.md','docs/advanced/ii/ui/inventory-example-5-state.md','docs/advanced/ii/ui/inventory-example-6-animation-and-register.md','docs/.vitepress/components/demos/ui/reactivity-demo.tsx','docs/.vitepress/components/demos/ui/events-demo.tsx','docs/.vitepress/components/demos/ui/conditional-demo.tsx','docs/.vitepress/components/demos/ui/props-demo.tsx','docs/.vitepress/components/demos/ui/component-demo.tsx','docs/.vitepress/components/demos/ui/slots-demo.tsx','docs/.vitepress/components/demos/ui/builtin-text-demo.tsx','docs/.vitepress/components/demos/ui/builtin-list-demo.tsx','docs/.vitepress/components/demos/ui/controller-demo.tsx','docs/.vitepress/components/demos/ui/strategy-demo.tsx','docs/.vitepress/components/demos/ui/perf-demo.tsx','docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx','docs/.vitepress/components/demos/ui/inventory-2-grid.tsx','docs/.vitepress/components/demos/ui/inventory-3-detail.tsx','docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx','docs/.vitepress/components/demos/ui/inventory-5-state.tsx','docs/.vitepress/components/demos/ui/inventory-6-full.tsx'); $js='const fs=require("fs"),crypto=require("crypto");const p01=' + ($p01 | ConvertTo-Json -Compress) + ';const p25=' + ($p25 | ConvertTo-Json -Compress) + ';const strip=s=>s.split(/\r?\n/).fLine truncated
<fails_when>non-zero exit, or output contains "NOTES-MISSING", "BAD-HASH", "NO-BASE-HEAD", "NO-PRE-", "MD-COUNT", "DEMO-COUNT", "NOT-DELETED", "GLOBAL-CLIENT-REMAINS", "CFG-COUNT", "CFG-STILL-TS", "INDEX-STILL-OLD", "INDEX-NO-25", "PART01-", "PART25-", "BLOCK-NO-COMMENT", "BLOCK-FEW-COMMENTS", "DEMO-FEW-COMMENTS", "DEMO-DEFAULT", "DEMO-DOM", "CODE-HASH-ASSERT-FAIL", "PRETTIER-", "ESLINT-", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "ROADMAP-MODIFIED", "STATE-MODIFIED", "NO-ROADMAP-HASH", "NO-STATE-HASH", "NO-PROTECTED-HASH", "ROADMAP-PROTECTED-CHANGED", "UNEXPECTED-SUMMARY"; or output lacks "T5-OK"</fails_when>
</verify>
<acceptance_criteria>prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径 0 类型错误;构建 green、`build complete`、0 dead link;`public/_docs/advanced/ii/ui` 恰好 25 个 HTML;25 篇 / 24 demo / 25 条侧边栏;3 个文件已删;全批无全局 `client`、无被删页引用;每段代码块与每个 demo 有注释;两组去注释代码哈希重算一致;ROADMAP / STATE 全文与受保护行哈希未变;NOTES 有 `修复后 docs / demo 快照哈希`、`页面计数:25`、`demo 计数:24`、`构建产物:25`、`10-48 门禁:`、`停止点:10-48 修复结束...`;未创建任何 SUMMARY。</acceptance_criteria>
<done>三项修复完成并通过全部门禁,10-48 在审阅前停止。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 修复 → 已验收正文 | 只允许三项修复;其它语义与示例结构不得改动 |
| 删除 → 侧边栏 / 导览 / 交叉引用 | 删除页面后必须同步所有入口与篇号,否则出现 404 或错误指代 |
| 内联 TS → 页面结构 | 只能追加代码块,不得新增独立页面 / demo / live |
| 注释 → 代码行为 | 只新增整行注释;非注释代码不得改变 |
| 10-48 → 账本 | 不写 SUMMARY / ROADMAP / STATE、不 commit |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-162 | Tampering | 删除范围 | high | mitigate | 明确只删 2 页 1 demo;Task 1 / 5 校验 MD=25、DEMO=24、被删文件不存在 |
| T-10-163 | Tampering | 内联 TS 变成新页面 / demo | high | mitigate | 只允许六处 `ts` 代码块;Task 5 校验文件计数与无新增 demo |
| T-10-164 | Spoofing | 全局 `client` 残留 | high | mitigate | Task 2 全批扫描 `(?<![\w-])client\.`;Task 5 复扫并失败即停 |
| T-10-165 | Tampering | 注释改动代码行为 | high | mitigate | 只加整行 `//` / 单行 `{/* */}`;Part 0-1 / Part 2-5 去注释聚合哈希前后必须相同 |
| T-10-166 | Repudiation | 10-48 越界写账本 / SUMMARY | medium | mitigate | ROADMAP / STATE 全文与受保护行哈希在 Task 1 记录、Task 5 重算;任何 SUMMARY 存在即失败 |
| T-10-167 | Denial of Service(构建不可用) | 删除与内联引入死链 / 类型错误 | high | mitigate | 删除后同步 sidebar / 导览 / 篇号;Task 5 要求 build green、0 dead link、25 HTML、docs 路径 0 类型错误 |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 关卡门禁:Task 0 已获「可以执行」;NOTES 含 `用户确认(10-47):可以执行`。
- 删除门禁:只删 2 页 1 demo;`docs/advanced/ii/ui` 恰好 25 篇、demos 恰好 24 个;侧边栏 25 条;两页导览无被删链接;篇号引用按映射更新。
- 内联门禁:六处 `ts` 代码块存在;未新增页面 / demo / live。
- client 门禁:25 篇无 `client.` 成员访问;模板与 UIController 篇说明 `props.state` 与「没有全局 client」。
- 注释门禁:25 篇每段代码块至少一条有价值注释、超 15 行至少 3 条;24 个 demo 按长度至少 2 / 4 / 6 条;既有注释逐字未改。
- 行为门禁:Part 0-1 与 Part 2-5 的去注释聚合哈希在注释前后一致,且 Task 5 重算一致;prettier 只做格式化。
- 构建门禁:prettier `--check`、ESLint 0/0、`docs/` 路径 0 类型错误、`pnpm docs:build` green + `build complete` + 0 dead link、25 个 HTML。
- 越界门禁:ROADMAP / STATE 全文与受保护行哈希与 Task 1 一致;未创建任何 SUMMARY;未改 `packages*` / `src`;未 commit。
- 停止门禁:NOTES 有 `停止点:10-48 修复结束,未进入 10-49 独立审阅;未改 ROADMAP / STATE;未写 SUMMARY;未 commit。`
</verification>
<success_criteria>
- 独立 TS 页与 TS demo 已删除,六处内联 TS 片段就位,全批为 25 篇正文 / 24 个 demo。
- 全批无全局 `client`,模板与 UIController 篇说明 `props.state` 取法。
- 25 篇正文的所有代码块与 24 个 demo 都有有价值注释,且非注释代码未变。
- prettier / ESLint / docs 类型 / 构建 / 25 个 HTML 全部通过;ROADMAP / STATE 未被改动;未 commit。
- 10-48 在修复结束即停止,独立读者审阅留给 10-49。
</success_criteria>
<output>
本计划**不写 SUMMARY**。完成后在对话中报告删除清单、25/24 计数与门禁结果,然后停止;独立读者审阅由 `10-49-PLAN.md` 执行,用户修订与收尾由 `10-50-PLAN.md` 执行。
</output>
## 编号变更(2026-11-01)
本文件写作期把「独立读者审阅」称为 10-49、把「用户修订与收尾」称为 10-50;重排后按下列映射理解(原文保持不变):
- 读者审阅 → `10-53-PLAN.md`(Round 2/3;Round 1 记录保留在 `10-49-READER-REVIEW.md`,本文件写作期的 `10-49-READER-REVIEW.md` 指针仍有效)。
- 用户修订、最终门禁、全站 live、落位评估与收尾 → `10-54-PLAN.md`。
- 新增的 `10-49`..`10-52` 是 Part 0–1 / 2–3 / 4 / 5 的深度扩写(D-93);`10-48` 仍是 pre-review 修复。
- 旧 `10-49-PLAN.md` / `10-50-PLAN.md` 已被新计划替换;本文件不因编号变更而改正文。
@@ -0,0 +1,351 @@
---
phase: 10-docs-restructure
plan: 49
type: execute
wave: 7
depends_on:
- 10-48
files_modified:
- docs/advanced/ii/ui/ui-template.md
- docs/advanced/ii/ui/container-and-coordinates.md
- docs/advanced/ii/ui/basic-shapes.md
- docs/advanced/ii/ui/curves-and-paths.md
- docs/advanced/ii/ui/text.md
- docs/advanced/ii/ui/image-and-texture.md
- docs/advanced/ii/ui/layer-transform-performance.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 72000
raw_tokens: 43000
tasks: 6
confidence: low
must_haves:
truths:
- "Part 0–1 的 7 篇按 D-93 补齐深度:渲染树模型、事件模型、元素/组件具体用法与设计原因、示例后解释四类内容逐页判定并落表(D-93 第 1–4 条)"
- "扩写不新增、不删除页面,仍为 25 篇正文与 24 个 demo;不新增导航、不改侧边栏、不改 demo(D-88 / D-93)"
- "每篇长度由内容决定:~300 行只是体量参考,不设下限也不设上限,不因低于 300 行判失败;不注水、不堆接口表(D-88)"
- "Round 1 的 116 条提问与 178 行分节概率只作内部输入(10-49-READER-REVIEW.md),不交给用户,也不作为唯一修改清单;扩写按 D-93 系统检查(D-91 / D-93 第 5 条)"
- "扩写只改本计划列出的 7 篇正文与 NOTES;其余 18 篇正文、两份导览、`docs/.vitepress/`、demo、`packages/`、`packages-user/`、`src/` 一律不改"
- "本计划不写 SUMMARY、不改 ROADMAP / STATE、不 commit;完成后停在扩写,不进入读者循环与用户审阅"
artifacts:
- "docs/advanced/ii/ui/ui-template.md(渲染树映射、事件入口、组件/元素/生命周期、文件放置与注册)"
- "docs/advanced/ii/ui/{container-and-coordinates,basic-shapes,curves-and-paths,text,image-and-texture,layer-transform-performance}.md(按 D-93 补齐模型、事件、组件用法与示例解释)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 `## 10-49 深度扩写(Part 0–1)`:基线、D-93 覆盖表、体量参考、门禁、停止点)"
key_links:
- "先建 D-93 覆盖表再动笔:没有逐页判定,扩写会退化成补几个读者问题,无法保证 25 篇同一深度口径(D-93 第 5 条)"
- "渲染树模型必须先于事件与组件:坐标、zIndex、命中顺序都挂在树上,先讲接口会让读者背结论(D-82 / D-93 第 1 条)"
- "示例后必须解释:代码只说明「怎么写」,解释才说明「在渲染树/事件/组件模型里的位置与理由」(D-93 第 4 条)"
- "体量只记录不设门禁:把 ~300 行当硬指标会诱导注水,违反 D-88"
---
<scope_justification>
本计划承担 25 篇中的 Part 0–1(7 篇)。扩写按 Part 分组而不是按 25 篇平均切分:
- Part 0–1 是「先能画出来」的地基(模板、坐标、图形、曲线、文字、图片、层级),7 篇共享同一套渲染树与命中模型,放在一个计划里才能一次讲清共用概念,后面的页面只引用不重复。
- 25 篇按每计划 ≤8 篇切分为 7 / 7 / 5 / 6 四份扩写计划:10-49(Part 0–1)、10-50(Part 2–3)、10-51(Part 4)、10-52(Part 5)。25 篇无法在 3 份计划内满足 ≤8 篇,故为 4 份,而不是压缩单篇深度。
- 四份扩写计划串行(wave 7→10),原因是它们共享同一份 `10-CUSTOM-UI-NOTES.md` 与同一套 `pnpm docs:build` 产物目录;并行会互相覆盖记录与构建输出。篇目本身不重叠,串行只为保护记录与构建,不改变每篇的写作口径。
- 本计划只写 7 篇正文与 NOTES;不写 SUMMARY、不改 ROADMAP / STATE、不改 demo、不 commit。
</scope_justification>
<objective>
按 D-93 把 Part 0–1 的 7 篇从「能照着抄」扩写到「能自己写」:讲清渲染树如何建立、坐标与变换如何沿树传递、`zIndex` 与绘制/命中顺序、元素生命周期与缓存/脏更新、组件如何映射成渲染树;讲清命中测试、捕获/冒泡、enter/leave、`noevent` / `actionStroke` 与嵌套传播;讲清每个元素/组件的具体用法、典型组合、注意事项与设计原因;每次给出代码后解释它在模型中的位置与理由。
Purpose: 当前 7 篇已能完成基本操作,但读者仍会在「文件放哪、坐标相对谁、谁先接事件、缓存什么时候脏、组件怎么变成元素」上卡住;只补参数表无法让读者独立改写示例(D-93)。
Output: 7 篇扩写后的正文 + NOTES 中的基线、D-93 覆盖表、体量参考与门禁记录。**不新增/删除页面、不改 demo、不改其它 18 篇、不写 SUMMARY / ROADMAP / STATE、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-48-PLAN.md
@.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
@docs/.vitepress/config.ts
**流程约定:**
- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-48` 计划与 SUMMARY、不改 POC 文件、不改 `docs/` 其它页面与 demo、不改 `packages/` / `packages-user/` / `src/`。
- **Task 0 是硬关卡**:汇报扩写范围、D-93 逐条口径、Round 1 内部输入的使用边界、体量口径与停止条件,等用户明确回复「可以执行」。
- 修改方式为**派发子代理执行**;改文件前先声明本次写入是内联还是派发。正文扩写一律派发子代理。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 代码注释;不 commit(D-90)。
- 写作口径按 D-59..D-74、D-77..D-88、D-91..D-93;示例注释按 D-65,代码块保留完整类上下文按 D-70,不写源码叙述按 D-80,不写使用概率元信息按 D-79。
- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。
**本批事实(执行时以这些为准):**
- 10-43..10-47 已执行完成,10-48 已完成 pre-review 修复;10-49 Round 1 独立读者审阅已完成,记录在 `10-49-READER-REVIEW.md`(25 篇、116 条提问、178 行分节概率),docs 未改。
- 本计划只做 Part 0–1 的**深度扩写**,不是读者审阅;读者循环在第 10-53 计划执行,用户审阅在第 10-54 计划执行。
- 25 篇位于 `docs/advanced/ii/ui/`,24 个 demo 位于 `docs/.vitepress/components/demos/ui/`;侧边栏 25 条在 `docs/.vitepress/config.ts`。
- 参考哈希基线(`## 参考清单哈希基线` 与各批复核表)是写作期记录,本计划不读源码改源码,也不得改写这些哈希记录。
- 相关源码只用于**核对模型事实**,不写进正文:`packages/render/src/core/{item,container,event,graphics,render,transform}.ts`、`packages/render-vue/src/{renderer,tag,elements,props}.ts`、`packages/system/src/ui/{ui,controller,instance,types}.ts`、`packages-user/client-base/src/types.ts`、`src/client/ui/index.ts`。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报 Part 0–1 扩写范围、D-93 口径与停止条件,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CONTEXT.md(D-88、D-90、D-91、D-92、D-93)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构:25 篇、116 条提问、178 行分节概率)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、门禁、10-48 基线)、.planning/phases/10-docs-restructure/10-48-PLAN.md(停止点)、docs/advanced/ii/ui/ 下 7 篇现文、docs/.vitepress/config.ts</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——只做一件事:按 D-93 深度扩写 Part 0–1 的 7 篇(`ui-template`、`container-and-coordinates`、`basic-shapes`、`curves-and-paths`、`text`、`image-and-texture`、`layer-transform-performance`)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不进入读者循环,不进入用户审阅。
**为什么**——这 7 篇是后面 18 篇的地基,但当前主要回答「怎么写」,没有系统回答「渲染树是什么、坐标和变换沿树怎么传、谁先接事件、缓存什么时候脏、组件怎么变成元素」。只补读者列出的问题会漏掉同类缺口,所以按 D-93 逐页判定四类内容,而不是按问题清单打补丁。
**大致怎么做**——Task 1 先把基线、D-93 覆盖表(7 篇 × 渲染树/事件/元素组件/示例解释)与体量参考写进 NOTES;Task 2 扩写 Part 0 的模板篇;Task 3 扩写坐标、图形、曲线 3 篇;Task 4 扩写文字、图片、层级 3 篇;每篇都要求「先模型、再用法、示例后解释」;Task 5 跑门禁、做 D-93 抽查、记录体量并停止。
**影响范围**——只改上述 7 篇正文与 `10-CUSTOM-UI-NOTES.md`。不改其余 18 篇、两份导览、侧边栏、24 个 demo、`packages/` / `packages-user/` / `src/`、既有 JSDoc/注释、ROADMAP / STATE;不写 SUMMARY;不 commit。
**D-93 逐条口径(将写入 NOTES 覆盖表):**
1. 渲染树模型:根/容器/子元素树、坐标与变换沿树传递、`zIndex` 与绘制/命中顺序、元素生命周期、缓存/脏更新、组件如何映射成渲染树。
2. 事件模型:命中测试、捕获与冒泡顺序、enter/leave、`noevent` / `actionStroke`、事件对象、嵌套容器中的传播。
3. 元素/组件用法:具体使用方式、重要功能、典型组合与场景、注意事项、为什么这样设计;不能只写「能做什么 / 参数有什么」。
4. 示例与解释并重:每次给代码后解释它在渲染树/事件/组件模型中的位置与理由,不能只给可复制代码。
**体量口径**——每篇长度由内容决定;用户提到的「每篇大概 300 行」只是体量/深度参考,不是门禁。内容本来少的页面不注水,低于 300 行不判失败;高于 300 行也不判失败(D-88)。
**Round 1 的使用边界**——`10-49-READER-REVIEW.md` 的 116 条提问只作内部输入,不交给用户,也不能只修这些;扩写必须按 D-93 系统检查。读者循环在 10-53 才执行。
**请用户确认:**
1. 扩写范围是 Part 0–1 的 7 篇;不新增/删除页面与 demo,不改其它 18 篇与导览。
2. 四类 D-93 内容逐页判定;不适用的格子写「不适用:理由」,不能留空或写「待补」。
3. 体量只记录不设门禁;不因低于 300 行失败,也不为凑行数注水。
4. 停止条件:扩写与门禁结束即停止;不进入读者循环、不写 SUMMARY / ROADMAP / STATE、不 commit。
5. 本次修改方式为**派发子代理执行**;不改既有注释;不调用 `opencode` 命令。
**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报扩写范围、D-93 口径、体量口径、Round 1 使用边界与停止条件。</what-built>
<how-to-verify>确认:①7 篇范围与「不新增/删除页面、不改 demo、不改其它 18 篇」;②四类 D-93 内容逐页判定、允许「不适用:理由」但不允许留空;③~300 行只是参考、不设门禁、不注水;④Round 1 仅内部输入、读者循环在 10-53;⑤扩写结束即停、不写 SUMMARY / ROADMAP / STATE、不 commit;⑥派发子代理执行、不改既有注释。</how-to-verify>
<resume-signal>回复「可以执行」以继续;其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且扩写范围、D-93 四类口径、体量口径、Round 1 使用边界、停止条件、派发方式六项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,且扩写范围、D-93 口径、体量口径、Round 1 边界、停止条件、派发方式均已确认。</human-check>
</verify>
<done>用户回复「可以执行」且六项待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 扩写前基线 + D-93 覆盖表 + 体量参考(不改正文)</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>`10-CUSTOM-UI-NOTES.md` 含 `读者审阅:已完成`;`10-49-READER-REVIEW.md` 存在且为 25 篇、116 条提问、178 行分节概率;用户已在 Task 0 回复「可以执行」。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(末尾 10-49 审阅小节与命名总表)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构,不改内容)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/ui/ 下 7 篇现文与其余 18 篇文件名</read_first>
<action>**本任务只建基线与覆盖表,绝对不改 `docs/` 正文、不改 ROADMAP / STATE。**
向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-49 深度扩写(Part 0–1)` 小节,依次写入以下固定格式的行(各独占一行,后续任务与 verify 按字面量断言):
1. `扩写范围:` + `docs/advanced/ii/ui/` 下 7 篇(Part 0–1),逐条列出完整路径;写「不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 18 篇与两份导览」。
2. `Round 1 内部输入:` + `10-49-READER-REVIEW.md(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单`。
3. `基线 HEAD(10-49 深度扩写):` + `git rev-parse HEAD` 的完整 sha。
4. `扩写前本批页面聚合哈希:` + 对上述 7 篇取聚合 SHA-256(小写 hex,64 位)。算法:按 `docs/advanced/ii/ui/...` 相对路径字符串排序,逐个对文件字节取 SHA-256,拼成 `相对路径:hash` 后用 LF 连接,再取 SHA-256。
5. `本批外文件聚合哈希:` + 对其余 18 篇正文 + `docs/advanced/ii/index.md` + `docs/advanced/index.md` 取同一算法的聚合 SHA-256(小写 hex,64 位)。用于证明本计划没有碰批外文档。
6. `ROADMAP 全文哈希:` 与 `STATE 全文哈希:` + 各自 UTF-8 全文的 SHA-256(小写 hex,64 位)。用于证明本计划没碰两个账本。
7. `### D-93 覆盖表` + 一张 7 行表格,表头逐字为 `| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |`;每行「篇目」写完整相对路径;四类内容格先写 `待补`,若确不适用写 `不适用:<一句理由>`;「现状行数」写当前 `Get-Content` 行数。
8. `体量参考(非门禁):` + 7 篇当前总行数与平均行数,并明确写「~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)」。
9. `停止点:10-49 只做 Part 0–1 深度扩写;不改 10-50..10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。`
**本任务不得修改任何 `docs/` 文件、不得改 ROADMAP / STATE、不得派发扩写子代理。** 写完立即结束本任务。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '读者审阅:已完成'){ Write-Error 'NO-1049-REVIEW-MARK' }; if(-not(Test-Path -LiteralPath '.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md')){ Write-Error 'MISSING-REVIEW' }; $pages=@('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); foreach($k in @('## 10-49 深度扩写(Part 0–1)','扩写范围:','Round 1 内部输入:','基线 HEAD(10-49 深度扩写):','扩写前本批页面聚合哈希:','本批外文件聚合哈希:','ROADMAP 全文哈希:','STATE 全文哈希:','D-93 覆盖表','体量参考(非门禁):','停止点:10-49 只做')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-49 深度扩写):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('扩写前本批页面聚合哈希','本批外文件聚合哈希','ROADMAP 全文哈希','STATE 全文哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; $rows=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/' }); if($rows.Count -ne 7){ Write-Error ('MATRIX-ROWS:'+$rows.Count) }; foreach($p in $pages){ if($np.IndexOf($p) -lt 0){ Write-Error "NO-PAGE-ROW $p" }; if(-not ($rows | Where-Object { $_.IndexOf($p) -ge 0 })){ Write-Error "NO-MATRIX-ROW $p" } }; foreach($r in $rows){ $c=@($r.Trim('|') -split '\|'); if($c.Count -lt 6){ Write-Error 'MATRIX-COLS' }; for($i=0;$i -lt 6;$i++){ if([string]::IsNullOrWhiteSpace($c[$i])){ Write-Error 'MATRIX-EMPTY' } } }; if($np -notmatch '116 条提问'){ Write-Error 'NO-ROUND1-COUNT' }; if($np -notmatch '178 行分节概率'){ Write-Error 'NO-PROB-COUNT' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-1049-REVIEW-MARK", "MISSING-REVIEW", "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NO-MATRIX-SECTION", "MATRIX-ROWS", "NO-PAGE-ROW", "NO-MATRIX-ROW", "MATRIX-COLS", "MATRIX-EMPTY", "NO-ROUND1-COUNT", "NO-PROB-COUNT", "MD-COUNT", "DEMO-COUNT"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 有 `## 10-49 深度扩写(Part 0–1)` 与九项固定行;`### D-93 覆盖表` 含 7 篇完整路径、表头六列、四类内容格非空(`待补` 或 `不适用:理由`)、现状行数为数字;Round 1 的两个计数(116 / 178)已记录且明确「仅内部输入」;四个聚合/账本哈希均为 64 位小写 hex;`docs/advanced/ii/ui` 仍为 25 篇、demo 仍为 24 个;未改任何 `docs/` 正文、未改 ROADMAP / STATE。</acceptance_criteria>
<done>扩写基线与 D-93 覆盖表已落盘,正文未动。</done>
</task>
<task type="auto">
<name>Task 2: 扩写 Part 0 模板篇(组件如何映射成渲染树)</name>
<files>docs/advanced/ii/ui/ui-template.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1 已写入 `## 10-49 深度扩写(Part 0–1)` 与 D-93 覆盖表;7 篇现文未被改动。</precondition>
<read_first>docs/advanced/ii/ui/ui-template.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅 ui-template.md 的提问,不向用户转述)、packages/render-vue/src/renderer.ts(createElement / insert / remove / createText 的映射)、packages/render-vue/src/tag.ts(内置标签到元素类的注册)、packages/system/src/ui/{ui,controller,instance,types}.ts(GameUI、open/close、props 注入)、packages-user/client-base/src/types.ts(IGameUIPropsBase.state)、src/client/ui/index.ts(UI 文件的导出入口)</read_first>
<action>**只改 `ui-template.md` 与 NOTES;本任务不碰其它 6 篇、不碰 demo。**
在保留现有正确内容的前提下扩写,按读者理解顺序组织(D-84),至少补齐以下四块,并保证每块先讲模型再讲用法:
1. **模板在渲染树里的位置**:新增 `## 这份模板在渲染树里的位置`。讲清 Vue 组件树 → render 函数返回的 VNode → 元素层渲染树(根节点 → `container` → `g-rect` / `text`)的映射;`createElement` 把标签变成元素实例,`insert` 挂到父节点,`remove` 销毁子树;组件重渲染只更新属性,不重建整棵树。解释为什么不能把裸文字写在 `container` 里(文字 VNode 会被当成文字元素并告警,空白会变成注释节点),以及 `container` 作为根子树与画布根的关系。
2. **事件从哪里进入**:新增 `## 事件从哪里进入`。用一小段说明:点击从画布根开始,按 `zIndex` 与子元素顺序找到最上层被点到的元素,再沿容器向外冒泡;`container` 是捕获单位;面板被打开后,它的根容器就是这棵子树的入口。只讲入口,捕获/冒泡的完整规则指向 `./events.md#捕获与冒泡`,不在这里重抄。
3. **组件、元素与打开方式**:新增 `## 组件、元素与打开方式`。讲清 `controller` / `instance` / `state` 三个基础 props 的来源;`instance` 是这次打开产生的实例句柄,`close` 要凭它关闭;`open` 的第二个参数只放你自己声明的 props(不是 `controller` / `instance` / `state`);`GameUI` 是 `{ name, component }` 对象,打开时传对象而不是靠名字查找——先核对 `packages/system/src/ui/ui.ts`,若与现有「靠名字识别」表述冲突,按 D-72 以源码注释为准并在对话中报告,不把冲突写进正文;同时说明静态查表列表并未自动填充,不要依赖名字反查。补文件放置与注册:游戏 UI 放在 `src/client/ui/<name>.tsx`,在 `src/client/ui/index.ts` 导出,客户端入口通过该出口拿到模块;不要写成「放哪都行」。
4. **两条写法怎么选**:新增 `## 两条写法怎么选`。把 TSX 与手写元素层两条路线放在同一棵渲染树下比较:TSX 负责组件、响应式与生命周期,手写元素层适合极底层的一次性结构;两者可以混用,但混用时谁负责挂载、谁负责销毁要说清。
**写法硬要求:**
- 每次给代码后必须用一段解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条),不能只给可复制代码。
- 代码块保留完整类/函数上下文(D-70),注释解释关键行为(D-65);不要写「模板」「[需改]」等标记(D-83)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写「v1 / 简化版 / 以后再做」这类降级表述。
- 不新增/删除页面或 demo;不因凑 300 行注水(D-88)。现文中的正确内容保留,不整篇重写。
**完成后更新 NOTES 的 D-93 覆盖表**:把 `ui-template.md` 行的四类内容格改为 `已讲`(确不适用才保留 `不适用:理由`),并追加一行 `自查:docs/advanced/ii/ui/ui-template.md — 渲染树:…;事件:…;组件/元素:…;示例解释:…`(每项一句,说明新增位置)。再在该小节追加 `已完成扩写:docs/advanced/ii/ui/ui-template.md` 与本任务点名的门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $p='docs/advanced/ii/ui/ui-template.md'; if(-not(Test-Path -LiteralPath $p)){ Write-Error 'MISSING-PAGE' }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); foreach($k in @('渲染树','事件','组件','实例','src/client/ui','index.ts','为什么')){ if($t.IndexOf($k) -lt 0){ Write-Error "PAGE-MISSING $k" } }; if($t -match '(?m)^##\s*(模板|需改)'){ Write-Error 'TEMPLATE-MARKER' }; if($t -match '简化版|以后再做|v1'){ Write-Error 'SCOPE-REDUCTION' }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '(?m)^已完成扩写:docs/advanced/ii/ui/ui-template\.md\s*$'){ Write-Error 'NO-DONE-MARK' }; if($np -notmatch '(?m)^自查:docs/advanced/ii/ui/ui-template\.md'){ Write-Error 'NO-SELF-CHECK' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/ui-template\.md' }); if($row.Count -ne 1){ Write-Error 'NO-MATRIX-ROW' }; if($row[0] -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui/ui-template.md" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING-PAGE", "PAGE-MISSING", "TEMPLATE-MARKER", "SCOPE-REDUCTION", "NO-DONE-MARK", "NO-SELF-CHECK", "NO-MATRIX-ROW", "MATRIX-STILL-PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>`ui-template.md` 新增渲染树位置、事件入口、组件/元素/打开方式、两条写法怎么选四块内容;讲清组件→VNode→元素树映射、为什么不能写裸文字、`props` 三个基础项、`open` 第二参数、`instance` 与 `close`、`GameUI` 对象、文件放 `src/client/ui/` 并导出;每次代码后有模型解释;无「模板 / 需改 / 简化版 / v1 / 以后再做」;NOTES 的覆盖表该行为 `已讲` 且有 `自查:` 与 `已完成扩写:` 行;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>模板篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 3: 扩写坐标、图形、曲线 3 篇(渲染树、命中与组合)</name>
<files>docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/curves-and-paths.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2 已完成并写入 `已完成扩写:docs/advanced/ii/ui/ui-template.md`;其 cover 表行已无 `待补`;`docs/advanced/ii/ui` 仍为 25 篇。</precondition>
<read_first>docs/advanced/ii/ui/{container-and-coordinates,basic-shapes,curves-and-paths}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 3 篇的提问)、packages/render/src/core/{item,container,graphics,transform}.ts(坐标/变换继承、zIndex 排序、命中、`actionStroke`、图形模式)、packages/render/src/core/event.ts(`noevent`、事件对象字段)</read_first>
<action>**只改这 3 篇与 NOTES;不碰其它篇目与 demo。**
三篇都按「先模型、再用法、示例后解释」扩写,保留现有正确内容,补齐以下要点:
**(1)`container-and-coordinates.md`**
- 新增 `## 渲染树:根、容器与子元素`:根容器 → 子容器 → 叶子元素的树;父子通过挂载建立;容器同时是布局单位与事件捕获单位;`zIndex` 只在同一父级的兄弟之间排序,父级的 `zIndex` 带着整棵子树与父级的兄弟比较,子元素不能越过父级去盖住旁支。
- 新增 `## 坐标与变换如何沿树传递`:子坐标在父容器的局部坐标系里;父级的平移/缩放/旋转会复合到子级;锚点决定元素自身哪个点落在 `x/y` 上,也是变换中心;嵌套时不要用「累加屏幕坐标」的心算,按树逐层理解。
- 新增 `## 事件在嵌套容器中的路径`:命中从根向内找最上层元素,捕获从根向命中元素,冒泡从命中元素向根;容器在捕获阶段把事件交给子级;`stopPropagation` 只停止继续传播,不阻止同一元素上的其它监听器;`noevent` 的子树整个不参与命中(不是只跳过自身)。
- 新增 `## 生命周期与缓存`:`appendChild` / `removeChild` / 销毁的关系;容器默认缓存,子元素变化要通过脏标记向上传递,父级缓存才会重绘;`hidden` 保留实例与状态但跳过绘制与命中,三元卸载会销毁子树。
- 新增 `## 坐标基准与画布`:说明 `[0, 0, 480, 320]` 是渲染目标(画布)坐标,不是浏览器窗口 CSS 像素;窗口大小变化时是否缩放由客户端画布决定,不要假设「写 480 就一定占满屏幕」;需要适配时按画布尺寸算,不要按窗口算。核对 `packages/render/src/core/render.ts` 与客户端画布设置后再写,不确认的数字不写。
**(2)`basic-shapes.md`**
- 新增 `## 图形在渲染树里的位置`:图形是叶子元素,挂在容器下;绘制顺序由兄弟 `zIndex` 与插入顺序决定;命中按图形几何而不是包围盒。
- 扩写 `## 填充与描边` 为 `## 填充、描边与命中`:讲清模式判定(`fill` 与 `stroke` 同时开 → 填充+描边;只开一个 → 对应模式;都不开 → 默认填充;`strokeAndFill` 的优先级);默认颜色;`actionStroke` 只把描边算命中,内部区域下穿;同时开两个开关不会互相覆盖,而是组合。
- 新增 `## 图形作为界面零件`:槽位底板、分隔线、按钮底、半透明遮罩的典型组合;每种组合说明为什么用这个图形、命中要注意什么。
- 新增 `## 为什么矩形没有圆角`:明确 `g-rect` 不支持圆角,圆角用 `g-rectr`(见曲线篇),避免读者给 `g-rect` 加 `radius`。
- 补元素层类的来源:`Rect` / `Circle` / `Ellipse` / `Line` 从 `@motajs/render` 导入;TSX 标签由渲染器内置注册,不需要逐个 import。
**(3)`curves-and-paths.md`**
- 新增 `## 路径与曲线的坐标基准`:贝塞尔/二次曲线/路径没有 `loc`,点坐标相对父容器;要整体移动就包一层容器;`Path2D` 是浏览器全局对象,不是本框架导出。
- 新增 `## 路径在渲染树与命中中的位置`:路径是叶子元素;命中按路径几何;`actionStroke` 只命中描边;`Path2D` 不能序列化,不能进存档。
- 扩写 `## 圆角矩形`:把 `circle` 1–4 项、`ellipse` 2/4/6/8 项的角与值映射讲清(按源码/类型定义核对,不凭猜测);给一个「只有左上与右下圆角」的例子并解释映射。
- 新增 `## 什么时候用路径`:自定义边框、异形底板、装饰线;与基础图形的取舍(能用矩形/圆角就不要上路径,命中与维护都更简单)。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表中这 3 篇的四类内容格为 `已讲`(或 `不适用:理由`),各追加一行 `自查:<path> — …` 与 `已完成扩写:<path>`,并记录本任务门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $pages=@('docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md'); foreach($p in $pages){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $c=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[0])); foreach($k in @('渲染树','坐标','变换','事件','zIndex','缓存','画布')){ if($c.IndexOf($k) -lt 0){ Write-Error "CONTAINER-MISSING $k" } }; $s=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[1])); foreach($k in @('渲染树','命中','actionStroke','填充','描边','g-rectr','@motajs/render')){ if($s.IndexOf($k) -lt 0){ Write-Error "SHAPES-MISSING $k" } }; $v=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[2])); foreach($k in @('坐标','Path2D','命中','圆角','容器')){ if($v.IndexOf($k) -lt 0){ Write-Error "CURVES-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in $pages){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths='docs/advanced/ii/ui/container-and-coordinates.md docs/advanced/ii/ui/basic-shapes.md docs/advanced/ii/ui/curves-and-paths.md'; $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "CONTAINER-MISSING", "SHAPES-MISSING", "CURVES-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>三篇分别补齐:坐标篇的渲染树/变换继承/嵌套事件路径/生命周期缓存/画布基准;图形篇的渲染树位置/填充描边命中判定/界面零件组合/无圆角说明/元素类导入;曲线篇的坐标基准/Path2D/命中/圆角映射/使用取舍。每次代码后有模型解释;无降级/占位表述;NOTES 覆盖表 3 行为 `已讲` 且有 `自查:` 与 `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>坐标、图形、曲线 3 篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 4: 扩写文字、图片、层级 3 篇(叶子元素、纹理与脏更新)</name>
<files>docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 已完成并写入 3 条 `已完成扩写:`;覆盖表无 `待补`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>docs/advanced/ii/ui/{text,image-and-texture,layer-transform-performance}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 3 篇的提问)、packages/render/src/{style/font.ts,core/misc.ts,assets/texture.ts,core/item.ts}(Font/Text/Texture、尺寸测量、缓存与脏更新)、packages-user/client-base/src/material/*(纹理/素材来源;确认后再写具体加载方式)</read_first>
<action>**只改这 3 篇与 NOTES;不碰其它篇目与 demo。**
三篇按「先模型、再用法、示例后解释」扩写,保留现有正确内容,补齐:
**(1)`text.md`**
- 新增 `## 文字元素与渲染树`:文字是叶子元素;不能把裸文字写在 `container` 里;文字元素有自己的测量尺寸与命中矩形。
- 扩写 `## 字体` 与 `## 尺寸与居中`:`Font` 构造参数顺序与默认值、`Font.defaults()` / `Font.clone` 的用途;文字宽高由测量决定,给 `width/height` 不裁剪;描边计入尺寸;锚点 0.5 时 `x/y` 落在中心;`loc` 里的锚点与外面 `anchorX/anchorY` 重复时以属性写法为准(核对 `packages/render/src/core/misc.ts` 的属性合并顺序后再写)。
- 新增 `## 文字作为界面零件`:标题、标签、按钮文字、数值显示;说明多行文本应使用内置文本组件而不是手写多个 `text`。
- 新增 `## 为什么文字默认不缓存`:文字内容变化频繁,缓存会让每次改字都重绘离屏画布;需要缓存时显式开,并说明代价。
**(2)`image-and-texture.md`**
- 新增 `## 图片元素与纹理`:图片元素接收纹理对象,`loc` 决定画多大,纹理会拉伸铺满;命中按图片矩形。
- 新增 `## 纹理从哪里来`:`Texture` 接受 `HTMLCanvasElement` / `ImageBitmap` / `HTMLImageElement`;给出加载 PNG 图标的完整路径(创建 `Image`、等待加载完成、再构造纹理),说明加载是异步的,未完成时不要拿空纹理去画;如果项目有素材/纹理管理器,按 `packages-user/client-base/src/material/*` 的实际接口写,不确认的 API 不写。
- 新增 `## 像素图与高清缓存`:`hd` / `anti` / `noanti` 的用途;像素图要关抗锯齿并尽量整数缩放;缓存对静态图标有利、对频繁换帧的动画纹理不利。
- 新增 `## 图片作为界面零件`:图标、道具格、背景图;典型组合与注意事项(尺寸、透明边、像素对齐)。
- 补 `import` 来源:`Texture` 从 `@motajs/render` 导入。
**(3)`layer-transform-performance.md`**
- 新增 `## 渲染树、层级与绘制顺序`:兄弟按 `zIndex` 排序,绘制从小到大(后画覆盖先画),命中从大到小(最上层先接);父级 `zIndex` 带着整棵子树参与父级兄弟的排序;子元素不能越过父级盖住旁支。
- 新增 `## 变换沿树传递`:`scale` / `rotate` / `alpha` 作用在元素自身坐标系,锚点是变换中心;父级变换复合到子级;事件里的 `offsetX/offsetY` 是变换后反算回元素局部坐标的结果,`absoluteX/absoluteY` 是画布坐标。
- 新增 `## 缓存与脏更新`:容器默认缓存;元素属性变化会把脏标记沿父链上传,父级缓存才重绘;父级缓存命中时子级变化不会自动穿透,除非子级把父级标脏;`nocache` 优先级高于 `cache`;给出「静态复杂面板适合缓存、频繁变化子树不适合」的判断,并给一个错误示范(给会变的文字/图标容器开缓存)。
- 新增 `## 事件坐标与变换`:缩放/旋转后点击落在哪里、`offsetX` 为什么不是屏幕坐标、嵌套变换下如何用 `absoluteX` 做跨元素判断。
- 保留并强化 `hidden` 与三元卸载的对比表;补「`hidden` 不改变布局流,因为这里没有 DOM 布局流,只有树上的绘制与命中」这一句,直接回答读者对布局流的疑问。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整类/函数上下文(D-70);注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表中这 3 篇的四类内容格为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,并记录本任务门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $pages=@('docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); foreach($p in $pages){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $t1=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[0])); foreach($k in @('渲染树','Font','锚点','缓存','测量')){ if($t1.IndexOf($k) -lt 0){ Write-Error "TEXT-MISSING $k" } }; $t2=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[1])); foreach($k in @('Texture','HTMLImageElement','ImageBitmap','像素','命中','加载')){ if($t2.IndexOf($k) -lt 0){ Write-Error "IMAGE-MISSING $k" } }; $t3=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[2])); foreach($k in @('zIndex','变换','缓存','脏','offsetX','absoluteX','hidden')){ if($t3.IndexOf($k) -lt 0){ Write-Error "LAYER-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in $pages){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths='docs/advanced/ii/ui/text.md docs/advanced/ii/ui/image-and-texture.md docs/advanced/ii/ui/layer-transform-performance.md'; $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "TEXT-MISSING", "IMAGE-MISSING", "LAYER-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>文字篇补齐渲染树位置、Font/测量/锚点、界面零件、默认不缓存;图片篇补齐纹理来源与 PNG 加载、像素图设置、命中、常用零件、`Texture` 导入;层级篇补齐 zIndex 同父排序与子树、变换继承、缓存脏更新、事件坐标与变换、`hidden` 与布局流。每次代码后有模型解释;NOTES 覆盖表 3 行为 `已讲` 且有 `自查:` 与 `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>文字、图片、层级 3 篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 5: 门禁 + D-93 抽查 + 体量记录 + 停止</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2–4 已把 7 篇的四类内容格改为 `已讲`(或 `不适用:理由`),并各写入 `自查:` 与 `已完成扩写:`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-49 深度扩写(Part 0–1)` 全部内容)、docs/advanced/ii/ui/ 下 7 篇、.planning/ROADMAP.md、.planning/STATE.md</read_first>
<action>**只校验、记录与停止;除 NOTES 外不改任何文件。**
1. **D-93 抽查**:逐篇读 7 篇,按四类内容核对「是否讲清模型/事件/组件用法/示例解释」。每篇写一行 `D-93 抽查:<path> — 通过` 或 `D-93 抽查:<path> — 发现缺口(缺口一句)`;有缺口先回到对应 Task 修到通过,不得把缺口留到读者循环。
2. **结构门禁**:`docs/advanced/ii/ui` 仍为 25 篇 `.md`;demo 仍为 24 个 `.tsx`;7 篇均为 CRLF;7 篇均无 `待补` 覆盖格;每篇均有 `自查:` 与 `已完成扩写:`;无「模板 / 需改 / 简化版 / v1 / 以后再做」。
3. **聚合哈希门禁**:用 Task 1 的同一算法重算 `本批外文件聚合哈希` 与 `ROADMAP 全文哈希` / `STATE 全文哈希`,必须与 Task 1 逐字一致;重算 `扩写前本批页面聚合哈希` 对应的「扩写后本批页面聚合哈希」,必须与扩写前不同(证明 7 篇确实改了)。
4. **prettier**:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后跑同路径 `--check`。
5. **ESLint**:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,要求 exit 0 且输出不含 `error` / `warning`。
6. **docs 类型**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,只要求 `docs/` 路径 0 条 `error TS`;既有引擎报错只记录条数,不要求本计划修。
7. **构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,要求 exit 0、输出含 `build complete`、不含 `dead link`;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。
8. **写 NOTES**:在 `## 10-49 深度扩写(Part 0–1)` 下追加:
- `扩写后本批页面聚合哈希:` + 64 位小写 hex(与扩写前不同)。
- `体量参考(扩写后):` + 7 篇逐篇行数与总行数;再次写明「不设 300 行门禁,低于 300 行不失败」(D-88)。
- `### 10-49 门禁` + 上述六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、25 个 HTML、D-93 抽查逐篇结论。
- `停止点:10-49 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-50..10-54;未 commit。`
9. **立即停止**:不创建任何 SUMMARY、不改 ROADMAP / STATE、不 commit、不派发读者;读者循环由 10-53 执行。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; $pages=@('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); foreach($k in @('扩写后本批页面聚合哈希:','体量参考(扩写后):','### 10-49 门禁','D-93 抽查:','停止点:10-49 扩写结束')){ if($sec.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($sec -notmatch '(?m)^扩写后本批页面聚合哈希:[0-9a-f]{64}'){ Write-Error 'NO-POST-HASH' }; $mpre=[regex]::Match($sec,'(?m)^扩写前本批页面聚合哈希:([0-9a-f]{64})'); $mpost=[regex]::Match($sec,'(?m)^扩写后本批页面聚合哈希:([0-9a-f]{64})'); if(-not $mpre.Success -or -not $mpost.Success){ Write-Error 'NO-BATCH-HASH' }; if($mpre.Groups[1].Value -eq $mpost.Groups[1].Value){ Write-Error 'BATCH-UNCHANGED' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; if($m.Groups[1].Value -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; foreach($p in $pages){ if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" }; if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" } }; $d93bad=@(); foreach($p in $pages){ $d93lines=@($sec -split "`r?`n" | Where-Object { $_ -match ('^D-93 抽查:'+[regex]::Escape($p)) }); if($d93lines.Count -eq 0){ $d93bad += ($p+':NO-LINE') } elseif($d93lines[-1] -match '发现缺口'){ $d93bad += $p } }; if($d93bad.Count -gt 0){ Write-Error ('D93-GAP '+($d93bad -join ',')) }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($p in $pages){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match "(?<!\r)\n"){ Write-Error "LF-ONLY $p" }; if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $sorted=@($pages | Sort-Object); $joined=($sorted | ForEach-Object { $_ + ':' + ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $_)))).Replace('-','').ToLower()) }) -join "`n"; $h=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($joined))).Replace('-','').ToLower(); if($sec -notmatch ('(?m)^扩写后本批页面聚合哈希:'+$h)){ Write-Error 'POST-HASH-MISMATCH' }; $roadText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md')); $roadHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($roadText))).Replace('-','').ToLower(); $mr=[regex]::Match($np,'(?m)^ROADMAP 全文哈希:([0-9a-f]{64})'); if(-not $mr.Success -or $mr.Groups[1].Value -ne $roadHash){ Write-Error 'ROADMAP-MODIFIED' }; $stText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); $stHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($stText))).Replace('-','').ToLower(); $ms=[regex]::Match($np,'(?m)^STATE 全文哈希:([0-9a-f]{64})'); if(-not $ms.Success -or $ms.Groups[1].Value -ne $stHash){ Write-Error 'STATE-MODIFIED' }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr=@($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $built=@(Get-ChildItem -LiteralPath 'public/_docs/advanced/ii/ui' -Filter *.html -File -ErrorAction SilentlyContinue); if($built.Count -ne 25){ Write-Error ('PAGE-NOT-BUILT:'+$built.Count) }; foreach($s in @('10-49-SUMMARY.md','10-53-SUMMARY.md','10-54-SUMMARY.md')){ ifLine truncated
<fails_when>non-zero exit, or output contains "NOTES-MISSING", "NO-POST-HASH", "NO-BATCH-HASH", "BATCH-UNCHANGED", "NO-MATRIX-SECTION", "MATRIX-STILL-PENDING", "NO-SELF-CHECK", "NO-DONE", "D93-GAP", "MD-COUNT", "DEMO-COUNT", "LF-ONLY", "SCOPE-REDUCTION", "POST-HASH-MISMATCH", "ROADMAP-MODIFIED", "STATE-MODIFIED", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "UNEXPECTED-SUMMARY"; or output lacks "T5-OK"</fails_when>
</verify>
<acceptance_criteria>7 篇的 D-93 覆盖格无 `待补`、逐篇有 `自查:` 与 `已完成扩写:`、`D-93 抽查` 无「发现缺口」;`扩写后本批页面聚合哈希` 与扩写前不同且与重算一致;`本批外文件聚合哈希`、ROADMAP / STATE 全文哈希与基线一致;25 篇 / 24 demo 不变;7 篇 CRLF、无降级表述;prettier / ESLint 0/0 / `docs/` 路径 0 类型错误 / 构建 green + 0 dead link / 25 个 HTML;NOTES 有 `体量参考(扩写后)`(不设 300 行门禁)、`### 10-49 门禁`、`停止点:10-49 扩写结束`;未创建任何 SUMMARY。</acceptance_criteria>
<done>Part 0–1 扩写完成并通过门禁,停在读者循环之前。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 写作者 → 正文 | 扩写必须按 D-93 讲模型与理由,不能退化成参数表或读者问题补丁 |
| 本计划 → 批外文档 | 只允许改 7 篇;其余 18 篇、导览、demo、侧边栏不得改动 |
| 正文 → 源码 | 源码只用于核对模型事实;不写源码叙述,不把注释冲突写进正文 |
| 本计划 → 账本 | 不写 SUMMARY、不改 ROADMAP / STATE、不 commit |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-168 | Tampering | 批外文档被改动 | high | mitigate | Task 1 记录 `本批外文件聚合哈希`;Task 5 重算比对,不一致即停 |
| T-10-169 | Tampering | 页面被新增 / 删除 | high | mitigate | 每次 verify 断言 `docs/advanced/ii/ui` 25 篇、demo 24 个;不新增导航 |
| T-10-170 | Repudiation | 扩写退化为只补读者问题 | high | mitigate | Task 1 建 D-93 四类覆盖表;每篇覆盖格必须 `已讲` 或 `不适用:理由`;Task 5 抽查 |
| T-10-171 | Tampering | 为凑 300 行注水 | medium | mitigate | 体量只记录不设门禁;D-88 写入 NOTES;禁止接口表堆砌与降级表述 |
| T-10-172 | Information Disclosure | 把 Round 1 读者记录交给用户 | medium | mitigate | Round 1 只作内部输入;本计划不产出用户可读的审阅摘要;10-54 明确不提供读者记录 |
| T-10-173 | Repudiation | 越界写 SUMMARY / ROADMAP / STATE | medium | mitigate | Task 5 校验 ROADMAP / STATE 全文哈希与基线一致;禁止创建 SUMMARY |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 关卡门禁:Task 0 已获「可以执行」;NOTES 含 `读者审阅:已完成`。
- 基线门禁:Task 1 写入 7 篇范围、Round 1 计数、基线 HEAD、两个聚合哈希、两个账本哈希、D-93 覆盖表、体量参考。
- 覆盖门禁:7 篇四类内容格为 `已讲` 或 `不适用:理由`,无 `待补`;每篇有 `自查:` 与 `已完成扩写:`;Task 5 的 `D-93 抽查` 无「发现缺口」。
- 范围门禁:`docs/advanced/ii/ui` 25 篇、demo 24 个;`本批外文件聚合哈希` 与基线一致;未改导览、侧边栏、`packages*` / `src`。
- 质量门禁:7 篇 CRLF;prettier `--check`;ESLint 0/0;`docs/` 路径 0 类型错误;`pnpm docs:build` green + `build complete` + 0 dead link;25 个 HTML。
- 体量门禁:只记录逐篇行数与总行数;不设 300 行下限/上限;不因低于 300 行失败。
- 停止门禁:NOTES 有 `停止点:10-49 扩写结束`;未创建 SUMMARY;ROADMAP / STATE 哈希未变;未 commit。
</verification>
<success_criteria>
- Part 0–1 的 7 篇按 D-93 讲清渲染树、事件、元素/组件用法与设计原因,每次代码后有模型解释。
- 读者能从这 7 篇独立复述「组件怎么变成渲染树、坐标/变换怎么传、谁先接事件、缓存什么时候脏」,并能改写示例而不只是照抄。
- 没有新增/删除页面与 demo,没有改动批外文档、导览、侧边栏、源码。
- 门禁全绿,体量只作参考记录,本计划停在读者循环之前。
</success_criteria>
<output>
本计划**不写 SUMMARY**。完成后在对话中报告 7 篇的扩写清单、逐篇行数(体量参考)、D-93 抽查结论与门禁结果,然后停止。读者循环由 `10-53-PLAN.md` 执行,用户审阅由 `10-54-PLAN.md` 执行。
</output>
@@ -0,0 +1,384 @@
# 高级 II · UI 25 篇独立读者审阅记录(10-49)
独立读者按 Part 0→5 顺序只读 25 篇的提问记录,未修改任何文档。
## 读者人格(逐字)
你是一位刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。你完全没写过 UI,不知道 canvas 是什么,也不会 Vue 的组件写法;你只掌握了基础 TS/JS、函数、对象、数组和一点点模板语法。你手里只有这套文档,不能看源码,也没有人可以问。你的任务不是评价文档好坏,而是老老实实按顺序读,读到哪里卡住就记下:我在哪一段卡住、我从文档里已经知道什么、我还缺什么才能继续往下做。
## 阅读范围
- `docs/advanced/ii/ui/ui-template.md` — 进入前提:会写 TS 函数和对象,想先让一个面板显示出来;不知道 canvas 与 DOM 的区别。
- `docs/advanced/ii/ui/container-and-coordinates.md` — 进入前提:已有一个能显示的 `container`、`g-rect`、`text`,想弄清楚 `loc` 六元组和嵌套坐标。
- `docs/advanced/ii/ui/basic-shapes.md` — 进入前提:已会摆容器,想画色块、边框、分隔线。
- `docs/advanced/ii/ui/curves-and-paths.md` — 进入前提:已会矩形、圆和直线,想画曲线、路径、圆角。
- `docs/advanced/ii/ui/text.md` — 进入前提:已会图形,想显示单行文字、字体和居中。
- `docs/advanced/ii/ui/image-and-texture.md` — 进入前提:已会文字和图形,想显示图标、贴图、像素画。
- `docs/advanced/ii/ui/layer-transform-performance.md` — 进入前提:已会摆元素,想处理遮挡、缩放旋转、显示开关和缓存。
- `docs/advanced/ii/ui/reactivity.md` — 进入前提:已能写静态界面,想让数据变化自动更新画面。
- `docs/advanced/ii/ui/events.md` — 进入前提:已会响应式,想接点击、悬停、滚轮。
- `docs/advanced/ii/ui/hotkey-in-ui.md` — 进入前提:已会点击事件,想接 Esc、Enter 这类按键。
- `docs/advanced/ii/ui/conditional-and-list-rendering.md` — 进入前提:已会事件和响应式,想按条件显示、循环生成列表。
- `docs/advanced/ii/ui/props.md` — 进入前提:已会写单个组件,想拆父子组件传数据。
- `docs/advanced/ii/ui/component-tsx.md` — 进入前提:已会 props,想写完整组件、生命周期和 `expose`。
- `docs/advanced/ii/ui/slots-and-attrs.md` — 进入前提:已会组件,想让父组件塞内容、透传属性。
- `docs/advanced/ii/ui/builtin-text-and-input.md` — 进入前提:已会自己拼组件,想用现成的换行文本、说明框、输入框。
- `docs/advanced/ii/ui/builtin-list-and-containers.md` — 进入前提:已用过文本与输入组件,想用现成的列表、分页、滚动、一次性弹窗。
- `docs/advanced/ii/ui/ui-controller-and-stack.md` — 进入前提:已能打开一个面板,想管多个面板的叠放、背景和主 UI。
- `docs/advanced/ii/ui/replace-builtin-ui.md` — 进入前提:已会 UI 栈,想把设置、存档、工具栏换成自己的。
- `docs/advanced/ii/ui/ui-performance.md` — 进入前提:已能搭面板和栈,想知道哪里会卡、哪些开关能省。
- `docs/advanced/ii/ui/inventory-example-1-skeleton.md` — 进入前提:已学完零件(模板、元素、响应式、事件、组件、内置组件、栈),但没把它们装成一个面板;本篇给目标与骨架。
- `docs/advanced/ii/ui/inventory-example-2-grid.md` — 进入前提:已有 720×480 骨架和左右两个占位区,但不知道道具数据、格子和网格怎么填。
- `docs/advanced/ii/ui/inventory-example-3-detail.md` — 进入前提:已有可点击选中的 5 列网格,但右侧仍是占位,不知道详情怎么接选中项。
- `docs/advanced/ii/ui/inventory-example-4-scroll.md` — 进入前提:网格与详情能用,但道具一多左侧放不下。
- `docs/advanced/ii/ui/inventory-example-5-state.md` — 进入前提:面板能看能选,但还不能装备、使用、关闭。
- `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` — 进入前提:功能基本齐了,要做动画、落回五个文件、注册成 UI。
## 逐篇提问
| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 |
| --- | --- | --- | --- | --- |
| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(开头两段与完整模板代码块) | 界面是画布上的框架元素,不是 DOM;TSX 写结构、Vue 管组件与响应式;模板由 Props 类型、Props 列表、组件、`GameUI` 注册四部分组成;四个 import 分别来自 `vue`、`@motajs/system`、`@motajs/render-vue`、`@user/client-base`;注册名是 `'my-panel'`。 | 这个 `.tsx` 文件该放在哪个目录、文件名有没有约束、构建或游戏如何发现它;`export const MyPanelUI` 之后是否还要在别处被 import 或登记;这四个包别名在我的项目里是否已存在、要不要配置。 | 新建一个文件、原样粘进去保存,游戏里就应该能出现面板——但不知道保存后去哪里看,也不知道要不要重启、重新构建或额外注册。 |
| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(`defineComponent` 与 `satisfies` 那一段) | `props` 列表至少含 `controller`、`instance`、`state`;setup 返回 render 函数;组件用 `defineComponent` 包起来;Props 接口同时继承 `IGameUIPropsBase` 与 `DefaultProps`。 | `defineComponent` 的两个参数各是什么、外层那个 `props` 参数从哪里来、为什么里面还要 `return () =>` 再包一层;`satisfies` 与泛型在这里起什么作用;JSX 里 `{/* */}` 注释、`<g-rect fill />` 只有属性名的写法是什么语法;想加自己的字段时改接口还是改列表。 | 原样复制能跑;一旦想改结构或加字段就可能写错,而且按文档提醒属性名写错不报错,我不知道该怎么自查。 |
| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(三个元素的说明与 `loc`) | `loc` 前两项是左上角坐标、后两项是宽高;`g-rect` 要 `fill` 才有填充、`fillStyle` 才是颜色;`text` 的内容放 `text` 属性;`container` 是布局单位也是事件捕获单位。 | 坐标原点在哪、单位是不是像素、`loc` 相对父容器还是相对画布;`480×320` 与游戏画布或窗口是什么关系;面板会出现在屏幕的哪个位置;`g-` 前缀是什么意思;窗口变化后会不会被拉伸或裁掉。 | 按示例填 `480×320` 界面能显示,但不知道会不会超出可视区、换个尺寸该按什么基准算,也不知道面板默认落点在左上还是居中。 |
| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(等价的原生元素代码块) | 同一画面可以用 `Container`、`Rect`、`Text` 手动 `pos`/`size`/`setFillStyle`/`setText`,再 `appendChild` 挂到根容器上。 | 这些类从哪个包 import(上一段只 import 了 `defineComponent`、`GameUI`、`SetupComponentOptions`、`DefaultProps`、`IGameUIPropsBase`);`root` 创建后挂到哪里才可见、是否必须写在某个 `GameUI` 的 render 里;这条路线还需要 `GameUI` 注册吗;两条路线该选哪条、能否混用。 | 直接抄这段会得到一份能编译、但不知道如何让它显示、也不知道缺哪些 import 的代码;也不确定它是不是「不写 Vue 的正式方案」。 |
| docs/advanced/ii/ui/ui-template.md | ## 只改哪几行 与 ## 打开与关闭 | 打开有三处:场景 UI 用 `props.state.sceneController.open(MyPanelUI, {})`、另一个 UI 内用 `props.controller.open(...)`、关闭自己用 `props.controller.close(props.instance)`;主 UI 栈用 `props.state.mainUIController.open(...)`,细节留到后面;没有全局 `client`。 | 第一次让面板出现该挑哪一个;表格写的「主入口 / 另一个 UI 内 / 主 UI 栈」与下一节三个代码段(场景 UI / 另一个 UI / 关闭自己)怎么对应;`open` 第二个参数 `{}` 里能放什么、放进去后怎么在面板里取到;`instance` 是什么、为什么 `close` 要传它;`sceneController` 与 `mainUIController` 从哪来、有什么区别。 | 会在场景 UI 与主 UI 栈之间犹豫,可能先抄场景那条;但不知道面板出现后是否被主界面盖住、是否与主界面同时存在,也不知道怎么把自己的参数带进面板。 |
| docs/advanced/ii/ui/container-and-coordinates.md | 坐标从哪里来 | 根容器左上角是原点,向右为正 x、向下为正 y;子元素相对父容器,每层重新平移 | 这个“根容器”是不是就是游戏画面?我写的 `[0, 0, 480, 320]` 和游戏窗口是什么关系,会不会被缩放 | 把根容器贴到左上角,界面就出现在画面左上角 |
| docs/advanced/ii/ui/container-and-coordinates.md | loc 与锚点 | `loc` 是 x、y、width、height、anchorX、anchorY 六元组,后三项可省略;`anc` 是简写;默认尺寸 200×200 | “后三项可以省略”到底指 height、anchorX、anchorY 三项,还是只指两个锚点?如果我省略宽高,是不是就变成 200×200 | 省略锚点后元素仍在左上角;省略宽高后元素是 200×200 |
| docs/advanced/ii/ui/container-and-coordinates.md | 一个嵌套示例 | 两段等价写法,一段 TSX、一段 `appendChild`;子坐标相对父容器 | 这段 TSX 应该放在哪里?第 1 篇的模板里有 `return () => (...)`,这里却是裸露的标签;`container`、`g-rect` 是全局可用还是要 import | 把嵌套示例整段塞进 render 函数就能看到两个区域 |
| docs/advanced/ii/ui/container-and-coordinates.md | 层级 | `zIndex` 越大越靠上,也影响命中;不改变坐标 | 两个不同父容器里的子元素,`zIndex` 还能互相比较吗?我想让 A 容器里的提示框盖住 B 容器,只给提示框大 `zIndex` 够不够 | 给提示框加大 `zIndex` 就能盖住旁边的容器 |
| docs/advanced/ii/ui/basic-shapes.md | 四个图形 | `g-rect`、`g-circle`、`g-ellipse`、`g-line` 及各自几何属性;元素层对应 `Rect`、`Circle`、`Ellipse`、`Line` | 元素层的这些类从哪里 import?TSX 里的标签又从哪里来?文档只给了类名,没有 import 行 | 照抄类名就能 new 出来并挂到容器上 |
| docs/advanced/ii/ui/basic-shapes.md | 填充与描边 | `fill`、`stroke`、`strokeAndFill` 是模式开关,颜色在 `fillStyle`、`strokeStyle`;线宽、虚线、端点、连接样式 | 如果我同时写 `fill` 和 `stroke` 两个开关,而不是 `strokeAndFill`,会得到什么?文档没说冲突时谁优先 | 同时写两个开关也能得到填充加描边 |
| docs/advanced/ii/ui/basic-shapes.md | 圆角与命中 | 圆和椭圆用 `radius`、`radiusX`、`radiusY`;`actionStroke` 只让描边响应点击 | 这节标题叫“圆角与命中”,可我真正想找的是“矩形圆角”,这里没有;我会以为 `g-rect` 也能给圆角 | 给 `g-rect` 加 radius 想得到圆角矩形,结果文档没这条属性 |
| docs/advanced/ii/ui/curves-and-paths.md | 三次贝塞尔 / 二次贝塞尔 | `g-bezier` 八元数组、`g-quad` 六元数组,顺序固定,长度错不报错但画错 | 这两个元素没有 `loc`,那曲线画在哪个坐标系?我想把整条曲线挪个位置,是改所有点,还是外面包一层容器 | 曲线坐标相对父容器原点,想移动就包容器 |
| docs/advanced/ii/ui/curves-and-paths.md | 路径 | `g-path` 的 `path` 必须是 `Path2D`,不能传字符串;用 `moveTo`、`lineTo` 组路径 | `Path2D` 从哪里来?是浏览器全局对象还是要 import?我的 TS 环境里直接写 `new Path2D()` 会不会报找不到名字?路径能不能用 `loc` 平移 | 直接 `new Path2D()` 就能用,路径从父容器原点开始画 |
| docs/advanced/ii/ui/curves-and-paths.md | 圆角矩形 | `g-rectr` 用 `circle` 或 `ellipse` 指定圆角;`circle` 支持 1 到 4 项,`ellipse` 支持 2、4、6、8 项 | `circle` 三项时“按顺序细分”具体是三口角各一个、第四个跟着谁?`ellipse` 每两个值对应哪个角?我无法从文字推出角与值的映射 | 三项圆角能猜到顺序,但实际四角效果只能试 |
| docs/advanced/ii/ui/text.md | 一行文字 | `text` 属性放内容,`fillStyle` 默认白色;描边用 `strokeStyle` 与 `strokeWidth`,描边计入尺寸 | `Text`、`Font` 从哪个包 import?TSX 里能不能直接写字号,还是一定要造 `Font` 实例 | 照抄 `new Text()` 和 `new Font()` 就能用,但 import 行要自己猜 |
| docs/advanced/ii/ui/text.md | 字体 | `Font` 构造参数顺序 `(family, size, sizeUnit, weight, italic)`;默认值用 `Font.defaults()`,改少量用 `Font.clone` | 怎么设置全局默认字体?`Font.defaultFamily` 这些静态默认值可不可以直接赋值?我只能每个文字都 clone 一遍 | 改静态默认值就能全局生效,或者只能逐个传 `font` |
| docs/advanced/ii/ui/text.md | 尺寸与居中 | 文字宽高由测量决定,给 `width`、`height` 不裁剪;锚点 0.5 让 x、y 落在中心 | 示例同时写了 `loc` 里的两个锚点和外面的 `anchorX`、`anchorY`,重复时以哪个为准?垂直居中算不算行高和描边 | 两种写法结果一样;但如果不一样我也不知道该信哪个 |
| docs/advanced/ii/ui/image-and-texture.md | 图片元素需要什么 | `image` 属性接收纹理对象,`loc` 决定画多大,纹理会被拉伸铺满 | 我只有一张 PNG 图标文件,怎么把它变成纹理对象?文档只教了用 canvas 现画一张,没有讲加载文件 | 我能显示文档里画的棋盘,但放不进自己的图标 |
| docs/advanced/ii/ui/image-and-texture.md | 造一张最小纹理 | `Texture` 来自 `@motajs/render`,接受 `HTMLCanvasElement`、`ImageBitmap`、`HTMLImageElement`;用 `document.createElement('canvas')` 画棋盘 | 我不知道 canvas 是什么,`getContext('2d')`、`fillRect` 只是照抄;文档还提到 `onMounted`,但没介绍它是什么、在哪里写 | 复制这段代码能出棋盘,但换图片源时卡住 |
| docs/advanced/ii/ui/image-and-texture.md | 像素图设置 | `noanti` 关抗锯齿且优先于 `anti`,`hd={false}` 关高清缓存,两者一起关才有硬边 | “高清缓存 / 逻辑像素”是什么意思?如果我的 UI 整体被缩放,`hd={false}` 会不会反而糊 | 像素图按文档设置后边缘变硬 |
| docs/advanced/ii/ui/image-and-texture.md | 应用层素材标签 | 存在 `icon`、`winskin`、`map-render` 三个标签,分别用于图标、窗口皮肤、地图渲染 | 它们“按应用层素材约定使用”,可约定在哪?没有链接也没有示例;我正想做物品图标,却无法从这里继续 | 想用 `icon` 显示物品图标,但不知道标签怎么写、素材放哪 |
| docs/advanced/ii/ui/layer-transform-performance.md | 遮挡:zIndex | `zIndex` 大者后绘制、先命中;不改变坐标与父布局 | 跨容器时是否同一套层叠?父容器没设 `zIndex`,子元素的大 `zIndex` 能不能压过另一个后绘制的容器 | 提示框放在列表容器里也能盖住外层其他区域 |
| docs/advanced/ii/ui/layer-transform-performance.md | 变换:scale、rotate 与 alpha | `scale` 必须两元数组,`rotate` 用弧度,`alpha` 为 0 到 1,绕锚点变换 | 缩放容器时子元素和命中区域会一起缩放吗?旋转后点击区域还是原来的矩形吗 | 缩放容器后里面文字和按钮都跟着缩,点击位置也对 |
| docs/advanced/ii/ui/layer-transform-performance.md | 显示开关:优先 hidden | `hidden` 不显示不交互但保留状态;三元会卸载并重置状态;给了选用场景清单 | `const open = ref(true)` 里的 `ref` 从哪来?这一篇在第 8 篇之前就用了响应式和 `onClick`,我照抄会不知道缺什么 | 照抄开关示例就能点开面板,但实际会因没引入 `ref` 卡住 |
| docs/advanced/ii/ui/layer-transform-performance.md | 缓存:cache 与 nocache | 默认缓存 `container`、`custom`、`container-custom`;默认不缓存 `text`、`image`、`template` 和全部 `g-*`;`nocache` 优先 | 缓存后“让元素知道自己脏了才会重绘”,可怎么让它知道?改文字、换颜色、滚动列表后要不要手动标脏 | 给静态面板开缓存会变快,但动态内容可能停在旧画面且我不知道怎么修 |
| docs/advanced/ii/ui/layer-transform-performance.md | `noevent:可见但不接收交互`;`filter 与 composite` | `noevent` 继续绘制但跳过命中,事件下穿,`cursor` 失效;`filter` 与 `composite` 两个属性存在,接受滤镜字符串与混合模式,取值很多、入门不必记 | 把 `noevent` 加在容器上,是整棵子树都不接收,还是只容器自身?遮罩里的子元素还能点吗;具体有哪些可用值?文档明确说再查,但没说去哪里查 | 弹窗遮罩加 `noevent` 后,下面所有按钮恢复可点;做暗色遮罩用 `alpha` 就够,暂时不用这两个 |
| docs/advanced/ii/ui/reactivity.md | `## ref:带 value 的盒子`(第 15–35 行示例) | `ref` 读写要写 `.value`;点击改 `count.value`,渲染函数里读它就记录依赖;`defineComponent` 返回 render 函数 | 第 1 篇说 UI 组件必须继承 `IGameUIPropsBase` 配 `DefaultProps`、props 列表要有 controller/instance/state、还要 `new GameUI(...)` 注册;这里的 `defineComponent(() => ...)` 既没有 props 参数也没有第二参数和注册。我不知道它算不算一个能打开的 UI | 直接把这段当面板用,发现没有可打开的入口;套回第 1 篇模板后,又不知道 `ref` 该写在 setup 的哪一步、结构怎么并进原来那份 TSX |
| docs/advanced/ii/ui/reactivity.md | `## reactive:一整块对象`(第 50–71 行) | `reactive` 返回代理,字段读写不用 `.value`;不能整体替换;解构丢响应式,要逐字段赋值 | 这段 `const panel = reactive(...)` 写在哪一层?模块顶层、`setup` 内、还是渲染函数外?写模块顶层时,打开两个面板会不会共用同一份 `panel` | 放在模块顶层后,开两个面板改一个另一个跟着变;或者放在组件内却每次重渲染都被重建,两种结果我都不知道哪个才是文档意图 |
| docs/advanced/ii/ui/reactivity.md | `## watch:副作用`(第 103–117 行) | `watch(源, (next, prev) => ...)`,数据变化后执行回调,适合日志/同步/一次性动作 | 组件卸载时 watch 要不要手动停?文档只对快捷键作用域说了自动清理,对 watch 一句没提 | 反复开关面板后旧回调还在跑、越积越多;我不知道该不该把返回的停止函数存起来 |
| docs/advanced/ii/ui/reactivity.md | `## 什么时候用 shallowRef 与 markRaw`(第 119–126 行) | 大对象整体替换用 `shallowRef`;外部实例用 `markRaw`;不确定就先用 `ref`/`reactive` | 第 6 篇的 `Texture`、画布这类对象算不算「外部实例」,要不要 `markRaw` 包一层再塞进组件?两篇之间没有一句话把它们接起来 | 把纹理放进 `ref` 后不确定会不会被 Vue 深层代理、会不会变慢或行为异常,只能先不管 |
| docs/advanced/ii/ui/reactivity.md | `## props 不要解构`(第 128–140 行) | 不要解构 `props`,直接读 `props.title`;完整写法在第 12 篇 | 本篇所有示例都没出现 props 参数,我不知道在 `defineComponent(() => ...)` 里 `props` 从哪来、要不要先声明 props 列表才收得到 `title` | 照着写 `props.title` 会拿不到值或类型报错,只能先跳过这段、等第 12 篇 |
| docs/advanced/ii/ui/events.md | `## 事件对象`(第 32–59 行) | `offsetX/offsetY` 相对触发元素,`absoluteX/absoluteY` 相对画布;`identifier` 区分多指;`type` 是按键种类;`buttons` 是位组合,判断左键要用位运算 | `type` 的可选值到底是什么(数字、字符串还是枚举)?判断左键该写 `ev.type === ?`?`buttons` 的左键位掩码是多少?文档只说「用位运算」,没给常量 | 想实现「只响应左键」时无从下手,只能先对所有按键都响应,或者去猜魔法数字 |
| docs/advanced/ii/ui/events.md | `## 捕获与冒泡`(第 61–77 行) | 捕获从外层向内、冒泡从内向外;`stopPropagation()` 分阶段阻止且不阻止同一元素其它监听器;示例给了父 `onClickCapture` + 子 `onClick` | 示例里父容器的捕获和子元素的冒泡到底谁先执行?正文那句「子元素先捕获、父元素后冒泡」让我拿不准顺序;同一元素上 `onClick` 与 `onClickCapture` 的相对顺序也没说 | 照抄写日志时,最后显示的值和我以为的执行顺序相反,我却判断不出是自己理解错还是写法有问题 |
| docs/advanced/ii/ui/events.md | `## 一组完整的交互`(第 116–154 行) | 用 `ref` 驱动颜色、光标、滚轮累计;事件回调只改 `ref`,画面由渲染函数按当前值生成 | 这段同样是裸 `defineComponent`,没有 props、没有 GameUI 注册,我不知道它作为「完整交互」能不能直接挂进游戏;也不知道 `onWheel` 在子元素铺满父容器时还能不能触发 | 放进文档 demo 能跑,搬进真实面板后整块打不开,或者滚轮完全没反应 |
| docs/advanced/ii/ui/events.md | `## enter 与 leave 不走普通冒泡`(第 79–81 行) | enter/leave 由根节点悬停集合统一触发,不按普通冒泡传递;父级要感知就自己在父级挂 | 鼠标从父容器移到它的子元素上,会不会触发父级 leave 再 enter?父子之间的悬停边界怎么算?文档没给判定 | 做悬停高亮时,鼠标扫过子元素导致父级反复 enter/leave,画面闪烁,我不知道该怎么规避 |
| docs/advanced/ii/ui/events.md | `## actionStroke:只把描边算作命中`(第 112–114 行) | 加 `actionStroke` 后只有描边算命中,内部区域下穿 | 描边只有 1px 时,命中区是不是也只有 1px、有没有最小命中宽度?第 3 篇说它不改绘制,但没说命中宽度是否跟 `lineWidth` 走 | 细边框几乎点不中;我不知道该不该配合加大 `lineWidth`,加大又会让视觉变粗 |
| docs/advanced/ii/ui/hotkey-in-ui.md | `## useKey:拿到当前组件的作用域`(第 21–28 行) | `useKey` 必须在 `setup` 中同步调用,返回当前组件的按键实现对象;组件卸载自动离开;可以直接用非空断言 `!` | `useKey` 从哪个包 import?这段没有 import;`props.state.hotkey.system` 这条路径也没解释(第 1 篇只说 `props.state` 是 ClientCore);这段该放在 `defineComponent` 的哪个位置也没说 | 复制后编译报 `useKey` 未定义,或者 `props` 在该作用域根本不存在 |
| docs/advanced/ii/ui/hotkey-in-ui.md | `## implement:把指令接到回调`(第 32–46 行) | `implement` 可连续调用、返回对象本身;同一次挂载对同一指令重复 implement 会覆盖 | 指令 id 拼错、或指令还没注册就 implement,会发生什么(报错还是静默)?文档没说 | 写了 `@common/exit` 按 Esc 没反应,我分不清是 id 错、作用域没挂上,还是被上层界面抢先处理了 |
| docs/advanced/ii/ui/hotkey-in-ui.md | `## 触发方式:HotkeyEmitMode`(第 74–82 行) | 三种模式:默认 `KeyUp` 抬起、`Once` 按下一次、`Continuous` 按住持续并配合 `interval` 控制最小间隔 | `interval` 写在哪个字段、单位是毫秒还是帧、默认多少?`addCommand` 的完整配置项也没列全(目前只见过 defaults/mode/priority/block) | 想做「按住连续翻页」时不知道 `interval` 怎么填,只能反复试数字 |
| docs/advanced/ii/ui/hotkey-in-ui.md | `## 优先级与阻断`(第 84–95 行) | `priority` 越高越先执行,目前只对抬起触发有效;`block` 阻断更低优先级;同优先级全部执行、不互相阻断 | 同时挂着多个界面(主界面 + 弹出面板)时,它们的按键作用域怎么排序?`priority` 是全局比较还是只在同一作用域内比较?文档没说 | 面板打开时按 Esc,可能同时关掉面板和下层界面,或者关掉的根本不是我以为的那一层 |
| docs/advanced/ii/ui/hotkey-in-ui.md | `## 注册新指令与分组`(第 48–72 行) | `addCommand(id, 显示名, { defaults, mode })`;`setGroup(id, 显示名, [指令])`;`defaults` 是二维数组,组内最后一个是主按键,前面的要先按住;不分组也能用 | 组合键的实际写法没有示例(例如 Ctrl+S);`KeyCode` 还有哪些值、能不能用字符串代替也没说 | 想加 Ctrl 组合键时不知道数组该怎么排,只能先只做单键 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 循环:用 map 生成元素`(第 50–65 行) | TSX 没有循环指令,用 `labels.map(...)` 返回元素数组;固定顺序、无内部状态的列表不需要 key | 这段 `{ labels.map(...) }` 应放在渲染函数的哪个位置、外面要不要包 `container`?示例是游离表达式,不是完整 return;map 出来的元素是否必须有父容器也没说 | 直接贴进 render 会结构不对,或者元素没有父容器导致定位异常 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## key:只在需要保留身份时加`(第 67–96 行) | 会增删、重排且需要保留身份时用稳定 id 作 key;不要用数组下标代替会变化的身份;无状态固定列表不加 | 怎么在 `ref` 数组上做增删(push / splice / 整体替换)才会触发更新?文档只给了初始 `ref<Row[]>([...])` 和渲染,没有修改示例 | 往 `rows.value` 里 push 一项后界面不刷新,或刷新行为和预期不同,只能猜哪种改法有效 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 三种写法怎么选`(第 98–105 行) | 四种组合的条件与结果对照:hidden 保留状态、三元重置、固定列表 map 不要 key、动态列表 map + key | 列表项如果是自定义组件(不是 `text` / `g-rect`),key 写在哪一层、是否和普通元素一样?表格没覆盖组件项 | 给组件列表加 key 时不确定加在组件标签上还是外层容器上,可能加错层级导致状态仍然错位 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 条件:优先 hidden`(第 5–25 行) | `hidden` 不显示、不交互但保留元素与状态;频繁开关的面板用它 | `hidden` 的元素还占不占布局位置、会不会影响兄弟元素定位?第 2 篇说坐标相对父容器,我猜不影响,但这一篇没有确认 | 隐藏上方区域后,不确定下面的元素会不会上移;如果会,我就得改用三元 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 边界与注意`(第 125–130 行) | hidden 元素仍在树里;三元成本在初始化与状态重置;map 每项结构要稳定;key 不是性能开关也不是修重挂载的手段 | 「不要在同一处混用不同标签却不给 key」和前文「固定顺序无状态不需 key」的边界在哪?什么算「混用不同标签」 | 列表里同时有 `text` 与 `g-rect` 时,不确定要不要补 key,加了又怕违背「无状态不要加」 |
| docs/advanced/ii/ui/props.md | L35–L48:`SetupComponentOptions<ItemCellProps, ItemCellEmits, keyof ItemCellEmits>` 与 `defineComponent<...>` 的三个泛型 | 第 1 篇的模板只写了一个泛型 `defineComponent<MyPanelProps>(props => ..., propsList)`;第 12 篇说要先声明 Props 接口,再把用到的键列进 `props` 数组。 | 第二个泛型 `ItemCellEmits` 和第三个 `keyof ItemCellEmits` 分别代表什么;`keyof` 在这里为什么能当第三个参数;什么时候必须写满三个、什么时候一个就够。文档没有一处把泛型顺序讲成一句话。 | 照抄 `ItemCell` 能跑;但自己新建一个组件时不知道该复制几个泛型,可能只写一个泛型、把 `emits` 漏掉,或把 `keyof` 写错位置。 |
| docs/advanced/ii/ui/props.md | L91–L93 与 L175–L182:父组件写 `v-model:selected={pickedA.value}` / `v-model:open={open.value}` | 第 1、11、13 篇都反复说“TSX 里没有模板指令”;第 12 篇说 `update:xxx` 只通过 `v-model:xxx` 消费,等价于“传入值并在子组件发出 `update:xxx` 时写回”。 | 既然 TSX 里没有模板指令,`v-model:selected` 这串东西在 JSX 属性位置到底怎么被识别;它写回的是 `pickedA.value` 还是 `pickedA`;为什么同篇又说“属性名必须 camelCase”,而这里 `v-model:selected` 带冒号。 | 照写后不确定 `v-model:selected` 会真正建立双向绑定,还是被当成一个普通属性透传下去;可能退回去手写 `selected` 加 `onUpdate:selected`,又和文档“不要写成手动监听”冲突。 |
| docs/advanced/ii/ui/props.md | L233:边界与注意里的“属性会落到 `attrs` 而不是 `props`” | 第 1 篇说 props 数组少写一个键就拿不到值;第 12 篇说漏写键名等于没传。 | `attrs` 是什么、在哪个对象上、是不是自动生效;这一篇只提了一句,定义要到第 14 篇才出现。 | 传了 `size` 却没生效时,不知道该先查 `props` 数组、`attrs`,还是属性名大小写;照抄时容易把“漏写键名”误判成组件没渲染。 |
| docs/advanced/ii/ui/props.md | L112–L129:`const size = props.size ?? 64` 与 `computed(() => props.size ?? 64)` 的差别 | 知道默认值用 `??`,不能给 props 赋值;setup 顶部读一次只保留挂载时的值,`computed` 会跟着 props 更新。 | 示例里的 `size` 正好是“不会变的基础尺寸”,但父组件示例又给三个格子传了不同的 `size`;如果父组件之后改 `size`,哪个写法会重画、哪个不会,需要自己从“读一次”推断。 | 照抄 `const size = props.size ?? 64` 并把 `size` 用在 `loc` 里,父组件后续改 `size` 时格子不变化,容易当成渲染失败。 |
| docs/advanced/ii/ui/props.md | L78–L94:父组件直接写 `<ItemCell ... />`,但没有 import 片段 | 知道 TSX 里元素标签是小写的 `g-rect`/`text`;知道父组件准备数据、子组件通过 props 接收。 | 大小写标签的规则没有被明确说出;`ItemCell` 从哪里 import、组件和普通元素在 TSX 里靠什么区分;父组件这段代码是否要放进 render 函数。 | 复制父组件片段时会缺 import,或把 `<ItemCell>` 当普通元素理解,导致不知道该怎么在页面里注册/引入子组件。 |
| docs/advanced/ii/ui/component-tsx.md | L31–L44 与 L111–L133:有的 `defineComponent` 带第二个参数,有的不带 | 第 12 篇的 `ItemCell` 和本篇的 `ItemCell`/`Card` 都传了第二个参数 `itemCellProps`/`cardProps`;本篇 `Ticker` 写的是 `defineComponent(() => {...})`,没有第二个参数。 | 第二个参数在什么时候可以省略;没有 props 的组件是否必须写一个空 options;省略后还会不会生成 props 数组、`emit` 还能不能用。文档只展示了两种写法,没有给判断规则。 | 自己写一个无 props 的小组件时,可能完全不写第二个参数;一旦以后要加 prop,又不知道是该补 options 还是靠别的方式声明。 |
| docs/advanced/ii/ui/component-tsx.md | L157–L212:`expose` 与父组件 `const card = ref<CardExpose>()`、`<Card ref={card} ... />` | 知道 `emit` 是子发父、`expose` 是父调子;知道第 8 篇的 `ref` 是带 `.value` 的响应式盒子。 | `ref<CardExpose>()` 什么时候被赋值、由谁赋值;`expose` 暴露的对象和 `ref` 之间是谁绑定的;父组件片段只 import 了 `ref`,`CardExpose`/`Card` 从哪来;`ref={card}` 在 TSX 里是不是普通属性。 | 照抄后点按钮调用 `card.value?.focus()` 可能一直是 `undefined`,或 `card.value` 拿到的是整个组件实例而不是 `{ focus }`;不知道要不要等 `onMounted`。 |
| docs/advanced/ii/ui/component-tsx.md | L104–L141:`onMounted` / `onUnmounted` 与 `window.setInterval` | 知道生命周期钩子要在 setup 体内同步调用;在 `onMounted` 里建监听/定时器,在 `onUnmounted` 里清;第 6 篇也提过纹理放 `onMounted`。 | “同步调用”具体指不能放在 `await` 之后还是不能放在回调里;`window.setInterval` 返回的 `number` 与浏览器/Node 类型差异;示例的 `let timer: number \| undefined` 为什么不用 `null`。 | 照抄定时器能跑;但把 `onMounted` 写进一个 `async` 函数或事件回调时,会静默不生效,读者不知道是自己写错还是环境问题。 |
| docs/advanced/ii/ui/component-tsx.md | L216–L230:组件与 UI 的区别表 | 知道普通组件只需继承 `DefaultProps`,UI 必须同时继承 `IGameUIPropsBase` 与 `DefaultProps`,且 props 数组包含 `controller`/`instance`/`state`;知道 UI 由 `GameUI` 注册。 | 把面板拆成普通组件后,`controller`/`instance`/`state` 要不要作为 props 往下传;普通组件如果需要关闭面板,应该自己发 emit 还是接收 controller。 | 按“普通组件不需要这三个值”去拆背包面板,拆到一半发现子组件里的关闭按钮拿不到 `controller`,再回头改 props 接口。 |
| docs/advanced/ii/ui/slots-and-attrs.md | L24–L37:`SlotsType`、`defineComponent<PanelProps, {}, string, PanelSlots>` 的四个泛型 | 第 12/13 篇已经见过一个泛型和三个泛型;知道 props 接口、emits 接口。 | 第二个泛型 `{}`、第三个 `string`、第四个 `PanelSlots` 各对应什么;为什么这里没有 emits 却要写 `string`;四个泛型的顺序从哪来。文档没有解释 `string`,也没有解释 `SlotsType` 与第四个泛型的关系。 | 照抄 `Panel` 能编译;自己写一个同时有 emits 和 slots 的组件时,不知道 `emits` 该放第二个还是第三个泛型,容易把类型放错位置导致 props/emit 推断全错。 |
| docs/advanced/ii/ui/slots-and-attrs.md | L29–L35 与 L113–L122:手写 `PanelOptions` / `FieldOptions` 代替 `SetupComponentOptions` | 第 12 篇明确说第二个参数由 `SetupComponentOptions` 约束,`props` 数组和 `emits` 数组都在这里声明;第 13 篇也照这个写法。 | 为什么第 14 篇改成自己声明 `interface PanelOptions { props: (keyof PanelProps)[] }` 和 `interface FieldOptions { props: ...; inheritAttrs: boolean }`;两套写法是否等价、能不能混用;`props: []` 空数组是否合法。 | 照抄 `Panel` 后,再写下一个组件时不知道应该用 `SetupComponentOptions` 还是手写 options;可能两套都写,或漏掉 `emits` 的类型约束。 |
| docs/advanced/ii/ui/slots-and-attrs.md | L61–L90:默认 slot 用标签之间内容,具名 slot 用子节点位置上的对象 `{{ title: ..., default: ... }}` | 知道 slot 在 TSX 里是函数;子组件用 `slots.default?.()`、`slots.title?.(...)` 调用;知道 `?.` 不能省。 | 父组件把具名 slot 写成“标签之间的一个对象”依据是什么;这个对象会被当成普通子节点、还是被 Vue 识别成 slots;默认 slot 的 `<text>` 与具名 slot 的对象能否同时出现、顺序有没有要求。 | 照抄具名 slot 时可能把对象当成普通 children 传下去,结果 Panel 里什么都不显示;或者默认内容与具名对象混写后只有一个生效。 |
| docs/advanced/ii/ui/slots-and-attrs.md | L106–L137:`attrs` 与 `{...attrs}` 透传、`inheritAttrs: false` | 知道没有被 props 声明、也没有被 emits 消费的属性会进入 `attrs`;可以 `{...attrs}` 原样交给内部元素;属性名仍然是 camelCase,透传不做转换。 | `attrs` 是不是响应式、父组件后续改属性时内部 `<text>` 会不会更新;`loc` 这种数组属性展开后是否原样可用;`inheritAttrs` 默认行为下属性会不会“既落根元素又落 text”两份;示例里的 `Font` 没有 import。 | 写 `<Field loc={...} fillStyle={...} />` 后,不确定属性最终落在 `Field` 的根元素还是内部 `text`,可能看到重复定位或样式不生效。 |
| docs/advanced/ii/ui/slots-and-attrs.md | L98–L102:作用域 slot 的数据由子组件传入 | 知道子组件调用 `slots.default?.({ count: 3 })`,父组件函数参数里拿到 `data`;知道 slot 类型写成 `(data: PanelData) => VNode`。 | 父组件函数参数的类型如何与子组件的 `PanelData` 对齐;如果父组件不写类型、或子组件改了传参结构,TS 会不会报错、运行时会不会静默变成 `undefined`。 | 照抄后能显示;但把 `count` 改名或加字段时,父组件可能仍按旧字段读,画面显示 `undefined` 而不知道是类型没接上。 |
| docs/advanced/ii/ui/builtin-text-and-input.md | `## TextContent:会换行的文字` 中 `loc={[40, 40]}` 与 `width={360}` | 知道 `width` 是必填的最大宽度,`autoHeight` 让高度跟内容走,`loc` 负责定位 | 不知道 `loc` 里的宽高和 `width` 是什么关系;`autoHeight` 时 `loc` 的 height 还要不要写;不写 height 会不会落到默认 200 | 照抄后能看到文字,但一旦想把它放进固定高度的区域,就不知道该改 `loc` 还是改 `width`,也不知道最终高度由谁决定 |
| docs/advanced/ii/ui/builtin-text-and-input.md | `## TextContent` 中 `interval={40}` | 知道 `interval` 是逐字显示的间隔,省略或为 0 时直接显示全部 | 不知道单位是毫秒还是别的;40 是快还是慢;也不知道能不能中途改速度 | 复制后只能凭感觉调数字;想做“快进/慢速”时没有依据 |
| docs/advanced/ii/ui/builtin-text-and-input.md | `## Textbox:带背景与标题的说明框` 中 `TextboxStore.get('task-box')` | 知道组件内部为每个文本框建了 `TextboxStore`,可按 id 取回控制器并 `setText` | 不知道在哪里给 `Textbox` 设置这个 id;示例里的 `Textbox` 没有 `id`、`name` 或类似属性 | 照抄 `TextboxStore.get('task-box')` 会拿不到东西,因为我不知道该把 `'task-box'` 写在哪 |
| docs/advanced/ii/ui/builtin-text-and-input.md | `## Input:在画布上输入` 的“点击位置创建真实的输入框并对齐到画布,失焦后收起” | 知道 `Input` 用 `v-model:value`,有 `multiline`、`placeholder`、`border` 等属性 | 不知道“收起”后画布上还显示什么;值还在不在;如果一个表单有五个字段,点第二个时第一个会不会消失 | 以为 `Input` 是常驻输入框,实际点别处就看不到,可能做出“字段消失”的界面而不知道为什么 |
| docs/advanced/ii/ui/builtin-text-and-input.md | `## 特殊组件 InputBox:单次输入` 与 `## 边界与注意` | 知道 `getInput` 返回 `Promise<string>`,`getInputNumber` 返回 `Promise<number>`,确认后 `await` 拿结果;边界说面板提前关掉要自己处理“没有结果” | 不知道取消或关闭弹窗时 Promise 是 resolve 空串、resolve undefined,还是 reject;也不知道 `getInputNumber` 解析失败时返回什么 | 写 `const name = await getInput(...)` 后无法区分“用户没输入”和“用户输了个空串”,`try/catch` 也不知道该不该写 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | `## List:可选中的列表` 的“初始选中项以列表第一项为准” | 知道 `list` 是 `[id, 文本]`,`v-model:selected` 绑定选中 id;点击行会切换;初始以第一项为准,挂载后改绑定不会重选 | 不知道示例里 `ref('weapon')` 到底有没有作用;如果我从存档恢复 `'armor'`,该走什么“列表自己的交互”;父组件怎么知道实际选中了第一项 | 设 `selected.value = 'armor'` 后界面仍选第一项,父组件拿到的是 `'armor'` 还是 `'weapon'` 无法确定 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | `## ListPage:左列表、右详情` 的 `close`、`closeLoc` | 知道 `close` 显示关闭按钮,`closeLoc` 调整按钮位置,`right` 把列表放右边,`basis` 是左侧比例 | 不知道 `closeLoc` 的取值格式和坐标系:是相对 `ListPage` 的四元组,还是绝对画布坐标;也没有示例 | 想移动关闭按钮时不知道写什么,只能不动或反复试 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | `## Page:分页` 的默认 slot 写法 | 知道页码从 0 开始,`pages` 是总页数,默认 slot 收到页码索引;14 篇学过默认 slot 内容写在标签之间、具名 slot 用对象 | 不知道这里为什么把函数直接当 children(`{(index) => ...}`),而 `ListPage` 用 `{{ default: fn }}`;两种写法分别什么时候用 | 照 `Page` 写函数、照 `ListPage` 写对象,混用时可能什么都不显示,也不知道该改哪边 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | `## Scroll:只对直接子元素做虚拟滚动` 的“只渲染视口附近的直接子元素” | 知道子元素要平铺,不能用一个容器包住全部;每个子元素有自己的 `loc`;暴露 `scrollTo` 与 `getScrollLength` | 不知道 `Scroll` 怎么得到总高度和行高:是靠子元素 `loc` 推出来,还是要额外给高度;变高行怎么办;`scrollTo(y)` 的 y 是内容像素还是行号 | 平铺 30 行能滚,但想“跳到第 20 行”时不知道 y 该算成 `20 * 28` 还是别的;滚动条长度也无法预期 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | `## 特殊组件 ConfirmBox 与 Choices` | 知道 `getConfirm` 返回 `Promise<boolean>`,`getChoice` 返回选中 key;`maxHeight` 超了会分页;`selected` 是默认索引 | 不知道用户直接关掉弹窗时返回什么;`getChoice` 取消时是 undefined 还是 reject;`getConfirm` 的完整参数顺序也没有单独列出来 | `if (yes)` 可能永远等不到结果,或 `choice` 类型对不上;不敢把一次性弹窗接到关键流程里 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 打开与关闭` 与 `## 背景` 的 `showBack` / `showingBack()` / `showBackground` / `hideBackground` | 知道 `active` 和 `showBack` 是引用值,TSX 里读 `.value`;`showingBack()` 返回背景最终是否显示;`hideBackground` / `showBackground` 是用户设置 | 不知道 `showBack.value` 和 `showingBack()` 什么时候会不同;想显示“背景现在可见吗”到底读哪个;四个名字太像,分不清谁改用户设置、谁读系统状态 | 在文字里写 `props.controller.showBack.value`,可能读到的是用户开关而不是最终结果,背景明明没显示却显示“已显示” |
| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 显示策略` 的 `showCustom(new MyStrategy())` | 知道默认 `lastOnly`,`showAll` 全部显示,`showCustom` 接收自定义策略;关闭时是否连带关闭由策略决定 | 不知道 `MyStrategy` 要实现什么接口、有哪些方法、返回什么;文档没有给最小自定义策略示例 | 需要“只叠两层、第三层替换第二层”这类特殊叠放时无法下手,只能退回 `lastOnly` 或 `showAll` |
| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 基础 props 注入` 的 `setPropsBaseCreator` | 知道控制器通过它给每个实例注入基础参数;示例返回 `{ instance, controller }`;UI 的 props 数组必须有 `controller`、`instance`、`state` | 不知道 `state` 是系统另外注入,还是也要 creator 返回;自定义 creator 会不会把 `state` 弄丢;`state` 到底从哪来 | 照示例写 creator 后,所有 `props.state.sceneController.open(...)` 都可能变成 undefined,但文档没有提示这一点 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 当前没有全局注册 / 覆盖入口` 与第 1 篇的 `new GameUI('my-panel', ...)` | 知道 `GameUI` 把名字和组件绑在一起;打开时靠传进去的对象;当前构造 `GameUI` 不会自动登记,所以不能按名字取回内置 UI | 不知道名字现在还有什么用;重名会不会冲突;是否必须唯一;调试时能不能靠名字找到实例 | 以为名字可以用来按名打开或覆盖,结果发现只能持有对象;如果两个 UI 同名,我不知道会不会出问题 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | `## keep:切换时不闪背景` | 知道 `keep()` 在 close 与 open 的间隙保持背景,`safelyUnload()` 栈空才关,`unload()` 无条件关 | 不知道如果中间 `open` 抛错、提前 return 或用户取消,需不需要 `try/finally` 保证 unload;keep 对象能不能重复使用 | 切换流程一旦失败,背景可能一直留着;我不知道该怎么恢复,只能刷新整个界面 |
| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法一:在打开处替换` | 知道内置 UI 指 `src/client/ui` 的应用层界面,例如设置、存档、工具栏;替换就是找到 `open` 那一行,把 `SaveUI` 换成 `MySaveUI` | 不知道 `SaveUI` 从哪个模块 import、导出名是什么;文档只给名字,没有给路径;我也不能读源码 | 想替换存档界面,却找不到可以 import 的 `SaveUI`;只能猜路径,猜错就编译失败 |
| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法二:包装组件` 的 `defineComponent<MyPanelProps>((props, { attrs, slots, emit }) => ...)` | 知道包装要转发 props、attrs、slots、emits,对外契约不变;`OriginalPanel` 是原组件 | 不知道包装组件没有 `props` 数组时,父组件传的值到底进 `props` 还是 `attrs`;`{...props}` 与 `{...attrs}` 会不会重复;没有声明 `emits` 能不能 `emit('change')` | 照抄后父组件的某些设置不生效,或 `change` 事件不触发;我不知道该补 `SetupComponentOptions` 还是该改展开顺序 |
| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法二` 的 `interface MyPanelProps extends OriginalPanelProps {}` | 知道要保留原契约,所以包装的 Props 继承原 Props | 不知道 `OriginalPanelProps` 从哪里来;如果原 UI 是用 `GameUI` 注册的,包装的是里面的组件还是 `GameUI` 本身;原组件的 props 类型有没有导出 | 写不出 `extends OriginalPanelProps`,也不知道该不该自己重写一份 Props;包装方案卡在第一步 |
| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法三:改显示策略或背景` | 知道 `showAll()` 让栈里 UI 同时显示,`setBackground` 换稳定背景;这些是控制器接口 | 不知道这些调用应该写在哪一层:主入口、场景 UI、还是某个面板里;如果我只想改内置设置面板的叠放,而不改它的组件,代码放哪里才会影响它 | 把 `showAll()` 写在自己面板里,可能只影响当前控制器;不确定是否影响内置 UI 所在的栈 |
| docs/advanced/ii/ui/replace-builtin-ui.md | `## 运行效果` | 知道示例并排对比 `lastOnly` 与 `showAll` 的叠放效果 | 示例没有演示“替换”本身:看不到 `MySaveUI` 替换 `SaveUI`,也看不到包装组件转发 props 的效果 | 看完仍无法确认自己的替换是否成功,只能等真正接到客户端里试 |
| docs/advanced/ii/ui/ui-performance.md | `## 症状与排查` 与 `## 边界与注意` 的“先测再改” | 知道卡顿先查大子树和缓存,切页闪烁查背景和 keep,频繁重建查 open/close,列表掉帧查是否平铺 | 不知道怎么测:没有 FPS、帧耗时、绘制次数、日志或性能面板的用法;也没有“改前/改后”怎么对比 | 只能凭感觉改,改完不知道是真的更快还是心理作用;症状表给了方向但没法验证 |
| docs/advanced/ii/ui/ui-performance.md | `## 缓存:cache 与 nocache` | 知道 `container`、`custom`、`container-custom` 默认缓存;`text`、`image`、`g-*` 默认不缓存;`nocache` 优先 | 不知道如果 `container` 里有每帧变化的 `text`,父容器的默认缓存会不会让整块不更新;要不要给父 `container` 加 `nocache`;脏标记会不会传到缓存的父级 | 做动画文字时可能文字不刷新;不知道该关父容器缓存还是把文字拆出去 |
| docs/advanced/ii/ui/ui-performance.md | `## 列表与分页` 的“规则见 `dev.md`” | 知道大量列表优先 `Scroll`、分页优先 `Page`;`key` 只在会重排、插入、删除且需要保留身份时加;11 篇也讲过类似规则 | 不知道 `dev.md` 是什么、在哪里;我手里只有这套 UI 文档;`Scroll` 示例又给每行加了 `key={index}` | 读到“见 dev.md”会停一下;不确定该按 11 篇的规则还是按 `Scroll` 示例写 `key` |
| docs/advanced/ii/ui/ui-performance.md | `## 基础 props` 的“自定义 `createPropsBase`” | 知道每个实例渲染都会走一次基础参数创建,creator 里不要做重活;读状态、算大数组、创建对象放到别处 | 不知道 `createPropsBase` 和 17 篇的 `setPropsBaseCreator` 是不是同一个东西;自定义时方法名到底写哪个;怎么把“现成的值”装进去也没有示例 | 按 19 篇的名字去找方法找不到,或写错名字不生效;也不知道该在哪里预先算好值 |
| docs/advanced/ii/ui/ui-performance.md | `## UI 栈` 的“`keep` 用完必须卸载” | 知道能 `hide`/`show` 就不重建;稳定背景用 `setBackground` 移出栈;`keep` 只在关一个开一个的间隙用,用完 `safelyUnload()` 或 `unload()` | 不知道异常路径怎么保证卸载;如果中间 `open` 失败,`keep` 是否还在;要不要 `try/finally` | 和 17 篇一样,切换失败后背景一直留着,不知道怎么恢复 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 先把文件拆好`(五个文件的表格 + “其余四个文件先留空或放占位组件”) | 最终拆成 5 个文件;`InventoryPanel` 是唯一被 `GameUI` 注册的组件,其余四个是普通子组件;本篇只写 `inventory-panel.tsx`。 | 这 5 个文件该放在项目的哪个目录、文件名和路径有什么约定、其它四个占位文件最小要写成什么样才能通过编译;全篇没有出现任何 `import` 路径或目录说明。 | 我会在自己项目里新建一个目录放这 5 个文件,但不知道构建会不会自动找到它们;四个空文件可能直接编译失败,连骨架都跑不起来。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 骨架代码`(`<g-rectr ... fill ... stroke ...>`) | `fill` / `stroke` / `strokeAndFill` 是模式开关,颜色由 `fillStyle` / `strokeStyle` 给;`g-rectr` 默认填充;圆角用 `circle`。 | 同时写 `fill` 和 `stroke`(而不是写 `strokeAndFill`)时,到底是“填充+描边”还是其中一个盖过另一个;文档分别讲过三种模式,却没讲两个开关同时出现。 | 我会照抄得到一块带蓝色描边的深色圆角面板;如果两个开关不能并存,我可能只得到填充或只得到描边,而且不会报错,很难判断哪里不对。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 骨架代码`(根 `<container loc={[0, 0, 720, 480]}>`)与 `## 运行效果` | `loc` 前两项是左上角、后两项是宽高;默认尺寸 200×200;live 按 720×480 展示。 | 720×480 是 UI 自己的逻辑尺寸,还是必须等于游戏画布尺寸;UI 比画布大或小时会不会被裁剪或缩放;我自己的魔塔画布不是 720×480 时该怎么定尺寸。 | 我会直接把根容器写成 720×480,但在自己游戏里可能只看到左上角一块,或者整块被拉伸;文档没有告诉我该按画布还是按面板设计尺寸。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 打开它` | 场景 UI 用 `props.state.sceneController.open`;另一个 UI 内用 `props.controller.open`;主 UI 栈用 `props.state.mainUIController.open`;没有全局 `client`。 | 如果我不在 UI 组件里(比如游戏主入口、场景脚本),手上没有 `props`,该从哪里拿 `sceneController` / `mainUIController`;文档只说“在主入口你持有的客户端核心实例上调用”,没给主入口长什么样,也没说客户端核心实例怎么获得。 | 我写完骨架后不知道把打开代码贴到哪里;在 UI 组件外写 `props.state` 会直接报错,我只能回头猜或去翻别的章节。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 先把文件拆好`(“留空或放占位组件”) | 四个子组件后续逐篇补全;`InventoryPanel` 负责组合它们。 | 占位组件最小要满足什么(要不要 `defineComponent`、要不要声明 `props`)才能被 `import` 又不报错;文档没有给占位写法。 | 我可能建四个空 `.tsx`,一 `import` 就编译失败;或者随便写个组件但 `props` 对不上,后面替换时还要回头改骨架。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | `## ItemGrid:按行列排列`(外层 `<container loc={[0, 0, 0, 0]}>`) | `container` 的 `loc` 是 x/y/w/h;不写尺寸默认 200×200;`container` 是布局单位与事件捕获单位;子元素坐标相对父容器。 | 宽高为 0 的容器会不会裁剪子元素、会不会让子元素无法命中;文档从没说过 `container` 是否裁剪溢出内容。 | 我照抄一个 0×0 容器包住网格;如果容器裁剪,我会看到一片空白,点击也没反应;如果它只是布局壳,则一切正常。我无法从文档判断是哪一种。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | `## ItemGrid:按行列排列`(每个格子外包 `<container loc={[x, y]}>`,没给宽高) | 不写宽高默认 200×200;`container` 参与命中;`zIndex` 决定遮挡与命中先后。 | 这个 200×200 的外壳会不会盖住相邻格子、把点击算到错误的格子上;命中区域是按容器自身矩形,还是只按可见子元素。 | 我的格子间距只有 8,外壳 200×200 会互相重叠;点第二格可能被第一格的外壳接住,选中项乱跳。文档没有说明该不该给外壳补 `size`。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | `## 放回面板`(`items.find(...)`;对照下一篇的 `items.value.find(...)`) | 选中项用 `computed` 从 `items` 与 `selectedId` 派生;`find` 找不到返回 `undefined`。 | `items` 在最终代码里到底是普通数组还是 `ref`;本篇写 `items.find`,下一篇写 `items.value.find`,我不知道假数据该定义成哪一种、`computed` 里该不该写 `.value`。 | 我照本篇写可能得到“`items.find` 不是函数”或响应式不更新;照下一篇写又要改数据定义。我只能二选一赌一个。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | `## ItemCell:一个格子`(`const size = props.size ?? 66;`) | `props` 是响应式的、不能解构;随数据变化的派生值应放 `computed`;尺寸这类不变的基础值可以在 setup 读一次。 | `cellSize` 会不会在运行时变(`边界与注意` 提到“网格区域尺寸变化时重新算列数”,暗示会变);如果父组件改 `cellSize`,`ItemCell` 里只读一次的 `size` 会不会保持旧值。 | 我先照抄;窗口或区域变化后只有列数变了,格子尺寸不跟着变,出现重叠或留白。我不确定是否该主动改成 `computed`。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | `## 放回面板` + `## 边界与注意`(选中与未选中) | `selectedId` 初始为 `'potion-red'`;点击只会上报有效 id;详情篇要用 `undefined` 表示未选中。 | 在这个面板里怎样才会进入“没有选中”的状态;本篇没有任何清除选中的入口,文档也没说后面会加。 | 我会以为点空白处或再点一次可以取消,但代码里没有;到了详情篇看到“请选择道具”的提示,我不知道它何时会出现,也不知道要不要自己补一个取消按钮。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | `## 选中项由父组件派生`(`items.value.find`) | `selectedItem` 是 `computed`;`ItemDetail` 的 `item` 可选;`find` 返回 `undefined` 时显示提示。 | `items` 的数据形态。我在上一篇刚看到 `items.find`,这一篇变成 `items.value.find`;我不知道最终 `InventoryPanel` 里 `items` 是 `ref` 还是普通数组,也不知道假数据该放哪。 | 我按这一篇把 `items` 写成 `ref`,上一篇的 `items={items}` 就要改成 `items.value`;改动会牵连 grid 段代码,而文档没有给合并后的完整版本。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | `## ItemDetail:右侧面板`(两个没有 `loc` 的 `<container hidden=...>`) | `container` 不写 `loc` 时默认 200×200;`ItemDetail` 外框是 196×330;`hidden` 只切换显示与交互。 | 这两个内层容器没有给尺寸,默认 200×200 会不会超出 196 宽的详情区、会不会裁剪或挡住右侧边缘;`TextContent` 的 `autoHeight` 超过 200 高时,是被容器裁掉还是继续撑开。 | 长描述会画到容器外,或者被裁掉;我不知道该不该给内层容器补 `loc={[0, 0, 196, 330]}`,文档没说 `container` 默认是否裁剪。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | `## ItemDetail:右侧面板`(`TextContent` 的 `autoHeight` 与 `loc`) | `TextContent` 的 `width` 必填;`autoHeight` 让高度跟内容走;`TextContent` 需要完整客户端才能跑。 | `autoHeight` 时元素高度由谁决定、会不会和父容器 200×200 的默认高度冲突;我在只读文档、没有完整客户端的情况下怎么确认它没被裁。 | 我照抄后描述可能只显示一部分,而且 live 里用的是 `text` 等价实现,看不出真实 `TextContent` 的效果;我无法验证。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | `## 运行效果`(“点「取消选择」可以看到没有选中时的提示”) | live 会演示未选中提示;live 用元素层 `text` 等价展示,正文代码块才给 `TextContent` 真实写法。 | 正文代码里没有“取消选择”按钮,也没有把 `selectedId` 设为 `undefined` 的逻辑;我不知道这个按钮是 demo 专用,还是我该在面板里实现。 | 我照正文搭完面板,永远看不到“请选择道具”;要么以为漏抄了,要么自己加一个文档没要求的按钮。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | `## ItemDetail:右侧面板`(`hidden={!!props.item}` 与 `hidden={!props.item}` 两块都渲染) | `hidden` 保留元素与状态;两块都渲染、用 `hidden` 切换;边界提到注意 `zIndex` 与遮挡。 | 两块容器都在 (0,0) 且默认 200×200,重叠时谁在上、会不会互相拦截点击;文档只提醒“注意”,没给判断方法或推荐写法。 | 我照抄后可能点不到详情里的内容,或者提示层挡住详情;我只能靠猜 `zIndex`。 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | `## 方案一:Scroll 平铺(推荐)` 的 `ItemGridScroll` 代码块与「`items` 与 `selectedId` 仍然来自 `InventoryPanel`」一句 | 第 21 篇把 `selectedId` 放在 `InventoryPanel`,用 `selectedId={selectedId.value}` 作为 prop 传给 `ItemGrid`;第 12 篇说 `props` 数组必须把用到的键列全,漏了就收不到 | 这个新组件没有 `props` 声明、没有 `SetupComponentOptions`,却直接用 `items` 和 `selectedId.value`。它们到底是父组件通过 prop 传进来的,还是同文件里的模块级变量,还是闭包?文档没说要从哪里拿、也没说 `InventoryPanel` 那一侧要怎么改 | 把代码复制进 `item-grid.tsx` 后 `items`、`selectedId` 会提示未定义;我分不清是该加 import、加 props,还是干脆写在同一个文件里 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | 同段 `const scroll = ref<ScrollExpose>()` 与 `import { Scroll, ScrollExpose } from '@user/client-base'` | 第 16 篇说 `Scroll` 暴露 `scrollTo(y, time?)` 与 `getScrollLength()`;第 15 篇见过 `TextContentExpose` 这种「用 ref 接方法」的类型 | 正文从没提过 `ScrollExpose` 是什么、为什么 `ref` 的泛型要填它;也没说 `Scroll` 在 TSX 上写 `ref={scroll}` 时,暴露对象是组件实例还是必须用这个类型 | 能照抄,但换一个内置组件(例如 `ListPage`、`Page`)时就不知道对应的 `XxxExpose` 名字,也不知道该不该一律用 `ref<SomeExpose>()` |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | `## 方案一` 每个子元素写成 `loc={[0, row * 74, 362, 66]}`,`Scroll` 高 294、`padEnd={16}`;以及全篇没有「放回面板」一节 | 第 16 篇说 `Scroll` 只对视口附近的直接子元素做虚拟滚动、子元素要平铺;第 21 篇专门有「放回面板」,给出把 `ItemGrid` 塞回 `InventoryPanel` 的完整写法 | 子元素的 `y` 是否必须是「从 0 开始累加的绝对坐标」?`Scroll` 靠什么算出 `getScrollLength()`,是最后一个子元素的 `y + height`,还是要自己声明总长度?最后一行要不要另外留高度?另外 `items` 从 10 个变 40 个、`InventoryPanel` 里把 `<ItemGrid>` 换成 `<ItemGridScroll>` 这两步,本篇没有写 | 抄完组件能滚,但换行高或换两列布局后总滚动长度会算错;并且不知道六个文件该怎么最终拼起来,因为缺少把滚动版塞回面板的这一步 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | `## 方案二:ListPage 左列表右详情` 的 `const list = items.map(...)`、`onClose={() => (selected.value = '')}` 与 `default: key => items.find(...)` | `ListPage` 的 `list` 属性是「每一项 `[id, 显示文本]`」;本篇正文说 `items` 来自 `InventoryPanel`;第 22 篇开头 `items` 是普通 `const` 数组,第 22 篇「选中项由父组件派生」又写成 `items.value.find(...)`;第 16 篇说 `ListPage` 的关闭按钮只发 `close` 事件、真正关闭动作由调用方处理;第 22 篇说 `ItemDetail` 在没有选中时显示「请选择道具」 | 这里 `items` 到底是普通数组还是 `ref`?照这里的写法不写 `.value`,可第 22 篇同系列的另一段又写 `.value`。另外 `list` 的类型是 `[string, string][]`,`.map` 推出来的是 `string[][]`,直接传会不会报类型错误、要不要断言;点「关闭」之后,按这里只是把选中清空,面板本身没有关。那这个关闭按钮的语义是「清空选中」还是「关面板」?如果我想真的关,应该调 `props.controller.close(props.instance)`,但这里是 slot 里的组件,拿不拿得到 `props.controller`? | 要么运行时 `items` 为 undefined 直接崩,要么 TypeScript 报「`string[][]` 不能赋给 `[string, string][]`」,我卡在类型上;点关闭后面板还在,只是右侧变成「请选择道具」,我会以为关闭功能坏了,或者以为要自己另外接控制器 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | `## 什么时候用 Scroll、ListPage、Page` 表格与 `## 边界与注意` 的 `container-custom` 一条 | 第 16 篇提过「滚动区域内部使用容器自定义标签 `container-custom`,是组件实现细节,作者不需要手动写」 | 第 16 篇说「不需要手动写」,本篇又写「只写 `container-custom`」,我不确定这句话是在禁止我写,还是在告诉我万一要写时只能这么写;也不知道「容器自定义标签」和普通 `custom` 标签是不是一回事 | 读到这里会犹豫要不要在 `Scroll` 里手写这个标签,怕写了反而破坏虚拟滚动 |
| docs/advanced/ii/ui/inventory-example-5-state.md | `## 已装备的格子` 的 `interface ItemCellProps` 扩展与 `<g-rectr ... strokeStyle={...} />` | 第 21 篇 `ItemCell` 的 `props` 数组是 `['item','selected','size']`;第 12 篇明确说「`props` 数组必须把用到的键写全,没写就收不到」,属性写错不报错、只是 `undefined` | 本篇只加了接口字段和描边表达式,没有给新的 `props` 数组(要不要把 `'equipped'` 加进去),也没有给 `ItemGrid` 怎么把 `equippedId` 传到每一格(`ItemGrid` 的接口和 `props` 数组是不是都要加?)。而第 21 篇的 `ItemGrid` 是显式逐个传 `item / selected / size` 的 | 只照着加接口字段,运行后 `props.equipped` 永远是 `undefined`,装备描边不出现,而且不报错,我会以为是颜色写错了 |
| docs/advanced/ii/ui/inventory-example-5-state.md | `## 状态放在 InventoryPanel` 的 `watch(() => selectedItem.value?.count ?? 0, (next, prev) => ...)` | 第 8 篇 `watch` 的例子是 `watch(count, cb)`,源是一个 `ref`,回调拿到新值与旧值;同篇也说 `computed` 只算值、副作用用 `watch` | `watch` 的第一个参数在这里是箭头函数而不是 `ref`,这是合法写法吗?`selectedItem` 是 `computed`,从 A 道具切到 B 道具时 `count` 也会变,这条 `watch` 会不会把我「换了个道具」误报成「数量变化」?另外要不要 `.value`、要不要 `{ immediate: true }` 都没说 | 能跑,但切换道具时提示会莫名其妙变成「数量:3 → 1」;我不知道这是设计如此还是我抄错了 |
| docs/advanced/ii/ui/inventory-example-5-state.md | `## 组装` 的 `<ActionBar ... onClose={() => (hint.value = '已请求关闭')} />` | 第 20 篇骨架里关闭按钮是 `props.controller.close(props.instance)`,而且边界注意里强调「关闭按钮必须在骨架阶段就能用」;本篇 `ActionBar` 只负责 `emit('close')`,由父组件决定 | 最终「关闭」到底该不该真的关面板?这里把 `close` 换成只改提示,和「面板能关闭」的目标不一致。如果我要保留真关闭,是不是写 `onClose={() => props.controller.close(props.instance)}`?那 `hint` 那句还要不要? | 照抄后点「关闭」不关面板、只改了提示文字;可是本篇「运行效果」又说 live 能关闭,我会对不上 |
| docs/advanced/ii/ui/inventory-example-5-state.md | `## 遮罩与 noevent` 的 `<g-rect loc={[0,0,720,480]} ... noevent />` 与边界注意「遮罩要盖在画面之上、面板之下」 | 第 7、9 篇说 `noevent` 仍然绘制、跳过命中、事件下穿;第 24 篇说遮罩负责压暗、不挡点击 | 这个遮罩放进组件树的哪个位置?写在面板容器前面还是后面?「面板之下」是指 `zIndex` 更小、还是源码顺序更靠前?如果遮罩在面板下方,点击面板外的遮罩区域会直接下穿到场景,这算不算预期?遮罩尺寸该用整块 720×480 还是面板外框? | 放错层时要么把整个面板也压暗,要么点击遮罩没有任何反应;我只能反复挪位置试 |
| docs/advanced/ii/ui/inventory-example-5-state.md | `## ActionBar:底部按钮` 的 `props.equipped ? '已装备' : '装备'` 与组装处 `equipped={!!equippedId.value}` | props 只读、不要解构;组件根据 props 渲染;装备状态只保存 id | `ActionBar` 的 `equipped` 看字面是「当前选中道具是否已装备」,但组装处传的是面板级的「有没有任何一个道具被装备」。两者语义不同。另外 `makeButton` 是在 `setup` 里定义并直接返回 JSX 的函数,它是否必须在 render 函数里调用才会随 props 更新?文档没说 | 选中一个没装备的道具,按钮仍然显示「已装备」;或者担心 `makeButton` 提前把 JSX 固定住,切换选中后按钮不刷新 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | `## 动画:只改 alpha 与 scale` 整段,尤其 `const InventoryPanel = defineComponent(() => { ... })` | 第 20 篇 `InventoryPanel` 是同时继承 `IGameUIPropsBase` 与 `DefaultProps`、`props` 数组含 `controller/instance/state` 的 UI;第 13 篇说 `setup` 返回 render、`onMounted` 起、`onUnmounted` 清 | 这段把 `InventoryPanel` 整个重新定义了一遍,里面只有一块描边,没有 props、没有网格、详情、按钮。它是「替换原文件」还是「只把 `pulse` 那段并进已有 `InventoryPanel`」?合并进已有文件时,`defineComponent` 的泛型与 `props` 数组怎么办?`pulse` 要传给哪个子组件? | 直接当新 `InventoryPanel` 用,整个背包面板会被一个边框取代;保守一点就停在半路,不知道代码该贴到哪里 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 同段注释「只改 `alpha` 与 `scale`」与 `loc={[30,30,660,420]}` 的 `<g-rectr>`;标题又说「让选中态动起来」 | 第 21 篇的选中态是 `ItemCell` 里那一圈描边(`selected ? '#f2b84b' : '#33465f'`);第 7 篇说 `scale` / `rotate` 以锚点为中心、锚点改变会连视觉位置一起变 | 代码动画的是整块面板外框(30,30,660,420),不是选中的格子;到底要动的是哪个?如果真是格子描边,`ItemCell` 里怎么拿到 `pulse`(父传子 prop?还是各自起一份)?`g-rectr` 默认锚点是 0,`scale` 放大时会不会往右下跑、和 `loc` 的 30,30 对不上? | 照抄后是面板边框在呼吸,不是选中格子在呼吸;或者缩放后边框往外偏,看起来像位移 bug |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 同段末尾 `transitioned(0, 300, linear())`、`if (!fade) return;`、`fade.set(100)` | 本篇说它的返回值是 `ITransitionedController<...> \| null`,使用前必须判空;也说本篇 live 不依赖它 | `transitioned` 和 `linear` 从哪个包 import?`0, 300` 是「起始值、时长」还是「两个端点」?`fade.set(100)` 的 100 是目标值还是时间?控制器还有哪些方法、怎么「开始/停止/回调」?文档只给了三行,读者没有源码可看 | 抄不下来;只能用回手写 `requestAnimationFrame`,这三行等于只留了个名字 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | `## 注册与打开` 的两段注释:`props.state.mainUIController.open(...)` 标「游戏内主 UI 栈」,`props.controller.open(...)` 标「场景 UI」 | 第 1 篇把 `props.state.sceneController.open` 归为「场景 UI」、把 `props.controller.open` 归为「在另一个 UI 内打开、面板跳面板」;第 17 篇说场景 UI 与主 UI 是两个控制器;第 20 篇已经写过 `export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)` | 这里把 `props.controller.open` 注释成「场景 UI」,和前面两篇对不上;从主菜单或主场景打开背包,到底该用 `sceneController`、`mainUIController` 还是当前 `controller`?另外 `InventoryUI` 第 20 篇已经 `new` 过一次,这里再 `new` 一次是重复注册还是替代?同名会不会冲突? | 选错控制器时背包出现在错误层级或压根打不开;重复 `new` 时不知道以哪个为准,怕一改就两个入口都坏 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | `## 性能自查` 表格的「列表 / key」两行,以及 `## 边界与注意` 的「不要只停一次」 | 第 19 篇的性能口径;第 21 篇说固定顺序列表不加 `key`、第 23 篇 `Scroll` 版又写了 `key={item.id}`;第 25 篇开头说动画卸载后必须停 | 表格说「通过:网格平铺在 `Scroll` 的直接子元素下」,但第 21 篇最终放回面板的是普通 `container` 网格,第 23 篇只给了独立 `Scroll` 组件,读者不知道最终 `inventory-panel.tsx` 里到底是哪一个。另外「不要只停一次」是什么意思——`cancelAnimationFrame` 到底要调用一次还是循环调用?我只知道要调一次 | 按第 21 篇做就没有 `Scroll`,按第 23 篇做又没有回填步骤;动画清理那句读不懂,怕少写或多写 |
## 跨篇问题
1. **文件落地与拼装。** 我读完第 1 篇只知道要 `export` 一个 `GameUI` 对象,不知道 `.tsx` 放哪个目录、构建如何发现、注册时机;到第 20 篇拿到五个文件职责表,仍没有目录、`import` 路径与「谁 import 谁」的完整示意,第 21、22 篇只给局部代码块,我手上没有一份把五个文件拼起来的可运行版本;第 21 篇定义 `interface Item`、第 22 篇直接用 `Item` 却没给 import、第 24 篇又各自重写 `ItemCellProps`,我也无法确定共享类型该放在哪个文件。
2. **组件骨架哪几段可以省。** 第 1 篇给的是带 Props 基类、props 列表、`GameUI` 注册的完整外壳,第 2–7 篇的 TSX 却是裸露标签;第 8、9、11、15、16 篇又大量用 `defineComponent(() => ...)`。我不知道这些片段该放进 `return () => (...)`、能否单独成文件、多个片段如何合成一个界面,也不知道省略外壳后父组件传的值会进 `props` 还是 `attrs`。
3. **`defineComponent` 的泛型与第二参数一路在变。** 第 1 篇一个泛型,第 12/13 篇三个(Props、Emits、`keyof Emits`),第 14 篇四个(还多 `string` 与 `SlotsType`);第二个参数有时是 `SetupComponentOptions`,有时是手写 `PanelOptions`/`FieldOptions`,`Ticker` 又完全不写。我不知道第几个参数是什么、哪些可以省、无 props 组件是否必须写空 options、省略后还能不能用 `emit`。
4. **import 来源散落。** `container`、`g-rect`、`text`、`image`、`g-path` 以及 `Container`、`Rect`、`Text`、`Font`、`Texture`、`Path2D` 从第 1 篇到第 7 篇都没有 import 行或「全局可用」说明;第 10 篇 `useKey` 没 import,第 23 篇又写 `import { useKey } from '@user/client-base'`;`DefaultProps`、`SetupComponentOptions`、`IGameUIPropsBase`、`SlotsType`、`VNode`、`Font` 的来源散落各篇,我要拼完整文件时得自己汇总。
5. **打开入口与控制器归属。** 第 1 篇把打开分成场景 UI、另一个 UI 内、主 UI 栈三处;第 20 篇说不在 UI 组件里时要在「主入口持有的客户端核心实例」上调用,却没给主入口长什么样;第 25 篇又把 `props.controller.open` 注释成「场景 UI」,而第 1、17 篇里它指「面板里面板」。我不知道第一次打开该挑哪个、从主菜单或主场景打开背包该用 `sceneController`、`mainUIController` 还是当前 `controller`,也不知道同时打开时谁在上面。
6. **`open` 的第二个参数与 `props.instance`。** 第 1 篇只出现 `open(..., {})`,我不知道第二个参数是什么类型、里面能放什么、放进去后怎么在面板里取到;`props.instance` 只被要求出现在 props 列表并在关闭时原样传回,我没能形成「它是什么、为什么关闭要凭它」的概念。
7. **坐标基准与面板尺寸。** 第 1、2 篇都用 480×320,第 20 篇直接定 720×480,但都没有说这是不是游戏画布分辨率、UI 会不会被整体缩放或裁剪、坐标原点与单位是「屏幕像素」还是「设计像素」;我自己的魔塔画布不是这个尺寸时,不知道该按画布还是按面板设计尺寸,后面网格列数与详情宽度都会跟着错。
8. **事件坐标与变换没有串起来。** 第 2 篇的嵌套坐标、第 7 篇的 `scale`/`rotate`、第 9 篇的 `offsetX`/`offsetY` 之间没有接上;元素被缩放或旋转后,事件里的相对坐标是变换前还是变换后的,我推不出来。
9. **`ref` 的两种样子。** 第 7 篇在响应式篇之前就用了 `ref`、`open.value`、`onClick`;第 8 篇的 `ref(0)` 是响应式值,第 13 篇的 `ref<CardExpose>()` 是拿子组件实例,两者 import 相同、写法相同,我容易把「组件 ref」也当成需要 `.value` 的普通响应式值,或反过来。
10. **`hidden` 与布局流。** `hidden` 在第 7、8、11 篇反复出现,却没有一处说明它是否影响布局流;我做「隐藏一块、下面跟着动/不动」时只能猜。
11. **列表数据怎么变。** 第 8 篇的 `ref` 与第 11 篇的 `ref` 数组之间缺一座桥,第 11 篇只讲怎么渲染列表,不讲 `push`/`splice`/整体替换哪种会触发更新;后面做背包格子恰恰从「数据如何变化」开始。
12. **`items` 是普通数组还是 `ref`。** 第 21 篇写 `const items: Item[]`、用 `items.find`,第 22 篇同一段派生逻辑写 `items.value.find`,第 23 篇 `Scroll` 版与 `ListPage` 版又直接 `items.map`,第 24 篇变成 `const items = ref<Item[]>(...)`。我不知道最终该定义成哪一种、传给子组件时写 `items` 还是 `items.value`、`computed` 里该不该写 `.value`。
13. **子组件怎么拿父组件选中态。** 第 21 篇是标准 props 逐层传(`selectedId`、`onSelect`),第 23 篇的 `ItemGridScroll` 没有 props 声明却直接引用 `items` 与 `selectedId.value`。我不知道它们是父组件传进来的、模块级变量还是闭包,也不知道 `InventoryPanel` 那一侧要怎么改,更不知道该学哪一种写法。
14. **`props` 与 `attrs` 的边界。** 第 12 篇末尾才说「漏写的键会落到 `attrs`」,`attrs` 的完整解释在第 14 篇;同一句「属性名用 camelCase」可能指元素属性、props 键或透传的 `attrs`。我在第 12 篇调试「传了没生效」时,手上没有 `attrs` 的概念,只能反复检查 props 数组。
15. **新增一个 prop 要改哪些地方。** 第 12 篇反复强调 `props` 数组漏键就收不到、而且不报错;第 24 篇给 `ItemCell` 加 `equipped` 时只改了接口和描边,没给新数组,也没给 `ItemGrid` 的传递链。我怕「照文档改完不生效」,又怕自己多改反而错。
16. **「TSX 里没有模板指令」与 `v-model:xxx`。** 第 1、11、13 篇都强调没有模板指令,第 12 篇却在 TSX 里写 `v-model:selected` / `v-model:open`。我无法判断哪些「模板写法」在 TSX 里其实可用、哪些必须换普通属性,也不知道 `v-model` 写回的是 `ref.value` 还是别的变量。
17. **slot 的两种写法。** 第 14 篇教的是默认 slot 内容写在标签之间、具名 slot 用对象;第 16 篇 `Page` 却把函数直接当 children,`ListPage` 又用 `{{ default: fn }}`。我不知道判断标准是什么,混用时担心「什么都不显示」。
18. **`props.state` 与 `state` 从哪来。** 第 1 篇说 `props.state` 是 ClientCore,第 10 篇直接写 `props.state.hotkey.system`,始终没有一处总览它里面有什么;第 17 篇 `setPropsBaseCreator` 示例只返回 `instance` 和 `controller`,但所有打开入口都靠 `props.state`。如果我自己写 creator,是不是要把 `state` 也装进去、不装会不会把已有的 `state` 覆盖掉,文档没有把这条链路讲透。
19. **背景的四个名字。** `showBack`、`showingBack()`、`showBackground`、`hideBackground` 名字太接近,我不知道「现在背景是否可见」该读引用值还是调用方法,也不知道哪个是用户设置、哪个是系统最终结果。
20. **`GameUI` 的名字还有什么用。** 第 1 篇说名字用于打开时识别,第 17 篇又说没有全局注册、打开只认对象;我不知道名字是否还必须唯一、重名会怎样、调试时能不能靠名字找到实例,第 25 篇再 `new` 一次 `InventoryUI` 时也不知道是重复注册还是替代。
21. **`width` 与 `loc` 里的宽高谁说话。** 第 2 篇说 `loc` 后两项是宽高,第 15 篇 `TextContent` 又单独要求 `width`。当两者都写时,我不知道哪个生效,也不知道 `autoHeight` 会不会改掉 `loc` 的高度。
22. **`List` 的 `v-model` 与「初始以第一项为准」。** 第 12 篇说 `v-model:xxx` 是双向绑定,第 16 篇说挂载后再改绑定不会重新选中。我想从存档恢复选中时,不知道该改绑定、改列表数据,还是调用某个「列表自己的交互」。
23. **`key` 的规则。** 第 11 篇说顺序固定的无状态列表不需要 `key`、也不要用下标代替会变化的身份;第 16、19、23 篇的 `Scroll` 示例又给每行 `key={index}` 或 `key={item.id}`,第 19 篇还让我「规则见 `dev.md`」,而我不知道 `dev.md` 是什么、在哪里。我不知道这是 `Scroll` 的特殊要求,还是只是示例写法。
24. **live 与正文不是同一段代码。** 第 15、16、22、23 篇都写明 live 是「等价元素」,真实组件要在完整客户端里跑;第 20 篇的关闭按钮在 live 里只显示提示,第 22 篇 live 用 `text` 等价实现多行说明、还多一个正文没有的「取消选择」按钮。我按正文写完后,无法用 live 对照自己的实现;当 live 和正文表现不同时,我不知道该以哪个为准。
25. **「内置组件」与「内置 UI」。** 第 15、16 篇标题都是「内置组件」,第 18 篇开头才把「内置组件」和「内置 UI」分开;我读第 15、16 篇时以为第 18 篇要改的就是这些组件,到第 18 篇才发现不是。
26. **图片与纹理。** 我真正要做的是物品栏,需要显示物品图标;第 6 篇只教了用 canvas 现画纹理,没有讲如何加载 PNG、如何从素材表取一帧,末尾提到的 `icon` 也没有可照抄的写法。
27. **canvas 相关术语。** 我不懂 canvas,但文档反复使用 canvas、`Path2D`、`getContext`、抗锯齿、高清缓存这些词。第 4、6、7 篇都假设我知道它们大概是什么,我只能照抄,无法判断出错时是代码问题还是理解问题。
28. **缓存与标脏。** 第 7 篇说 `container` 默认开缓存,又说「频繁变化的元素开缓存反而更慢」,却没给「如何标脏」;第 19 篇也没说父容器默认缓存会不会让内部变化的 `text` 不更新、脏标记会不会传到缓存的父级。我不确定默认缓存对会变化的物品栏容器是不是陷阱。
29. **「没有选中」这个状态从哪来。** 第 21 篇把 `selectedId` 初始化成有效 id,点击也只会上报有效 id;第 22 篇却依赖 `undefined` 来显示「请选择道具」,live 里还有一个正文没有的「取消选择」按钮。我想不出用户做什么操作会进入未选中状态,也不知道这个交互该由谁补。
30. **容器是否裁剪、命中怎么算。** 第 21 篇用 0×0 容器包网格、用默认 200×200 的容器包每个格子,第 22 篇用默认 200×200 的容器包详情内容;我反复遇到「容器不写尺寸」的写法,却始终不知道容器会不会裁剪超出部分、命中是按容器矩形还是子元素矩形、重叠时点击算谁的。
31. **「关闭」到底归谁。** 第 20 篇骨架关闭按钮直接 `props.controller.close(props.instance)`,第 24 篇组装时 `onClose` 只改提示文字,第 24 篇 live 描述又说能关闭;第 23 篇 `ListPage` 的关闭按钮只清空选中。我不确定最终面板的关闭按钮该调控制器、交给父组件再决定,还是只清空选中,也不知道 slot 里的组件拿不拿得到 `props.controller`。
32. **最终背包左侧是什么。** 第 21 篇放回面板的是普通容器网格,第 23 篇给了 `Scroll` 与 `ListPage` 两个独立方案,第 25 篇性能表却按「已平铺在 `Scroll` 下」判定通过。三篇拼起来,我不知道 `inventory-panel.tsx` 最终的左侧到底是普通网格、`Scroll` 还是 `ListPage`。
33. **布局最后会不会压住。** 第 20 篇左侧网格占位是 `[54,110,400,330]`(底边到 440),第 24 篇 `ActionBar` 放在 `[54,392,304,32]`(392–424),第 23 篇 `Scroll` 高又是 294。我不确定按钮是故意压在网格上方,还是网格应该缩短,也不知道最终各区域的真实坐标该以哪篇为准。
34. **「只要基础 TS/JS」与样板语法。** 第 1 篇说「只要基础 TS/JS」,但模板里出现了 `defineComponent`、`satisfies`、JSX 注释与无值属性;我不确定这些是必须现场学会,还是可以当作固定样板不动。
## 分节使用概率
| 篇目 | 章节 | 使用概率(高/中/低) | 理由 |
| --- | --- | --- | --- |
| docs/advanced/ii/ui/ui-template.md | 一个最小 UI | 高 | 这是唯一的起点,我会反复回来对照复制、逐行替换,两个代码块都会被打开看。 |
| docs/advanced/ii/ui/ui-template.md | 只改哪几行 | 高 | 它直接对应我的目标「把模板改成自己的面板」,是我改动时的操作清单。 |
| docs/advanced/ii/ui/ui-template.md | 打开与关闭 | 高 | 写完必须打开才能验证,也要能关闭回到上一界面;但我会在同一节里反复卡在选择入口上。 |
| docs/advanced/ii/ui/ui-template.md | 运行效果 | 低 | 这是文档站的演示,`templateLoader` 指向 `.vitepress` 内部路径,我在自己项目里没法照搬,只能看个样子。 |
| docs/advanced/ii/ui/ui-template.md | 边界与注意 | 中 | 四条都是踩坑提示,但第一遍读时「单文件组件」「camelCase 与连字符」还没有具体对照物,容易读过即忘,多半等出错后回来查。 |
| docs/advanced/ii/ui/container-and-coordinates.md | 坐标从哪里来 | 高 | 我没有任何 UI 经验,先要弄清坐标原点和父子相对关系,否则什么都摆不对 |
| docs/advanced/ii/ui/container-and-coordinates.md | loc 与锚点 | 高 | 每个元素都要写 `loc`,锚点直接决定“位置对了没” |
| docs/advanced/ii/ui/container-and-coordinates.md | 一个嵌套示例 | 高 | 我需要照着嵌套出“外框 + 内容区”,这是物品栏的基本结构 |
| docs/advanced/ii/ui/container-and-coordinates.md | 层级 | 中 | 做物品栏会用到提示框或浮层,但一开始不一定需要跨容器层叠 |
| docs/advanced/ii/ui/container-and-coordinates.md | 运行效果 | 中 | 我需要一个视觉对照,确认自己摆出来的区域和文档一致 |
| docs/advanced/ii/ui/container-and-coordinates.md | 边界与注意 | 高 | 默认 200×200 和锚点差异是我最可能踩的坑 |
| docs/advanced/ii/ui/basic-shapes.md | 四个图形 | 高 | 色块、边框、分隔线是物品栏最基础的组成 |
| docs/advanced/ii/ui/basic-shapes.md | 填充与描边 | 高 | 我要区分“填充的格子”和“只有边框的槽位”,必须会开关模式 |
| docs/advanced/ii/ui/basic-shapes.md | 圆角与命中 | 中 | 圆角矩形更常用,但命中区域和 `actionStroke` 在按钮上会用到 |
| docs/advanced/ii/ui/basic-shapes.md | 运行效果 | 中 | 需要看四个图形的默认效果,避免颜色混在一起 |
| docs/advanced/ii/ui/basic-shapes.md | 边界与注意 | 高 | 默认浅灰、`fill` 不是颜色、圆和矩形锚点不同,都是我会写错的地方 |
| docs/advanced/ii/ui/curves-and-paths.md | 三次贝塞尔 | 低 | 物品栏以矩形和图片为主,装饰性曲线暂时用不上 |
| docs/advanced/ii/ui/curves-and-paths.md | 二次贝塞尔 | 低 | 同上,不是第一批需要的能力 |
| docs/advanced/ii/ui/curves-and-paths.md | 路径 | 中 | 想画自定义边框或异形底板时会用,但先要解决 `Path2D` 从哪来 |
| docs/advanced/ii/ui/curves-and-paths.md | 圆角矩形 | 高 | 面板、按钮、物品槽都想要圆角,这是最可能直接使用的元素 |
| docs/advanced/ii/ui/curves-and-paths.md | 默认绘制方式 | 中 | 圆角矩形默认填充、路径默认填充,能少写属性,但需要记住表格 |
| docs/advanced/ii/ui/curves-and-paths.md | 运行效果 | 低 | 我更关心 `g-rectr`,曲线示例对当前目标帮助有限 |
| docs/advanced/ii/ui/curves-and-paths.md | 边界与注意 | 中 | 圆角命中区域和 `Path2D` 类型限制会影响交互,需要回看 |
| docs/advanced/ii/ui/text.md | 一行文字 | 高 | 物品名、数量、标题都要写字 |
| docs/advanced/ii/ui/text.md | 字体 | 中 | 我想让标题和正文有区分,会用到 `Font`,但不知道 import |
| docs/advanced/ii/ui/text.md | 尺寸与居中 | 高 | 文字居中在槽位里非常常见,锚点是主要手段 |
| docs/advanced/ii/ui/text.md | 不会自动换行 | 中 | 物品描述会很长,我必须知道什么时候该换内置文本组件 |
| docs/advanced/ii/ui/text.md | 运行效果 | 中 | 需要对照字号与颜色,确认文字没有和背景混在一起 |
| docs/advanced/ii/ui/text.md | 边界与注意 | 高 | 白字、描边过细、`width` 不裁剪,都是我容易误判的点 |
| docs/advanced/ii/ui/image-and-texture.md | 图片元素需要什么 | 高 | 物品栏的核心就是图标,必须让 `image` 显示出来 |
| docs/advanced/ii/ui/image-and-texture.md | 造一张最小纹理 | 中 | 我只想验证元素能显示;真正图标要加载文件,这一节只能算过渡 |
| docs/advanced/ii/ui/image-and-texture.md | 像素图设置 | 中 | 魔塔素材多是像素图,放大发虚是常见问题 |
| docs/advanced/ii/ui/image-and-texture.md | 应用层素材标签 | 低 | 文档明确说超出最小范围且没有用法,我暂时接不上 |
| docs/advanced/ii/ui/image-and-texture.md | 运行效果 | 中 | 需要看默认插值和 `noanti hd={false}` 的差别 |
| docs/advanced/ii/ui/image-and-texture.md | 边界与注意 | 高 | 纹理创建成本、拉伸变形、默认 200×200 都会直接影响我 |
| docs/advanced/ii/ui/layer-transform-performance.md | 遮挡:zIndex | 高 | 物品提示框、下拉层、选中高亮都需要压在别的元素上面 |
| docs/advanced/ii/ui/layer-transform-performance.md | 变换:scale、rotate 与 alpha | 中 | 悬浮放大、遮罩变暗会用,但不是第一版必需 |
| docs/advanced/ii/ui/layer-transform-performance.md | 显示开关:优先 hidden | 高 | 打开/关闭物品栏、详情面板是最常见的交互 |
| docs/advanced/ii/ui/layer-transform-performance.md | 缓存:cache 与 nocache | 中 | 物品栏可能有几十个格子,会考虑性能,但先要会标脏 |
| docs/advanced/ii/ui/layer-transform-performance.md | noevent:可见但不接收交互 | 中 | 弹窗遮罩需要“压暗但可点下面”,这一节正好对应 |
| docs/advanced/ii/ui/layer-transform-performance.md | filter 与 composite | 低 | 特殊视觉效果,当前目标用不到,文档也说先不记 |
| docs/advanced/ii/ui/layer-transform-performance.md | 什么时候用 hidden、什么时候用三元 | 高 | 我需要明确开关面板时状态会不会丢,这张表能直接指导选择 |
| docs/advanced/ii/ui/layer-transform-performance.md | 运行效果 | 中 | 需要看遮挡切换与隐藏、缩放的实际表现 |
| docs/advanced/ii/ui/layer-transform-performance.md | 边界与注意 | 中 | 弧度、`scale` 数组、缓存标脏都会影响后续,但部分问题这篇没答完 |
| docs/advanced/ii/ui/reactivity.md | ref:带 value 的盒子 | 高 | 计数器、面板开关、输入回显都靠它,是最先会照抄的一段 |
| docs/advanced/ii/ui/reactivity.md | reactive:一整块对象 | 中 | 面板一组字段可能用它,但也可以全用 ref 绕开 |
| docs/advanced/ii/ui/reactivity.md | computed:派生值 | 高 | 背包的总重、可否装备、按钮是否可点这类派生值会频繁用到 |
| docs/advanced/ii/ui/reactivity.md | watch:副作用 | 中 | 只在要同步外部或打日志时用,日常界面不一定需要 |
| docs/advanced/ii/ui/reactivity.md | 什么时候用 shallowRef 与 markRaw | 低 | 先把界面跑起来,性能优化阶段才会回头看 |
| docs/advanced/ii/ui/reactivity.md | props 不要解构 | 高 | 一旦开始写组件几乎必踩,属于高频回查点 |
| docs/advanced/ii/ui/reactivity.md | 运行效果 | 低 | 只是看演示,不参与写代码 |
| docs/advanced/ii/ui/reactivity.md | 边界与注意 | 中 | 出现「点了不变」时回来排查 |
| docs/advanced/ii/ui/events.md | 命中测试:事件先找最上层元素 | 中 | 只有做遮罩、穿透、重叠按钮时才需要深究 |
| docs/advanced/ii/ui/events.md | 事件名:on 加事件名 | 高 | 每个可点元素都要查事件名,最常翻的一张表 |
| docs/advanced/ii/ui/events.md | 事件对象 | 高 | 坐标、按键判断、修饰键几乎每次交互都会碰 |
| docs/advanced/ii/ui/events.md | 捕获与冒泡 | 中 | 嵌套面板或阻止点击穿透时才用得上 |
| docs/advanced/ii/ui/events.md | enter 与 leave 不走普通冒泡 | 中 | 做悬停高亮时会遇到,但不是每个界面都有 |
| docs/advanced/ii/ui/events.md | noevent:可见但不接收交互 | 中 | 做半透明遮罩、压暗层时直接用 |
| docs/advanced/ii/ui/events.md | cursor:悬停时的鼠标样式 | 中 | 可点元素的提示常用,但属于锦上添花 |
| docs/advanced/ii/ui/events.md | actionStroke:只把描边算作命中 | 低 | 只有「看起来只有边框可点」的特殊界面才会用 |
| docs/advanced/ii/ui/events.md | 一组完整的交互 | 高 | 最接近可整体抄用的整合示例,起步阶段会反复对照 |
| docs/advanced/ii/ui/events.md | 运行效果 | 低 | 只是看演示 |
| docs/advanced/ii/ui/events.md | 边界与注意 | 中 | 事件不触发时回来核对命名与 hidden/noevent |
| docs/advanced/ii/ui/hotkey-in-ui.md | 最小模型:指令、作用域、实现 | 中 | 先建立概念,写代码时不常回头 |
| docs/advanced/ii/ui/hotkey-in-ui.md | useKey:拿到当前组件的作用域 | 高 | 任何要快捷键的面板第一步都是它 |
| docs/advanced/ii/ui/hotkey-in-ui.md | implement:把指令接到回调 | 高 | 绑 Esc 关闭、Enter 确认必用 |
| docs/advanced/ii/ui/hotkey-in-ui.md | 注册新指令与分组 | 中 | 内置指令不够用时才需要自己注册 |
| docs/advanced/ii/ui/hotkey-in-ui.md | 触发方式:HotkeyEmitMode | 中 | 默认抬起触发够用,只有连发时才细看 |
| docs/advanced/ii/ui/hotkey-in-ui.md | 优先级与阻断 | 低 | 按键冲突、需要压过下层时才用 |
| docs/advanced/ii/ui/hotkey-in-ui.md | UI 相关默认按键 | 高 | 想知道某个功能该用哪个指令 id 时直接查表 |
| docs/advanced/ii/ui/hotkey-in-ui.md | 为什么没有可运行示例 | 低 | 一次性说明,读完就不再看 |
| docs/advanced/ii/ui/hotkey-in-ui.md | 边界与注意 | 中 | 按键无反应时回来核对 setup 与覆盖规则 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | 条件:优先 hidden | 高 | 面板、提示层开关几乎每处都用 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | 三元:真正移除节点 | 中 | 需要每次打开重置状态时才切换到这个写法 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | 循环:用 map 生成元素 | 高 | 背包格子、属性行、按钮组都靠它 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | key:只在需要保留身份时加 | 高 | 只要是会增删的列表就得判断要不要 key |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | 三种写法怎么选 | 中 | 决策时查一次表,平时按习惯写 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | 运行效果 | 低 | 只是看演示 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | 边界与注意 | 中 | 列表状态错位时回来核对 key 与结构 |
| docs/advanced/ii/ui/props.md | 组件怎么拿参数 | 高 | 拆父子组件时第一件要做的事,必须知道 Props 接口和 props 数组怎么写。 |
| docs/advanced/ii/ui/props.md | 属性名用 camelCase | 高 | 传参不生效最常见的原因,做背包格子时会反复踩。 |
| docs/advanced/ii/ui/props.md | 默认值用 props.x ?? 默认 | 高 | 尺寸、开关这类可选 prop 几乎每个组件都会用到。 |
| docs/advanced/ii/ui/props.md | props 是响应式的,不要解构 | 高 | 父组件更新后子组件不刷新时,首先要排查的写法。 |
| docs/advanced/ii/ui/props.md | emits 与 v-model | 高 | 选中态、开关、输入值这类双向交互都要用。 |
| docs/advanced/ii/ui/props.md | props 与 hidden / 三元 | 中 | 只在“由父组件控制子组件显隐”的面板里用,属于特定模式。 |
| docs/advanced/ii/ui/props.md | 运行效果 | 中 | 用于对照三个格子的交互,但不运行文档站时只能看代码。 |
| docs/advanced/ii/ui/props.md | 边界与注意 | 中 | 作为排查清单有用,不是每次写组件都逐条对照。 |
| docs/advanced/ii/ui/component-tsx.md | 一个完整组件的结构 | 高 | 新建每个组件都要照着六段结构写。 |
| docs/advanced/ii/ui/component-tsx.md | 生命周期:onMounted 与 onUnmounted | 中 | 做动画、定时刷新、纹理创建时才会用到。 |
| docs/advanced/ii/ui/component-tsx.md | emit 与 expose | 中 | 需要父组件主动调用子组件方法(聚焦、滚动到某格)时才会用。 |
| docs/advanced/ii/ui/component-tsx.md | 组件与 UI 的区别 | 高 | 决定“这块该写成普通组件还是 UI”,拆面板前必须先判断。 |
| docs/advanced/ii/ui/component-tsx.md | 运行效果 | 低 | 主要是演示,写代码时不会反复回看。 |
| docs/advanced/ii/ui/component-tsx.md | 边界与注意 | 中 | 泛型、options、生命周期同步调用这些坑需要当检查表。 |
| docs/advanced/ii/ui/slots-and-attrs.md | slot 解决什么问题 | 高 | 做可复用外框(面板、卡片、列表容器)时先要理解这个模型。 |
| docs/advanced/ii/ui/slots-and-attrs.md | 默认 slot | 高 | 最常见的内容填充方式,几乎每个容器组件都会用。 |
| docs/advanced/ii/ui/slots-and-attrs.md | 具名 slot | 中 | 有标题/页脚/操作区多个插槽时才需要。 |
| docs/advanced/ii/ui/slots-and-attrs.md | 作用域 slot | 中 | 列表项、分页器这类“结构父定、数据子给”的场景才会用。 |
| docs/advanced/ii/ui/slots-and-attrs.md | attrs:没声明的属性 | 高 | 写包装组件(把 `loc`/`fillStyle` 透传给内部元素)时必用。 |
| docs/advanced/ii/ui/slots-and-attrs.md | inheritAttrs 什么时候用 | 中 | 只在属性落错位置、需要关掉自动继承时才查。 |
| docs/advanced/ii/ui/slots-and-attrs.md | 什么时候用 slot、props、attrs | 高 | 拆组件时用来判断该选哪一种传值方式。 |
| docs/advanced/ii/ui/slots-and-attrs.md | 运行效果 | 低 | 演示性质,实际写代码时回看频率低。 |
| docs/advanced/ii/ui/slots-and-attrs.md | 边界与注意 | 中 | `?.`、camelCase、`inheritAttrs` 几条容易忘,适合当清单。 |
| docs/advanced/ii/ui/builtin-text-and-input.md | TextContent:会换行的文字 | 高 | 背包说明、任务文本都要换行,几乎每个面板都会用到。 |
| docs/advanced/ii/ui/builtin-text-and-input.md | Textbox:带背景与标题的说明框 | 中 | 说明框常见,但可以用 `TextContent` 加自己画的背景替代,不是必需。 |
| docs/advanced/ii/ui/builtin-text-and-input.md | Input:在画布上输入 | 高 | 改名、数量、搜索都要输入,是面板常见需求。 |
| docs/advanced/ii/ui/builtin-text-and-input.md | 特殊组件 InputBox:单次输入 | 中 | 单次输入在命名、数量确认里会用,但不是每个面板都需要。 |
| docs/advanced/ii/ui/builtin-text-and-input.md | 运行效果 | 中 | 想看效果,但明说是等价元素,不能验证真实组件的失焦与打字机行为。 |
| docs/advanced/ii/ui/builtin-text-and-input.md | 边界与注意 | 高 | `width` 必填、`v-model:value`、Promise 取消分支都是实际会踩的坑。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | List:可选中的列表 | 高 | 背包分类、设置菜单的基础结构。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | ListPage:左列表、右详情 | 高 | 左列表右详情正是背包和设置面板的主结构。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | Page:分页 | 中 | 物品多时才需要,简单列表用不上。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | Scroll:只对直接子元素做虚拟滚动 | 高 | 大量物品必须虚拟滚动,平铺规则也很关键。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | Selection:不接收事件的选中光标 | 低 | 列表已经内置,只有完全自定义列表时才单独用。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | 特殊组件 ConfirmBox 与 Choices | 中 | 确认和选项弹窗会用,但也可以自己拼面板替代。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | 运行效果 | 中 | 能看布局对照,但不能验证真实列表的选中与滚动。 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | 边界与注意 | 高 | 平铺、初始选中、0 基页码、Promise 悬着都是关键风险。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 四层模型 | 中 | 帮助理解系统,但写代码时不直接操作这四层。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 打开与关闭 | 高 | 每个多面板 UI 都要用,是最基础的接口。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 显示策略 | 高 | 决定叠放和关闭行为,做背包、设置切换时必用。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 背景 | 中 | 有背景需求才用,但切换闪背景时一定会查。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | keep:切换时不闪背景 | 中 | 只在“关一个、开一个”的切换场景里用。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 场景 UI 与主 UI | 高 | 决定面板开在哪个栈,是入口处必须做的选择。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 基础 props 注入 | 中 | 普通作者用默认即可,只有自定义 creator 才需要。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 当前没有全局注册 / 覆盖入口 | 中 | 影响替换思路,但不影响日常打开面板。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 运行效果 | 中 | 最小控制器能看栈长度和激活状态,但不覆盖背景与策略细节。 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 边界与注意 | 高 | 连带关闭、`alwaysShow`、`.value`、重建成本都需要注意。 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 改法一:在打开处替换 | 高 | 最直接、最可靠的替换方式,应该优先考虑。 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 改法二:包装组件 | 中 | 只改一小部分时才用,转发 props、slots、emits 的成本高。 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 改法三:改显示策略或背景 | 中 | 界面不变、只改叠放或背景时才用。 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 三种改法怎么选 | 中 | 决策时看,但不是每次替换都要重新读。 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 不要改内置实现 | 高 | 避免升级丢改动的关键警告,应该先看。 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 运行效果 | 低 | 只对比策略,不演示替换本身,对实际替换帮助有限。 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 边界与注意 | 高 | 转发漏项、emit 改名、keep 配对都是实际操作风险。 |
| docs/advanced/ii/ui/ui-performance.md | 显示开关:优先 hidden | 高 | `hidden` 与三元的取舍是每个面板都会遇到的。 |
| docs/advanced/ii/ui/ui-performance.md | 缓存:cache 与 nocache | 中 | 只有复杂稳定子树才需要,但默认值容易被误解。 |
| docs/advanced/ii/ui/ui-performance.md | 画面质量:hd、anti 与 noanti | 中 | 像素图才需要,普通 UI 用默认即可。 |
| docs/advanced/ii/ui/ui-performance.md | 列表与分页 | 高 | 大量列表的性能入口,和背包直接相关。 |
| docs/advanced/ii/ui/ui-performance.md | 组件粒度 | 中 | 拆分原则有用,但没有量化标准,容易凭感觉。 |
| docs/advanced/ii/ui/ui-performance.md | UI 栈 | 中 | 多面板时用,单面板可以跳过。 |
| docs/advanced/ii/ui/ui-performance.md | 基础 props | 低 | 多数作者不需要自定义基础参数创建函数。 |
| docs/advanced/ii/ui/ui-performance.md | 症状与排查 | 高 | 出问题时按表排查最实用。 |
| docs/advanced/ii/ui/ui-performance.md | 运行效果 | 中 | 能看 `hidden` 与 `cache` 开关,但不能真正测性能。 |
| docs/advanced/ii/ui/ui-performance.md | 边界与注意 | 高 | 缓存不是越多越好、`keep` 必须卸载、先测再改,都是收口建议。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | 最终要做成什么 | 高 | 我动手前会先确认目标范围和最终布局,这一节是唯一的总目标说明。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | 先把文件拆好 | 高 | 我会照着拆文件、定职责;但实际落地时缺目录和 import 信息,会反复回来找。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | 骨架代码 | 高 | 这是我要复制并逐步替换的基础代码,几乎每次开工都会打开。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | 打开它 | 高 | 不打开就看不到面板;我会反复回来确认场景 UI、面板内、主 UI 栈三种入口。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | 运行效果 | 中 | 我会看一眼目标样子,但 live 不能真的关闭,参考价值有限。 |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | 边界与注意 | 中 | 收尾自查时会看,尤其是“关闭按钮必须能用”和“Props 基类”两条。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | 数据模型 | 高 | 我要把自己的存档数据映射成 `Item`,会反复对照字段。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | ItemCell:一个格子 | 高 | 格子是最常改的部分(颜色、选中描边、名称数量位置),会反复翻。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | ItemGrid:按行列排列 | 高 | 列数、格子尺寸、间距的算法在这里,布局不合适就要回来改。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | 放回面板 | 高 | 选中状态归谁、网格怎么上报,是我接父子组件时最需要确认的一段。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | 运行效果 | 中 | 用来看选中效果,但 live 与正文的代码组织不同,不能直接对照。 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | 边界与注意 | 中 | 做自适应和后续增删道具时会回来核对列数、id、`key` 的提醒。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | 选中项由父组件派生 | 高 | 详情、按钮都要共用同一份选中数据,这段派生逻辑我会反复引用。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | ItemDetail:右侧面板 | 高 | 详情区的名称、数量、描述和空状态都在这,是最常改的一块。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | 运行效果 | 中 | 我会看空状态和详情切换,但 live 用等价元素,真实 `TextContent` 效果看不到。 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | 边界与注意 | 中 | `undefined` 处理、`TextContent` 宽度、`zIndex` 遮挡这几条会作为自查清单。 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | 方案一:Scroll 平铺(推荐) | 高 | 道具一多就必然要滚动,这是本篇主路径;`padEnd`、`scrollTo`、「子元素平铺」都是当场要用的。 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | 方案二:ListPage 左列表右详情 | 中 | 只有打算把背包改成「左列表右详情」才会用;已有网格布局的人多半只当备选参考。 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | 什么时候用 Scroll、ListPage、Page | 中 | 设计阶段选方案时看一次;实现时不太会回头查。 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | 运行效果 | 低 | 只能目视,live 又是元素层等价实现,抄不到代码。 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | 边界与注意 | 中 | 「包一层就失效」「key 对不上」「padEnd 要调」都是踩坑时回来核对的内容。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | ActionBar:底部按钮 | 高 | 可复用的按钮写法,禁用=弱化+早返回这条口径会直接用。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 状态放在 InventoryPanel | 高 | `computed` + `watch` + 状态上提是这一篇的核心,写业务时反复对照。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 已装备的格子 | 中 | 只有要做装备态时才用,而且给出的代码不完整,仍需自己补传递链。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 键盘收口 | 中 | 只有要 Esc 关闭面板时才需要,三行代码,用过一次就够。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 遮罩与 noevent | 中 | 加遮罩是常见需求,但放置层级说不清,实际会边试边查。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 组装 | 高 | 这是唯一把按钮、状态、回调接起来的地方,组装时必须看。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 运行效果 | 低 | 目视对照,无法复用代码。 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 边界与注意 | 中 | 「watch 别自循环」「别用 hidden 当禁用」这类提醒会在出错时回来查。 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 动画:只改 alpha 与 scale | 中 | 手写 RAF 的骨架有用,但示例没有并进真实面板,很多人会跳过或只抄清理逻辑。 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 拆分回顾 | 低 | 只是目录树复述,第 20 篇已给过,读过一次不会再看。 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 注册与打开 | 高 | 把面板变成可打开 UI 的最后一步,`GameUI` 与打开入口必须照做。 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 性能自查 | 低 | 一次性对号入座清单,读一遍就过;实现时不会反复查。 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 运行效果 | 低 | 最终成品的目视确认,不产生可复用代码。 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 边界与注意 | 中 | 动画必须清、注册不写全局表、props 逐层传,这几条会在收尾时核对。 |
## 声明
未读源码:是
未修改任何文档:是
live 目视验证:未执行(留到 10-50)
以上仅为读者视角的提问与使用概率判断,不构成对错判定,也不含修改方案;是否构成问题由用户在 10-50 裁决。
@@ -0,0 +1,343 @@
---
phase: 10-docs-restructure
plan: 50
type: execute
wave: 8
depends_on:
- 10-49
files_modified:
- docs/advanced/ii/ui/reactivity.md
- docs/advanced/ii/ui/events.md
- docs/advanced/ii/ui/hotkey-in-ui.md
- docs/advanced/ii/ui/conditional-and-list-rendering.md
- docs/advanced/ii/ui/props.md
- docs/advanced/ii/ui/component-tsx.md
- docs/advanced/ii/ui/slots-and-attrs.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 76000
raw_tokens: 45000
tasks: 6
confidence: low
must_haves:
truths:
- "Part 2–3 的 7 篇按 D-93 补齐深度:响应式如何驱动渲染树更新、事件命中与捕获/冒泡、按键与元素事件的边界、条件/列表与树的增删、props/组件/slots 如何映射成子树(D-93 第 1–4 条)"
- "事件篇必须核对源码后讲清捕获/冒泡顺序:父容器先捕获、命中元素先冒泡、父容器后冒泡;现文若写成「子元素先捕获」必须改正(D-72 / D-93 第 2 条)"
- "扩写不新增、不删除页面,仍为 25 篇正文与 24 个 demo;不改 demo、不改侧边栏、不改其它 18 篇"
- "每篇长度由内容决定:~300 行只是体量参考,不设下限/上限,不因低于 300 行失败;不注水(D-88)"
- "Round 1 的 116 条提问只作内部输入,不交给用户;扩写按 D-93 系统检查,不能只修列出的问题(D-91 / D-93 第 5 条)"
- "本计划只改 Part 2–3 的 7 篇与 NOTES;不写 SUMMARY、不改 ROADMAP / STATE、不 commit、不进入读者循环"
artifacts:
- "docs/advanced/ii/ui/{reactivity,events,hotkey-in-ui,conditional-and-list-rendering}.md(响应式与事件模型、按键、条件/列表的树更新)"
- "docs/advanced/ii/ui/{props,component-tsx,slots-and-attrs}.md(组件如何映射成子树、props 管线、生命周期、slots/attrs 边界)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 `## 10-50 深度扩写(Part 2–3)`:基线、D-93 覆盖表、体量参考、门禁、停止点)"
key_links:
- "先讲响应式如何触发树更新,再讲事件与组件:读者要先知道「数据变→组件重渲染→属性 patch→树更新」,才能理解事件回调改 ref 为什么会让画面变(D-93 第 1 条)"
- "事件顺序必须以源码为准:捕获/冒泡写反会让读者在嵌套容器里永远调不对顺序(D-72 / D-93 第 2 条)"
- "组件篇必须讲 props 管线:父组件传值→VNode props→组件 props 列表→setup props;漏掉任一环,读者就会把「传了没生效」归因错(D-93 第 3 条)"
- "条件/列表篇必须讲树的增删与 key:把 hidden、三元卸载、列表 diff 放在同一棵树上比较,读者才能判断状态会不会丢(D-93 第 1 条)"
---
<scope_justification>
本计划承担 25 篇中的 Part 2–3(7 篇)。切分理由与 10-49 相同:25 篇按每计划 ≤8 篇分为 7 / 7 / 5 / 6 四份,四份串行以保护共享 NOTES 与构建产物。
- Part 2(响应式、事件、按键、条件/列表)回答「界面怎么随数据与操作变化」;Part 3(props、组件、slots/attrs)回答「界面怎么拆成组件」。两者共享「组件树 → VNode → 渲染树」的同一套映射,放在一个计划里才能把「数据变→重渲染→patch→树更新」讲成一条链。
- 本计划不动 Part 4–5 的 11 篇;不新增/删除页面与 demo;不写 SUMMARY、不改 ROADMAP / STATE、不 commit。
</scope_justification>
<objective>
按 D-93 把 Part 2–3 的 7 篇从「会用 API」扩写到「理解模型」:讲清响应式数据如何触发组件重渲染并 patch 到渲染树;讲清命中测试、捕获/冒泡的真实顺序、enter/leave、`noevent` 子树、`actionStroke`、事件对象与嵌套容器传播;讲清按键系统与元素事件的边界;讲清条件/列表如何增删树节点、key 与状态保留;讲清 props 从父组件到 setup 的完整管线、组件生命周期与 `expose`、slots/attrs 的落点与边界。
Purpose: 读者在这 7 篇最容易出现「顺序靠猜、传值靠试、状态为什么丢不知道」的问题;只列事件名与 props 参数无法让读者独立排查(D-93)。
Output: 7 篇扩写后的正文 + NOTES 中的基线、D-93 覆盖表、体量参考与门禁记录。**不新增/删除页面、不改 demo、不改其它 18 篇、不写 SUMMARY / ROADMAP / STATE、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-48-PLAN.md
@.planning/phases/10-docs-restructure/10-49-PLAN.md
@.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
@docs/.vitepress/config.ts
**流程约定:**
- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-49` 计划与 SUMMARY、不改 POC 文件、不改 `docs/` 其它页面与 demo、不改 `packages/` / `packages-user/` / `src/`。
- **Task 0 是硬关卡**:汇报扩写范围、D-93 四类口径、事件顺序的核对要求、体量口径与停止条件,等用户明确回复「可以执行」。
- 修改方式为**派发子代理执行**;正文扩写一律派发子代理,改文件前先声明。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 代码注释;不 commit(D-90)。
- 写作口径按 D-59..D-74、D-77..D-88、D-91..D-93;示例注释按 D-65,代码块保留完整类上下文按 D-70,不写源码叙述按 D-80,不写使用概率元信息按 D-79。
- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。
**本批事实(执行时以这些为准):**
- 10-49 已完成 Part 0–1 的深度扩写并停在读者循环之前;本计划承接 Part 2–3,不重复 Part 0–1 已讲清的渲染树基础,只做必要回指。
- Round 1 记录 `10-49-READER-REVIEW.md` 含 25 篇、116 条提问、178 行分节概率;本计划只把其中与 Part 2–3 相关的提问作内部输入,不向用户转述。
- 事件顺序以 `packages/render/src/core/{item,container,event,render}.ts` 为准;`stopPropagation`、`noevent` 的子树行为、enter/leave 的 hover 集合行为必须先核对再写。
- 组件与 props 以 `packages/render-vue/src/{renderer,elements,props}.ts` 与 Vue 的 `defineComponent` 语义为准;`expose`、`emit`、slots 的写法按当前项目实际用法核对。
- 按键篇以 `packages/system/src/hotkey/*` 与 `packages-user/client-base/src/hotkey/*` 为准;不要把手写 `document.addEventListener` 当成推荐方案。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报 Part 2–3 扩写范围、事件顺序核对要求与停止条件,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CONTEXT.md(D-88、D-91、D-92、D-93)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-49 扩写小节与命名总表)、docs/advanced/ii/ui/ 下 7 篇现文、docs/.vitepress/config.ts</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——按 D-93 深度扩写 Part 2–3 的 7 篇(`reactivity`、`events`、`hotkey-in-ui`、`conditional-and-list-rendering`、`props`、`component-tsx`、`slots-and-attrs`)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不进入读者循环与用户审阅。
**为什么**——这 7 篇是「界面怎么随数据与操作变化、怎么拆组件」的核心,但当前更多在列事件名、props 参数与写法,没有把「数据变→重渲染→patch→树更新」「捕获/冒泡真实顺序」「props 从父到 setup 的管线」「条件/列表如何增删节点」讲成模型。读者会靠试错而不是推理。
**大致怎么做**——Task 1 先写基线与 D-93 覆盖表(7 篇 × 渲染树/事件/元素组件/示例解释);Task 2 扩写响应式与事件 2 篇,事件顺序以源码核对并改正现文可能的反写;Task 3 扩写按键与条件/列表 2 篇;Task 4 扩写 props、组件、slots/attrs 3 篇;Task 5 跑门禁、D-93 抽查、体量记录并停止。
**影响范围**——只改上述 7 篇与 NOTES。不改其余 18 篇、两份导览、侧边栏、24 个 demo、`packages/` / `packages-user/` / `src/`、既有 JSDoc/注释、ROADMAP / STATE;不写 SUMMARY;不 commit。
**事件顺序的核对要求(重点):**
- 先读 `packages/render/src/core/{item,container,event}.ts`,确认捕获阶段从根向命中元素、冒泡阶段从命中元素向根;容器在捕获阶段按 `zIndex` 从高到低把事件交给子级。
- 现文若出现「子元素先捕获」这类与源码不符的表述,必须改正为「父容器先捕获、命中元素先冒泡、父容器后冒泡」,并在对话中报告修正点;不要把源码行号写进正文(D-80 / D-72)。
- `stopPropagation` 讲清「只停止继续传播,不阻止同一元素上的其它监听器」;`noevent` 讲清「整个子树不参与命中,不是只跳过自身」;enter/leave 讲清「由根的 hover 集合统一触发,不走普通冒泡」。
**体量口径**——每篇长度由内容决定;~300 行只是参考,不是门禁;不注水、不因低于 300 行失败(D-88)。
**Round 1 边界**——116 条提问只作内部输入,不交给用户;扩写按 D-93 系统检查,不能只修列出的问题。
**请用户确认:**
1. 扩写范围是 Part 2–3 的 7 篇;不新增/删除页面与 demo,不改其它 18 篇与导览。
2. 事件篇必须以源码核对捕获/冒泡顺序,现文不符要改正;`stopPropagation` / `noevent` / enter-leave 的口径按上面写。
3. 四类 D-93 内容逐页判定;不适用写「不适用:理由」,不能留空或写「待补」。
4. 体量只记录不设门禁;不注水。
5. 停止条件:扩写与门禁结束即停止;不进入读者循环、不写 SUMMARY / ROADMAP / STATE、不 commit。
6. 本次修改方式为**派发子代理执行**;不改既有注释;不调用 `opencode` 命令。
**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报扩写范围、D-93 口径、事件顺序核对要求、体量口径与停止条件。</what-built>
<how-to-verify>确认:①7 篇范围与不改批外内容;②事件顺序以源码为准、现文不符要改正;③`stopPropagation` / `noevent` / enter-leave 口径;④四类 D-93 逐页判定、允许「不适用:理由」;⑤体量不设门禁;⑥结束即停、不写 SUMMARY / ROADMAP / STATE、不 commit。</how-to-verify>
<resume-signal>回复「可以执行」以继续;其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且扩写范围、事件顺序口径、D-93 四类口径、体量口径、停止条件、派发方式六项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,且扩写范围、事件顺序口径、D-93 口径、体量口径、停止条件、派发方式均已确认。</human-check>
</verify>
<done>用户回复「可以执行」且六项待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 扩写前基线 + D-93 覆盖表 + 体量参考(不改正文)</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>`10-49` 已写入 `停止点:10-49 扩写结束`;`10-CUSTOM-UI-NOTES.md` 含 `## 10-49 深度扩写(Part 0–1)`;用户已在 Task 0 回复「可以执行」。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-49 扩写小节、命名总表)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/ui/ 下 7 篇现文与其余 18 篇文件名</read_first>
<action>**本任务只建基线与覆盖表,绝对不改 `docs/` 正文、不改 ROADMAP / STATE。**
向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-50 深度扩写(Part 2–3)` 小节,依次写入:
1. `扩写范围:` + Part 2–3 的 7 篇完整路径;写「不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 18 篇与两份导览」。
2. `Round 1 内部输入:` + `10-49-READER-REVIEW.md(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单`。
3. `基线 HEAD(10-50 深度扩写):` + `git rev-parse HEAD` 完整 sha。
4. `扩写前本批页面聚合哈希:` + 对 7 篇取聚合 SHA-256(算法与 10-49 Task 1 相同:按 `docs/advanced/ii/ui/...` 相对路径排序,逐文件取 SHA-256,拼 `相对路径:hash` 后 LF 连接,再 SHA-256)。
5. `本批外文件聚合哈希:` + 对其余 18 篇 + `docs/advanced/ii/index.md` + `docs/advanced/index.md` 取同一算法聚合 SHA-256。
6. `ROADMAP 全文哈希:` 与 `STATE 全文哈希:` + 各自全文 SHA-256。
7. `### D-93 覆盖表` + 7 行表格,表头逐字 `| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |`;四类内容格先写 `待补`,确不适用写 `不适用:<理由>`;行数写当前值。
8. `体量参考(非门禁):` + 7 篇当前总行数与平均行数,写明「~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)」。
9. `停止点:10-50 只做 Part 2–3 深度扩写;不改 10-51..10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。`
**本任务不得修改任何 `docs/` 文件、不得改 ROADMAP / STATE、不得派发扩写子代理。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-50 深度扩写(Part 2–3)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '停止点:10-49 扩写结束'){ Write-Error 'NO-1049-STOP' }; $pages=@('docs/advanced/ii/ui/reactivity.md','docs/advanced/ii/ui/events.md','docs/advanced/ii/ui/hotkey-in-ui.md','docs/advanced/ii/ui/conditional-and-list-rendering.md','docs/advanced/ii/ui/props.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/slots-and-attrs.md'); foreach($k in @('## 10-50 深度扩写(Part 2–3)','扩写范围:','Round 1 内部输入:','基线 HEAD(10-50 深度扩写):','扩写前本批页面聚合哈希:','本批外文件聚合哈希:','ROADMAP 全文哈希:','STATE 全文哈希:','D-93 覆盖表','体量参考(非门禁):','停止点:10-50 只做')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-50 深度扩写):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('扩写前本批页面聚合哈希','本批外文件聚合哈希','ROADMAP 全文哈希','STATE 全文哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; $rows=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/' }); if($rows.Count -ne 7){ Write-Error ('MATRIX-ROWS:'+$rows.Count) }; foreach($p in $pages){ if(-not ($rows | Where-Object { $_.IndexOf($p) -ge 0 })){ Write-Error "NO-MATRIX-ROW $p" } }; foreach($r in $rows){ $c=@($r.Trim('|') -split '\|'); if($c.Count -lt 6){ Write-Error 'MATRIX-COLS' }; for($i=0;$i -lt 6;$i++){ if([string]::IsNullOrWhiteSpace($c[$i])){ Write-Error 'MATRIX-EMPTY' } } }; if($np -notmatch '116 条提问'){ Write-Error 'NO-ROUND1-COUNT' }; if($np -notmatch '178 行分节概率'){ Write-Error 'NO-PROB-COUNT' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-1049-STOP", "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NO-MATRIX-SECTION", "MATRIX-ROWS", "NO-MATRIX-ROW", "MATRIX-COLS", "MATRIX-EMPTY", "NO-ROUND1-COUNT", "NO-PROB-COUNT", "MD-COUNT", "DEMO-COUNT"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 有 `## 10-50 深度扩写(Part 2–3)` 与九项固定行;覆盖表 7 篇完整路径、六列、四类内容格非空(`待补` 或 `不适用:理由`)、行数为数字;Round 1 计数已记录且明确仅内部;四个哈希为 64 位小写 hex;25 篇 / 24 demo 不变;未改任何 `docs/` 正文、未改 ROADMAP / STATE。</acceptance_criteria>
<done>Part 2–3 扩写基线与覆盖表已落盘,正文未动。</done>
</task>
<task type="auto">
<name>Task 2: 扩写响应式与事件 2 篇(数据驱动与真实传播顺序)</name>
<files>docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1 已写入 `## 10-50 深度扩写(Part 2–3)` 与覆盖表;7 篇现文未被本计划改动。</precondition>
<read_first>docs/advanced/ii/ui/{reactivity,events}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 2 篇的提问)、packages/render-vue/src/renderer.ts(patchProp / insert / remove)、packages/render/src/core/{item,container,event,render,graphics}.ts(命中、zIndex 排序、捕获/冒泡、hover、noevent、actionStroke)、docs/advanced/ii/ui/container-and-coordinates.md(10-49 已扩写的渲染树与坐标,只回指不重抄)</read_first>
<action>**只改这 2 篇与 NOTES;不碰其它篇目与 demo。**
**(1)`reactivity.md`**
- 新增 `## 数据变化如何走到渲染树`:`ref` / `computed` / `shallowRef` 的读写触发组件重渲染;重渲染生成新 VNode,渲染器对同一元素做属性 patch(不是整棵树重建);只有属性真的变化才改元素;子组件是否重渲染取决于 props 与自身依赖。把「数据 → 组件 → VNode → 元素属性 → 绘制」讲成一条链。
- 新增 `## 什么时候会重渲染、什么时候不会`:依赖收集的粒度;在事件回调里改 `ref` 会触发;直接改非响应式对象不会;`computed` 缓存;批处理/异步更新对「连续改多次」的影响(按 Vue 当前版本核对,不写错版本行为)。
- 新增 `## 响应式与元素生命周期的边界`:重渲染不等于重建;`v-if` / 三元才会卸载;`hidden` 只切显示;`ref` 到子组件与 `ref(0)` 响应式值的区别(两处 `ref` 同名不同义),给一个对照例子。
- 新增 `## 响应式作为界面零件`:面板开关、选中项、计数、列表数据四类典型状态;每类说明该放组件内还是提到父级,以及为什么。
**(2)`events.md`**
- 扩写 `## 命中测试:事件先找最上层元素`:命中从根容器开始,按兄弟 `zIndex` 从高到低、同层按子元素顺序找最上层被点到的元素;`hidden` 不绘制也不参与命中;`noevent` 整个子树不参与命中(不是只跳过自身),事件下穿到兄弟/下层;图形命中按几何,`actionStroke` 只把描边算命中。
- 修正 `## 捕获与冒泡`:以源码核对后写成「捕获从根容器向命中元素传递,冒泡从命中元素向根容器传递;父容器先捕获,命中元素随后捕获并先冒泡,父容器最后冒泡」。若现文「子元素先捕获」与源码不符,必须改正并在对话中报告。给一个三层嵌套的例子,用日志顺序说明完整序列。
- 扩写 `stopPropagation`:只停止继续传播,不阻止同一元素上的其它监听器;捕获阶段停止后不再向内,冒泡阶段停止后不再向外;给出「同一元素两个监听器都执行」的例子。
- 扩写 `## enter 与 leave 不走普通冒泡`:由根的 hover 集合在每次移动后做差集统一触发;先 leave 后 enter;父容器只有在自身也在 hover 集合里时才收到;不要把 enter/leave 当成冒泡事件。
- 新增 `## 事件坐标与变换`:`offsetX/offsetY` 是相对当前元素、经过变换反算后的局部坐标;`absoluteX/absoluteY` 是画布坐标;缩放/旋转后两者关系;嵌套容器里如何判断点击落在哪个元素。
- 扩写 `## 事件对象`:补 `target`(当前监听元素)、`touch`、`type`/`buttons` 的位运算、`identifier` 在多指中的用途;说明事件对象在捕获与冒泡阶段是同一份还是各自计算(按源码写,不猜)。
- 新增 `## 嵌套容器中的传播`:一个父容器 + 两个重叠子元素的完整例子,说明点击命中谁、捕获/冒泡各经过谁、`stopPropagation` 放在哪一层会得到什么结果;代码后解释它在树上的路径。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表这 2 行为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $p1='docs/advanced/ii/ui/reactivity.md'; $p2='docs/advanced/ii/ui/events.md'; foreach($p in @($p1,$p2)){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $a=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p1)); foreach($k in @('重渲染','VNode','patch','ref','computed','hidden','生命周期')){ if($a.IndexOf($k) -lt 0){ Write-Error "REACTIVITY-MISSING $k" } }; $b=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p2)); foreach($k in @('捕获','冒泡','stopPropagation','noevent','actionStroke','offsetX','absoluteX','hover')){ if($b.IndexOf($k) -lt 0){ Write-Error "EVENTS-MISSING $k" } }; $evtBad=@($b -split "`r?`n" | Where-Object { $_ -match '子元素先捕获' -and $_ -notmatch '不是|并非|而不是|不要' }); if($evtBad.Count -gt 0){ Write-Error 'EVENT-ORDER-STILL-WRONG' }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-50 深度扩写(Part 2–3)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in @($p1,$p2)){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in @($p1,$p2)){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check $p1 $p2" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "REACTIVITY-MISSING", "EVENTS-MISSING", "EVENT-ORDER-STILL-WRONG", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>响应式篇讲清数据→组件→VNode→元素属性→绘制的链路、重渲染与不重渲染的条件、`hidden` 与三元/`v-if` 的生命周期差异、两种 `ref` 的区别;事件篇讲清命中顺序、捕获/冒泡真实顺序(不得残留肯定式「子元素先捕获」,否定式解释允许)、`stopPropagation` 同元素语义、`noevent` 子树、enter/leave hover 集合、坐标与变换、嵌套传播完整例子。每次代码后有模型解释;NOTES 覆盖表 2 行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>响应式与事件 2 篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 3: 扩写按键与条件/列表 2 篇(事件边界与树增删)</name>
<files>docs/advanced/ii/ui/hotkey-in-ui.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2 已写入 2 条 `已完成扩写:`;覆盖表这 2 行无 `待补`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>docs/advanced/ii/ui/{hotkey-in-ui,conditional-and-list-rendering}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 2 篇的提问)、packages/system/src/hotkey/{system,keyboard,command,types}.ts、packages-user/client-base/src/hotkey/*(`useKey`、注册、优先级、注销)、packages/render-vue/src/{renderer,elements}.ts(条件/列表的 VNode 与 key 处理)、docs/advanced/ii/ui/layer-transform-performance.md(hidden vs 三元,只回指)</read_first>
<action>**只改这 2 篇与 NOTES;不碰其它篇目与 demo。**
**(1)`hotkey-in-ui.md`**
- 新增 `## 按键与元素事件是两条路径`:元素事件来自画布命中;按键来自键盘系统,不经过元素命中;两者可能同时存在,要说明谁先、谁会被 UI 栈拦截(以实际 hotkey 系统为准)。
- 新增 `## 按键系统的模型`:注册、绑定、作用域/优先级、冲突处理、注销;`useKey` 在组件里如何拿到系统、组件卸载时是否自动清理;不要把手写 `document.addEventListener` 当成推荐方案。
- 新增 `## 在 UI 里接按键的典型场景`:Esc 关闭面板、Enter 确认、方向键移动选中;每个场景说明为什么用按键而不是元素事件、如何在面板打开时抢占、关闭后如何恢复。
- 新增 `## 按键与 UI 栈的关系`:面板叠放时哪个面板收到按键;背景 UI 是否还能响应;关闭当前面板后按键归属如何变化。
- 补 import 来源与最小示例(按项目实际导出核对),示例后解释它在事件模型中的位置。
**(2)`conditional-and-list-rendering.md`**
- 新增 `## 条件渲染改的是树,不是样式`:三元/`v-if` 为 false 时节点被卸载,组件状态与生命周期重置;`hidden` 保留实例与状态,只跳过绘制与命中;把两种做法放在同一棵树上比较,给出选择表(与 10-49 的层级篇口径一致)。
- 新增 `## 列表渲染与 key`:列表 diff 依据 key 判断「同一个节点」;用下标当 key 在插入/删除/排序时会把状态错配;稳定 id 才适合;无状态静态列表可以不用 key,但要说明边界。
- 新增 `## 数据怎么变才会更新列表`:`push` / `splice` / 整体替换 / `ref` 数组的赋值分别会发生什么(按 Vue 当前版本核对);`computed` 派生列表的缓存;不要把「改了数组但画面没动」归因成渲染器问题。
- 新增 `## 列表项的事件与状态`:每项的事件回调如何拿到当前项;删除一项时事件与选中态如何处理;嵌套列表的 key 作用域。
- 新增 `## 条件/列表的树形示意`:给一个「父容器 → 条件分支 → 列表 → 列表项」的完整例子,代码后解释增删发生在哪一层、哪些状态保留、哪些重建。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表这 2 行为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $p1='docs/advanced/ii/ui/hotkey-in-ui.md'; $p2='docs/advanced/ii/ui/conditional-and-list-rendering.md'; foreach($p in @($p1,$p2)){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $a=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p1)); foreach($k in @('按键','useKey','注册','优先级','UI 栈','卸载')){ if($a.IndexOf($k) -lt 0){ Write-Error "HOTKEY-MISSING $k" } }; $b=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p2)); foreach($k in @('卸载','hidden','key','splice','computed','列表')){ if($b.IndexOf($k) -lt 0){ Write-Error "COND-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-50 深度扩写(Part 2–3)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in @($p1,$p2)){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in @($p1,$p2)){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check $p1 $p2" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "HOTKEY-MISSING", "COND-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>按键篇讲清按键与元素事件两条路径、按键系统模型(注册/优先级/冲突/注销)、UI 内典型场景、与 UI 栈的关系;条件/列表篇讲清卸载与 `hidden` 的树差异、key 规则、数据变更如何触发更新、列表项事件与状态、完整的树形示例。每次代码后有模型解释;NOTES 覆盖表 2 行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>按键与条件/列表 2 篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 4: 扩写 props、组件、slots/attrs 3 篇(组件如何映射成子树)</name>
<files>docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/component-tsx.md, docs/advanced/ii/ui/slots-and-attrs.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 已写入 2 条 `已完成扩写:`;覆盖表这 2 行无 `待补`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>docs/advanced/ii/ui/{props,component-tsx,slots-and-attrs}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 3 篇的提问)、packages/render-vue/src/{renderer,elements,props,index}.ts(props / attrs / slots 到元素树的落点)、packages/system/src/ui/types.ts(UIComponent 与默认 props)、Vue 当前版本的 `defineComponent` / `SlotsType` 用法(以项目实际类型为准)</read_first>
<action>**只改这 3 篇与 NOTES;不碰其它篇目与 demo。**
**(1)`props.md`**
- 新增 `## props 的完整管线`:父组件写属性 → VNode 的 props → 组件声明的 `props` 列表 → setup 里拿到的 props;未声明的键落到 `attrs`,不会进 props;属性名用 camelCase;漏写 props 数组不会报错但拿不到值。把这条链画成文字流程,并用一个「传了没生效」的例子逐环排查。
- 新增 `## props 是响应式的,但解构会丢响应式`:直接读 `props.x` 会跟随更新;解构或提前存到普通变量会丢;需要派生值用 `computed`;需要本地副本时说明同步策略。
- 新增 `## props、attrs 与组件边界的职责`:哪些值该走 props(组件声明的输入),哪些走 attrs(透传给根元素),哪些该走 slot(内容而非数据);给一个选择表。
- 新增 `## props 与渲染树`:props 变化触发组件重渲染,最终落到元素属性;不改变树结构的 props 只 patch 属性,不重建子树;`key` 变化才会重建。
**(2)`component-tsx.md`**
- 新增 `## 组件如何映射成一棵子树`:组件实例 → render 函数返回的 VNode → 元素层子树;组件嵌套就是子树嵌套;组件的根元素是它在父树中的挂载点。
- 扩写 `defineComponent` 的泛型与第二参数:逐个说明 Props / Emits / Slots 的位置,哪些可以省、省略后还能不能用 `emit`;第二参数(`SetupComponentOptions` 或项目自定义 options)里放什么;不要只给一个「照抄」的签名。
- 新增 `## 生命周期与渲染树`:创建、挂载、更新、卸载分别对应树的哪些操作;`onMounted` / `onUnmounted` 里适合做什么(订阅、定时器、纹理释放);卸载时什么会自动清理、什么必须手动清理。
- 新增 `## expose、emit 与父组件拿子组件`:`expose` 暴露什么、父组件 `ref` 拿到的是什么;`emit` 与 props 回调的取舍;两种 `ref` 的区别(响应式值 vs 组件实例)。
- 新增 `## 组件拆分与树的边界`:什么时候拆组件(复用、状态隔离、渲染性能),什么时候不拆(只为一层结构);拆完后 props/slots 怎么走。
**(3)`slots-and-attrs.md`**
- 新增 `## slot 是内容,不是数据`:默认 slot、具名 slot、作用域 slot 的区别;slot 内容在父组件的渲染树里求值,再插入子组件的位置;不要把 slot 当成 props。
- 新增 `## attrs 的落点与透传`:未声明 props 的属性进入 `attrs`;默认透传到子组件根元素;`inheritAttrs: false` 时手动绑定到哪里;事件监听器作为 attrs 透传时的行为。
- 新增 `## 组件边界上的事件与属性`:父组件在子组件标签上写 `onClick` 会落到哪;子组件根元素是否接收;需要转发时怎么写;避免「点了没反应」。
- 新增 `## slots/attrs 在渲染树里的位置`:给一个「父组件 → 子组件 → 默认 slot / 具名 slot / 透传属性」的完整例子,代码后解释每一段内容最终落在哪棵子树、哪个元素上。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整类/组件上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表这 3 行为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $pages=@('docs/advanced/ii/ui/props.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/slots-and-attrs.md'); foreach($p in $pages){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $a=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[0])); foreach($k in @('props','attrs','管线','camelCase','computed','渲染树')){ if($a.IndexOf($k) -lt 0){ Write-Error "PROPS-MISSING $k" } }; $b=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[1])); foreach($k in @('defineComponent','生命周期','expose','emit','子树','ref')){ if($b.IndexOf($k) -lt 0){ Write-Error "COMPONENT-MISSING $k" } }; $c=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[2])); foreach($k in @('slot','attrs','inheritAttrs','透传','事件','渲染树')){ if($c.IndexOf($k) -lt 0){ Write-Error "SLOTS-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-50 深度扩写(Part 2–3)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in $pages){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths=($pages -join ' '); $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "PROPS-MISSING", "COMPONENT-MISSING", "SLOTS-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>props 篇讲清完整管线、响应式与解构边界、props/attrs/slot 职责、props 变化到渲染树的落点;组件篇讲清组件→子树映射、`defineComponent` 泛型/第二参数、生命周期与树操作、`expose`/`emit`/`ref`、拆分边界;slots/attrs 篇讲清 slot 是内容、attrs 透传与 `inheritAttrs`、组件边界事件、完整落点示例。每次代码后有模型解释;NOTES 覆盖表 3 行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>props、组件、slots/attrs 3 篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 5: 门禁 + D-93 抽查 + 体量记录 + 停止</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2–4 已把 7 篇的四类内容格改为 `已讲`(或 `不适用:理由`),并各写入 `自查:` 与 `已完成扩写:`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-50 深度扩写(Part 2–3)` 全部内容)、docs/advanced/ii/ui/ 下 7 篇、.planning/ROADMAP.md、.planning/STATE.md</read_first>
<action>**只校验、记录与停止;除 NOTES 外不改任何文件。**
1. **D-93 抽查**:逐篇核对四类内容;每篇写 `D-93 抽查:<path> — 通过` 或 `— 发现缺口(缺口一句)`;有缺口先修到通过。
2. **事件顺序复核**:确认 `events.md` 不再出现肯定式「子元素先捕获」(否定式解释「不是子元素先捕获,而是父容器先捕获」允许),且捕获/冒泡顺序与源码一致;`stopPropagation`、`noevent` 子树、enter/leave 口径正确。
3. **结构门禁**:25 篇 / 24 demo 不变;7 篇 CRLF;无 `待补` 覆盖格;每篇有 `自查:` 与 `已完成扩写:`;无「模板 / 需改 / 简化版 / v1 / 以后再做」。
4. **聚合哈希门禁**:重算 `本批外文件聚合哈希`、`ROADMAP 全文哈希`、`STATE 全文哈希`,与 Task 1 一致;重算 `扩写后本批页面聚合哈希`,必须与扩写前不同。
5. **prettier**:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后 `--check`。
6. **ESLint**:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,exit 0、输出不含 `error` / `warning`。
7. **docs 类型**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,`docs/` 路径 0 条 `error TS`;既有引擎报错只记录条数。
8. **构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,exit 0、含 `build complete`、无 `dead link`;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。
9. **写 NOTES**:追加 `扩写后本批页面聚合哈希`、`体量参考(扩写后)`(逐篇行数 + 总行数,再次写明不设 300 行门禁)、`### 10-50 门禁`(命令、结果、`docs/` 路径 0 类型错误、既有引擎报错条数、构建耗时、25 HTML、D-93 逐篇结论、事件顺序复核结论)、`停止点:10-50 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-51..10-54;未 commit。`
10. **立即停止**:不创建 SUMMARY、不改 ROADMAP / STATE、不 commit、不派发读者。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-50 深度扩写(Part 2–3)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; $pages=@('docs/advanced/ii/ui/reactivity.md','docs/advanced/ii/ui/events.md','docs/advanced/ii/ui/hotkey-in-ui.md','docs/advanced/ii/ui/conditional-and-list-rendering.md','docs/advanced/ii/ui/props.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/slots-and-attrs.md'); foreach($k in @('扩写后本批页面聚合哈希:','体量参考(扩写后):','### 10-50 门禁','D-93 抽查:','停止点:10-50 扩写结束','事件顺序复核')){ if($sec.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($sec -notmatch '(?m)^扩写后本批页面聚合哈希:[0-9a-f]{64}'){ Write-Error 'NO-POST-HASH' }; $mpre=[regex]::Match($sec,'(?m)^扩写前本批页面聚合哈希:([0-9a-f]{64})'); $mpost=[regex]::Match($sec,'(?m)^扩写后本批页面聚合哈希:([0-9a-f]{64})'); if(-not $mpre.Success -or -not $mpost.Success){ Write-Error 'NO-BATCH-HASH' }; if($mpre.Groups[1].Value -eq $mpost.Groups[1].Value){ Write-Error 'BATCH-UNCHANGED' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; if($m.Groups[1].Value -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; foreach($p in $pages){ if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" }; if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" } }; $d93bad=@(); foreach($p in $pages){ $d93lines=@($sec -split "`r?`n" | Where-Object { $_ -match ('^D-93 抽查:'+[regex]::Escape($p)) }); if($d93lines.Count -eq 0){ $d93bad += ($p+':NO-LINE') } elseif($d93lines[-1] -match '发现缺口'){ $d93bad += $p } }; if($d93bad.Count -gt 0){ Write-Error ('D93-GAP '+($d93bad -join ',')) }; $ev=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/ui/events.md')); $evtBad=@($ev -split "`r?`n" | Where-Object { $_ -match '子元素先捕获' -and $_ -notmatch '不是|并非|而不是|不要' }); if($evtBad.Count -gt 0){ Write-Error 'EVENT-ORDER-STILL-WRONG' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($p in $pages){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match "(?<!\r)\n"){ Write-Error "LF-ONLY $p" }; if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $sorted=@($pages | Sort-Object); $joined=($sorted | ForEach-Object { $_ + ':' + ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $_)))).Replace('-','').ToLower()) }) -join "`n"; $h=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($joined))).Replace('-','').ToLower(); if($sec -notmatch ('(?m)^扩写后本批页面聚合哈希:'+$h)){ Write-Error 'POST-HASH-MISMATCH' }; $roadText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md')); $roadHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($roadText))).Replace('-','').ToLower(); $mr=[regex]::Match($np,'(?m)^ROADMAP 全文哈希:([0-9a-f]{64})'); if(-not $mr.Success -or $mr.Groups[1].Value -ne $roadHash){ Write-Error 'ROADMAP-MODIFIED' }; $stText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); $stHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($stText))).Replace('-','').ToLower(); $ms=[regex]::Match($np,'(?m)^STATE 全文哈希:([0-9a-f]{64})'); if(-not $ms.Success -or $ms.Groups[1].Value -ne $stHash){ Write-Error 'STATE-MODIFIED' }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr=@($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-ErroLine truncated
<fails_when>non-zero exit, or output contains "NOTES-MISSING", "NO-POST-HASH", "NO-BATCH-HASH", "BATCH-UNCHANGED", "NO-MATRIX-SECTION", "MATRIX-STILL-PENDING", "NO-SELF-CHECK", "NO-DONE", "D93-GAP", "EVENT-ORDER-STILL-WRONG", "MD-COUNT", "DEMO-COUNT", "LF-ONLY", "SCOPE-REDUCTION", "POST-HASH-MISMATCH", "ROADMAP-MODIFIED", "STATE-MODIFIED", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "UNEXPECTED-SUMMARY"; or output lacks "T5-OK"</fails_when>
</verify>
<acceptance_criteria>7 篇覆盖格无 `待补`、逐篇 `自查:` / `已完成扩写:`、`D-93 抽查` 无缺口;事件篇不含「子元素先捕获」且事件顺序复核通过;`扩写后本批页面聚合哈希` 与扩写前不同且与重算一致;批外/ROADMAP/STATE 哈希未变;25 篇 / 24 demo 不变;7 篇 CRLF、无降级表述;prettier / ESLint 0/0 / `docs/` 路径 0 类型错误 / 构建 green + 0 dead link / 25 个 HTML;NOTES 有体量参考、`### 10-50 门禁`、事件顺序复核、停止点;未创建 SUMMARY。</acceptance_criteria>
<done>Part 2–3 扩写完成并通过门禁,停在读者循环之前。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 写作者 → 正文 | 必须讲模型与顺序,不能只列事件名 / props 参数 |
| 事件文档 → 源码事实 | 捕获/冒泡顺序、`stopPropagation`、`noevent`、enter/leave 必须以源码为准 |
| 本计划 → 批外文档 | 只允许改 7 篇;其余 18 篇、导览、demo、侧边栏不得改动 |
| 本计划 → 账本 | 不写 SUMMARY、不改 ROADMAP / STATE、不 commit |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-174 | Tampering | 事件顺序写反 | high | mitigate | Task 2 先核对源码;verify 断言 `events.md` 不含「子元素先捕获」;Task 5 复核 |
| T-10-175 | Tampering | 批外文档被改动 | high | mitigate | Task 1 记录 `本批外文件聚合哈希`;Task 5 重算比对 |
| T-10-176 | Repudiation | 扩写退化为只补读者问题 | high | mitigate | D-93 四类覆盖表逐页判定;覆盖格必须 `已讲` 或 `不适用:理由`;Task 5 抽查 |
| T-10-177 | Tampering | 为凑 300 行注水 | medium | mitigate | 体量只记录不设门禁;禁止接口表堆砌与降级表述 |
| T-10-178 | Information Disclosure | 把 Round 1 读者记录交给用户 | medium | mitigate | Round 1 仅内部输入;本计划不产出用户可读审阅摘要 |
| T-10-179 | Repudiation | 越界写 SUMMARY / ROADMAP / STATE | medium | mitigate | Task 5 校验 ROADMAP / STATE 全文哈希;禁止创建 SUMMARY |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 关卡门禁:Task 0 已获「可以执行」;10-49 已写入停止点。
- 基线门禁:Task 1 写入 7 篇范围、Round 1 计数、基线 HEAD、两个聚合哈希、两个账本哈希、D-93 覆盖表、体量参考。
- 覆盖门禁:7 篇四类内容格为 `已讲` 或 `不适用:理由`,无 `待补`;每篇有 `自查:` 与 `已完成扩写:`;`D-93 抽查` 无缺口。
- 事件门禁:`events.md` 不含「子元素先捕获」;捕获/冒泡、`stopPropagation`、`noevent` 子树、enter/leave 口径与源码一致;Task 5 记录复核结论。
- 范围门禁:25 篇 / 24 demo;`本批外文件聚合哈希` 与基线一致;未改导览、侧边栏、`packages*` / `src`。
- 质量门禁:7 篇 CRLF;prettier `--check`;ESLint 0/0;`docs/` 路径 0 类型错误;构建 green + 0 dead link;25 个 HTML。
- 体量门禁:只记录行数;不设 300 行下限/上限;不因低于 300 行失败。
- 停止门禁:NOTES 有 `停止点:10-50 扩写结束`;未创建 SUMMARY;ROADMAP / STATE 哈希未变;未 commit。
</verification>
<success_criteria>
- Part 2–3 的 7 篇按 D-93 讲清响应式链路、事件真实传播顺序、按键边界、条件/列表的树增删、props 管线、组件生命周期与 slots/attrs 落点。
- 读者能独立复述捕获/冒泡顺序、props 从父到 setup 的路径、key 与状态保留的关系,并能改写示例。
- 事件篇不再出现与源码不符的顺序表述;没有新增/删除页面与 demo,没有改动批外文档与源码。
- 门禁全绿,体量只作参考记录,本计划停在读者循环之前。
</success_criteria>
<output>
本计划**不写 SUMMARY**。完成后在对话中报告 7 篇扩写清单、逐篇行数(体量参考)、事件顺序修正点、D-93 抽查结论与门禁结果,然后停止。读者循环由 `10-53-PLAN.md` 执行,用户审阅由 `10-54-PLAN.md` 执行。
</output>
@@ -0,0 +1,332 @@
---
phase: 10-docs-restructure
plan: 51
type: execute
wave: 9
depends_on:
- 10-50
files_modified:
- docs/advanced/ii/ui/builtin-text-and-input.md
- docs/advanced/ii/ui/builtin-list-and-containers.md
- docs/advanced/ii/ui/ui-controller-and-stack.md
- docs/advanced/ii/ui/replace-builtin-ui.md
- docs/advanced/ii/ui/ui-performance.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 58000
raw_tokens: 34000
tasks: 6
confidence: low
must_haves:
truths:
- "Part 4 的 5 篇按 D-93 讲清内置组件/UI 系统的具体用法、重要功能、典型组合、注意事项与设计原因,不能只给 props 表(D-93 第 3 条)"
- "内置组件必须说明它在渲染树中的落点、事件如何进入、与 props/slots 的关系;UI 系统必须说明栈、背景、策略、实例生命周期与事件归属(D-93 第 1–2 条)"
- "扩写不新增、不删除页面,仍为 25 篇正文与 24 个 demo;不改 demo、不改侧边栏、不改其它 20 篇"
- "每篇长度由内容决定:~300 行只是体量参考,不设下限/上限,不因低于 300 行失败;不注水(D-88)"
- "Round 1 的 116 条提问只作内部输入,不交给用户;扩写按 D-93 系统检查(D-91 / D-93 第 5 条)"
- "本计划只改 Part 4 的 5 篇与 NOTES;不写 SUMMARY、不改 ROADMAP / STATE、不 commit、不进入读者循环"
artifacts:
- "docs/advanced/ii/ui/{builtin-text-and-input,builtin-list-and-containers}.md(内置组件的用法、组合、事件与树落点)"
- "docs/advanced/ii/ui/{ui-controller-and-stack,replace-builtin-ui,ui-performance}.md(UI 栈与背景模型、替换内置 UI、性能边界)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 `## 10-51 深度扩写(Part 4)`:基线、D-93 覆盖表、体量参考、门禁、停止点)"
key_links:
- "内置组件必须先讲「它替你决定了什么」:文本换行、列表选中、滚动裁剪、弹窗层级都是组件内置行为,读者不知道边界就会重复造轮子或与组件打架(D-93 第 3 条)"
- "UI 栈篇必须把「谁收到事件、谁盖住谁、背景何时显示」讲成一套模型:否则读者在多层面板下无法判断按键/点击归属(D-93 第 2 条)"
- "替换内置 UI 必须讲注册点与风险:只讲「写个同名 UI」会让读者覆盖后丢存档/设置/工具栏行为(D-93 第 3 条)"
- "性能篇必须把缓存、显示开关、列表/滚动、命中测试放在同一棵树上解释,不能只给「少用缓存」的口号(D-93 第 1 条)"
---
<scope_justification>
本计划承担 25 篇中的 Part 4(5 篇)。切分理由与 10-49 相同:25 篇按每计划 ≤8 篇分为 7 / 7 / 5 / 6 四份,四份串行以保护共享 NOTES 与构建产物。
- Part 4 是「不要重复造轮子」的一层:两个内置组件篇 + 一个 UI 系统篇 + 一个替换篇 + 一个性能篇。五篇共享同一套「组件挂在 UI 栈的哪个位置、事件归谁、缓存归谁」的模型,放在一个计划里才能前后一致。
- 本计划不动 Part 0–3 与 Part 5 的 20 篇;不新增/删除页面与 demo;不写 SUMMARY、不改 ROADMAP / STATE、不 commit。
</scope_justification>
<objective>
按 D-93 把 Part 4 的 5 篇从「有这些组件/开关」扩写到「知道什么时候用、用了会发生什么、为什么这样设计」:讲清内置文本/输入组件的具体用法、事件、受控边界与典型组合;讲清列表/滚动/分页/弹窗的选中、key、裁剪、命中与状态;讲清 UIController 的栈、背景、策略、实例生命周期、事件归属与两个控制器的分工;讲清替换内置 UI 的注册点、替换范围与风险;讲清 UI 性能的缓存、显示开关、列表/滚动、命中与纹理边界。
Purpose: 这 5 篇最容易被写成 props 表;读者照着表能填参数,却不知道组件已经替自己做了什么、什么时候不该用、替换后会破坏什么(D-93)。
Output: 5 篇扩写后的正文 + NOTES 中的基线、D-93 覆盖表、体量参考与门禁记录。**不新增/删除页面、不改 demo、不改其它 20 篇、不写 SUMMARY / ROADMAP / STATE、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-49-PLAN.md
@.planning/phases/10-docs-restructure/10-50-PLAN.md
@.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
@docs/.vitepress/config.ts
**流程约定:**
- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-50` 计划与 SUMMARY、不改 POC 文件、不改 `docs/` 其它页面与 demo、不改 `packages/` / `packages-user/` / `src/`。
- **Task 0 是硬关卡**:汇报扩写范围、D-93 四类口径、内置组件的边界要求、体量口径与停止条件,等用户明确回复「可以执行」。
- 修改方式为**派发子代理执行**;正文扩写一律派发子代理,改文件前先声明。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 代码注释;不 commit(D-90)。
- 写作口径按 D-59..D-74、D-77..D-88、D-91..D-93;示例注释按 D-65,代码块保留完整类上下文按 D-70,不写源码叙述按 D-80,不写使用概率元信息按 D-79。
- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。
**本批事实(执行时以这些为准):**
- 10-49 / 10-50 已完成 Part 0–3 的深度扩写并各自停在读者循环之前;本计划承接 Part 4,只回指已讲清的渲染树与事件基础。
- 内置组件的实际实现与导出位置以 `packages-user/client-base/src/components/*`、`packages-user/client-base/src/setting/*`、`packages/system/src/ui/*` 为准;文档只写对外用法,不写源码导读。
- UIController 的栈策略、背景四个名字(`showBack` / `showingBack()` / `showBackground` / `hideBackground`)、`keep`、`active`、`setPropsBaseCreator` 以 `packages/system/src/ui/{controller,types,instance,ui}.ts` 为准;`sceneController` / `mainUIController` 以 `packages-user/client-base/src/types.ts` 为准。
- 替换内置 UI 的注册点以 `src/client/ui/*` 与客户端入口为准;不要声称可以「覆盖任意内置 UI」而不核对注册方式。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报 Part 4 扩写范围、内置组件边界与停止条件,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CONTEXT.md(D-88、D-91、D-92、D-93)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-49 / 10-50 扩写小节与命名总表)、docs/advanced/ii/ui/ 下 5 篇现文、docs/.vitepress/config.ts</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——按 D-93 深度扩写 Part 4 的 5 篇(`builtin-text-and-input`、`builtin-list-and-containers`、`ui-controller-and-stack`、`replace-builtin-ui`、`ui-performance`)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不进入读者循环与用户审阅。
**为什么**——这 5 篇当前能告诉读者「有哪些 props」,但不能回答「组件替我决定了什么、什么时候不该用、替换内置 UI 会破坏什么、性能问题出在树的哪一层」。读者照表填参数能跑,遇到边界就回到试错。
**大致怎么做**——Task 1 先写基线与 D-93 覆盖表(5 篇 × 渲染树/事件/元素组件/示例解释);Task 2 扩写文本/输入与列表/容器 2 篇;Task 3 扩写 UI 栈与替换内置 UI 2 篇;Task 4 扩写性能篇;Task 5 跑门禁、D-93 抽查、体量记录并停止。
**影响范围**——只改上述 5 篇与 NOTES。不改其余 20 篇、两份导览、侧边栏、24 个 demo、`packages/` / `packages-user/` / `src/`、既有 JSDoc/注释、ROADMAP / STATE;不写 SUMMARY;不 commit。
**内置组件的边界要求(重点):**
- 每个内置组件都要说明「它替你决定了什么」:文本的换行/测量、输入的受控与事件、列表的选中与导航、滚动/分页的裁剪与回收、弹窗的层级与背景。
- 说明它在渲染树中的落点、事件如何进入、与 props/slots 的关系;不能只列 props。
- 说明典型组合与不适用场景;能手工拼的简单结构不要为了用组件而用组件。
**体量口径**——每篇长度由内容决定;~300 行只是参考,不是门禁;不注水、不因低于 300 行失败(D-88)。
**Round 1 边界**——116 条提问只作内部输入,不交给用户;扩写按 D-93 系统检查。
**请用户确认:**
1. 扩写范围是 Part 4 的 5 篇;不新增/删除页面与 demo,不改其它 20 篇与导览。
2. 每个内置组件都要讲「替你决定了什么 / 树落点 / 事件 / 组合与不适用」,不能只给 props 表。
3. UI 栈篇要讲清栈、背景四个名字、策略、实例生命周期与事件归属;替换篇要讲注册点与风险。
4. 四类 D-93 内容逐页判定;不适用写「不适用:理由」,不能留空或写「待补」。
5. 体量只记录不设门禁;不注水。
6. 停止条件:扩写与门禁结束即停止;不进入读者循环、不写 SUMMARY / ROADMAP / STATE、不 commit。
7. 本次修改方式为**派发子代理执行**;不改既有注释;不调用 `opencode` 命令。
**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报扩写范围、D-93 口径、内置组件边界、体量口径与停止条件。</what-built>
<how-to-verify>确认:①5 篇范围与不改批外内容;②每个内置组件讲「替你决定了什么 / 树落点 / 事件 / 组合与不适用」;③UI 栈与替换篇的重点;④四类 D-93 逐页判定、允许「不适用:理由」;⑤体量不设门禁;⑥结束即停、不写 SUMMARY / ROADMAP / STATE、不 commit。</how-to-verify>
<resume-signal>回复「可以执行」以继续;其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且扩写范围、内置组件边界、D-93 四类口径、体量口径、停止条件、派发方式六项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,且扩写范围、内置组件边界、D-93 口径、体量口径、停止条件、派发方式均已确认。</human-check>
</verify>
<done>用户回复「可以执行」且六项待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 扩写前基线 + D-93 覆盖表 + 体量参考(不改正文)</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>`10-50` 已写入 `停止点:10-50 扩写结束`;`10-CUSTOM-UI-NOTES.md` 含 `## 10-50 深度扩写(Part 2–3)`;用户已在 Task 0 回复「可以执行」。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-49 / 10-50 扩写小节、命名总表)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/ui/ 下 5 篇现文与其余 20 篇文件名</read_first>
<action>**本任务只建基线与覆盖表,绝对不改 `docs/` 正文、不改 ROADMAP / STATE。**
向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-51 深度扩写(Part 4)` 小节,依次写入:
1. `扩写范围:` + Part 4 的 5 篇完整路径;写「不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 20 篇与两份导览」。
2. `Round 1 内部输入:` + `10-49-READER-REVIEW.md(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单`。
3. `基线 HEAD(10-51 深度扩写):` + `git rev-parse HEAD` 完整 sha。
4. `扩写前本批页面聚合哈希:` + 对 5 篇取聚合 SHA-256(算法与 10-49 Task 1 相同:按 `docs/advanced/ii/ui/...` 相对路径排序,逐文件取 SHA-256,拼 `相对路径:hash` 后 LF 连接,再 SHA-256)。
5. `本批外文件聚合哈希:` + 对其余 20 篇 + 两份导览取同一算法聚合 SHA-256。
6. `ROADMAP 全文哈希:` 与 `STATE 全文哈希:` + 各自全文 SHA-256。
7. `### D-93 覆盖表` + 5 行表格,表头逐字 `| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |`;四类内容格先写 `待补`,确不适用写 `不适用:<理由>`;行数写当前值。
8. `体量参考(非门禁):` + 5 篇当前总行数与平均行数,写明「~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)」。
9. `停止点:10-51 只做 Part 4 深度扩写;不改 10-52..10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。`
**本任务不得修改任何 `docs/` 文件、不得改 ROADMAP / STATE、不得派发扩写子代理。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-51 深度扩写(Part 4)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '停止点:10-50 扩写结束'){ Write-Error 'NO-1050-STOP' }; $pages=@('docs/advanced/ii/ui/builtin-text-and-input.md','docs/advanced/ii/ui/builtin-list-and-containers.md','docs/advanced/ii/ui/ui-controller-and-stack.md','docs/advanced/ii/ui/replace-builtin-ui.md','docs/advanced/ii/ui/ui-performance.md'); foreach($k in @('## 10-51 深度扩写(Part 4)','扩写范围:','Round 1 内部输入:','基线 HEAD(10-51 深度扩写):','扩写前本批页面聚合哈希:','本批外文件聚合哈希:','ROADMAP 全文哈希:','STATE 全文哈希:','D-93 覆盖表','体量参考(非门禁):','停止点:10-51 只做')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-51 深度扩写):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('扩写前本批页面聚合哈希','本批外文件聚合哈希','ROADMAP 全文哈希','STATE 全文哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; $rows=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/' }); if($rows.Count -ne 5){ Write-Error ('MATRIX-ROWS:'+$rows.Count) }; foreach($p in $pages){ if(-not ($rows | Where-Object { $_.IndexOf($p) -ge 0 })){ Write-Error "NO-MATRIX-ROW $p" } }; foreach($r in $rows){ $c=@($r.Trim('|') -split '\|'); if($c.Count -lt 6){ Write-Error 'MATRIX-COLS' }; for($i=0;$i -lt 6;$i++){ if([string]::IsNullOrWhiteSpace($c[$i])){ Write-Error 'MATRIX-EMPTY' } } }; if($np -notmatch '116 条提问'){ Write-Error 'NO-ROUND1-COUNT' }; if($np -notmatch '178 行分节概率'){ Write-Error 'NO-PROB-COUNT' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-1050-STOP", "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NO-MATRIX-SECTION", "MATRIX-ROWS", "NO-MATRIX-ROW", "MATRIX-COLS", "MATRIX-EMPTY", "NO-ROUND1-COUNT", "NO-PROB-COUNT", "MD-COUNT", "DEMO-COUNT"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 有 `## 10-51 深度扩写(Part 4)` 与九项固定行;覆盖表 5 篇完整路径、六列、四类内容格非空、行数为数字;Round 1 计数已记录且明确仅内部;四个哈希为 64 位小写 hex;25 篇 / 24 demo 不变;未改任何 `docs/` 正文、未改 ROADMAP / STATE。</acceptance_criteria>
<done>Part 4 扩写基线与覆盖表已落盘,正文未动。</done>
</task>
<task type="auto">
<name>Task 2: 扩写文本/输入与列表/容器 2 篇(内置组件替你决定了什么)</name>
<files>docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1 已写入 `## 10-51 深度扩写(Part 4)` 与覆盖表;5 篇现文未被本计划改动。</precondition>
<read_first>docs/advanced/ii/ui/{builtin-text-and-input,builtin-list-and-containers}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 2 篇的提问)、packages-user/client-base/src/components/*(文本、说明框、输入框、列表、分页、滚动、弹窗的实际导出与 props)、packages-user/client-base/src/elements/props.ts(元素 props 基线)、docs/advanced/ii/ui/{text,events,conditional-and-list-rendering}.md(已扩写的基础篇,只回指不重抄)</read_first>
<action>**只改这 2 篇与 NOTES;不碰其它篇目与 demo。**
**(1)`builtin-text-and-input.md`**
- 新增 `## 这些组件替你决定了什么`:换行文本、说明框、输入框分别封装了哪些行为(测量/换行/内边距/滚动/焦点/输入事件),以及哪些行为仍要自己处理;不要只列 props。
- 新增 `## 文本组件的用法与组合`:多行说明、标题 + 正文、可滚动的长说明;每类给完整用法与树落点,说明为什么用组件而不是多个 `text`。
- 新增 `## 输入组件的受控边界`:值从哪里来、`v-model` 写回什么、输入事件何时触发、失焦/回车如何处理;受控与非受控的取舍;输入框在 UI 栈中的焦点归属。
- 新增 `## 事件与渲染树`:组件的根元素在树里的位置;`onClick` 等属性落在根还是内部元素;需要拿内部元素时组件暴露了什么;不要把组件当成黑盒猜事件。
- 新增 `## 不适用场景`:单行短标签、纯展示文本、极简输入不要为了统一而套组件;给出手写 `text` 的边界。
**(2)`builtin-list-and-containers.md`**
- 新增 `## 列表、滚动、分页、弹窗各自解决什么`:四类组件的职责边界;选中、导航、裁剪、回收、层级、背景分别归谁;用一张对照表说明「什么时候用哪个」。
- 新增 `## 列表的选中与 v-model`:初始选中、挂载后改绑定会不会重新选中、用户操作后绑定如何写回;列表项渲染与 key;与条件/列表篇的 key 规则一致。
- 新增 `## 滚动与裁剪`:滚动容器如何裁剪超出内容、命中是否按裁剪区域、滚动位置在隐藏/卸载时是否保留;`Scroll` 与 `ListPage` 的差异与选择。
- 新增 `## 弹窗与一次性提示`:弹窗的层级、背景、关闭方式;与 UIController 的栈/背景如何配合;什么时候用内置弹窗、什么时候用普通面板。
- 新增 `## 组合示例与树形解释`:一个「分页列表 + 详情 + 弹窗确认」的完整例子;代码后解释每层在渲染树中的位置、事件路径、状态归属。
**写法硬要求:**
- 每个组件都回答「它替你决定了什么、树落点、事件怎么进、典型组合、什么时候不用」(D-93 第 3 条);每次代码后解释模型位置与理由(第 4 条)。
- 代码块保留完整上下文(D-70),注释充足(D-65);不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表这 2 行为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $p1='docs/advanced/ii/ui/builtin-text-and-input.md'; $p2='docs/advanced/ii/ui/builtin-list-and-containers.md'; foreach($p in @($p1,$p2)){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $a=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p1)); foreach($k in @('换行','输入','v-model','事件','渲染树','不适用')){ if($a.IndexOf($k) -lt 0){ Write-Error "TEXTINPUT-MISSING $k" } }; $b=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p2)); foreach($k in @('列表','滚动','分页','弹窗','key','裁剪','渲染树')){ if($b.IndexOf($k) -lt 0){ Write-Error "LIST-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-51 深度扩写(Part 4)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in @($p1,$p2)){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in @($p1,$p2)){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check $p1 $p2" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "TEXTINPUT-MISSING", "LIST-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>文本/输入篇讲清组件替你决定了什么、文本组合、输入受控边界、焦点与事件落点、不适用场景;列表/容器篇讲清四类组件职责、选中与 `v-model`、key、滚动裁剪与命中、弹窗与栈/背景、完整组合示例的树解释。每次代码后有模型解释;NOTES 覆盖表 2 行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>文本/输入与列表/容器 2 篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 3: 扩写 UI 栈与替换内置 UI 2 篇(归属、背景与风险)</name>
<files>docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/replace-builtin-ui.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2 已写入 2 条 `已完成扩写:`;覆盖表这 2 行无 `待补`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>docs/advanced/ii/ui/{ui-controller-and-stack,replace-builtin-ui}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 2 篇的提问)、packages/system/src/ui/{controller,types,instance,ui}.ts(栈策略、背景四个名字、keep、active、setPropsBaseCreator、open/close/hide/show)、packages-user/client-base/src/types.ts(sceneController / mainUIController)、src/client/ui/*(内置 UI 与替换入口)、docs/advanced/ii/ui/{events,hotkey-in-ui}.md(已扩写的事件/按键归属,只回指)</read_first>
<action>**只改这 2 篇与 NOTES;不碰其它篇目与 demo。**
**(1)`ui-controller-and-stack.md`**
- 新增 `## 控制器、实例与栈`:`UIController` 管一条栈;每次 `open` 产生一个 `UIInstance`(key / ui / vBind / hidden / alwaysShow);`close` 凭实例关闭;`hide` / `show` 只切实例可见性,不出栈;`closeAll` 的范围。
- 新增 `## 背景的四个名字`:`showBack` 是用户设置与系统结果的合成;`showingBack()` 读最终是否显示;`showBackground()` / `hideBackground()` 改用户设置;`setBackground` 换背景 UI;`keep()` 的作用与生命周期;用一个状态表说明「现在背景是否可见该读哪个」。
- 新增 `## 栈策略`:默认 `last-only` 与 `showAll` 的差异;`alwaysShow` 的实例如何参与;策略切换后栈内实例的显示状态如何重算;不要假设「打开新面板一定盖住旧面板」而不看策略。
- 新增 `## 两个控制器`:`sceneController` 与 `mainUIController` 的分工(场景 UI vs 主界面常驻 UI);同一个 UI 在两个控制器下会得到两个独立实例;从主菜单/场景/面板内打开时该选哪个;给一个决策表。
- 新增 `## 事件归属与生命周期`:栈顶/可见实例谁收到元素事件与按键;背景 UI 是否参与;关闭后实例销毁、纹理/监听释放;`props.state` 的注入链(`setPropsBaseCreator`)与自定义 creator 要包含什么。
- 新增 `## 打开与关闭的完整例子`:一个「主界面工具栏 → 打开设置 → 设置里再开确认框 → 逐层关闭」的例子;代码后解释每层实例在栈中的位置、背景变化与事件归属。
**(2)`replace-builtin-ui.md`**
- 新增 `## 替换的是入口,不是实现`:内置 UI 通过 `GameUI` 对象在客户端入口/场景/主界面被打开;替换的做法是提供自己的 UI 并在对应注册/打开点替换,不是改 `packages/` 里的内置实现;先核对 `src/client/ui/*` 的实际注册方式再写。
- 新增 `## 可以替换哪些、分别影响什么`:设置、存档、工具栏、状态栏等;逐个说明替换后哪些行为要自己保留(存档兼容、按键、背景、返回路径),哪些可以省略。
- 新增 `## 替换步骤`:从新建 `src/client/ui/<name>.tsx`、导出 `GameUI`、在入口注册/替换、打开验证到回退;每一步给出验证点。
- 新增 `## 风险与边界`:覆盖后丢设置/存档/工具栏事件的典型原因;不要替换自己没有把握的内置 UI;替换不等于修改引擎;与插件/主题的关系。
- 新增 `## 一个最小替换示例`:替换一个简单内置 UI(按实际最简单的入口选),代码后解释它接在哪条栈、背景与关闭路径怎么走。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表这 2 行为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $p1='docs/advanced/ii/ui/ui-controller-and-stack.md'; $p2='docs/advanced/ii/ui/replace-builtin-ui.md'; foreach($p in @($p1,$p2)){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $a=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p1)); foreach($k in @('栈','实例','showBack','showingBack','showBackground','hideBackground','keep','sceneController','mainUIController','事件')){ if($a.IndexOf($k) -lt 0){ Write-Error "STACK-MISSING $k" } }; $b=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p2)); foreach($k in @('GameUI','注册','替换','存档','背景','风险')){ if($b.IndexOf($k) -lt 0){ Write-Error "REPLACE-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-51 深度扩写(Part 4)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in @($p1,$p2)){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in @($p1,$p2)){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check $p1 $p2" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "STACK-MISSING", "REPLACE-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>UI 栈篇讲清控制器/实例/栈、背景四个名字与状态表、栈策略、两个控制器分工、事件归属与生命周期、props 注入链、完整开关例子;替换篇讲清「替换入口不是改实现」、可替换范围与影响、步骤与验证点、风险边界、最小替换示例。每次代码后有模型解释;NOTES 覆盖表 2 行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>UI 栈与替换内置 UI 2 篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 4: 扩写性能篇(缓存、显示开关、列表与命中的边界)</name>
<files>docs/advanced/ii/ui/ui-performance.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 已写入 2 条 `已完成扩写:`;覆盖表这 2 行无 `待补`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>docs/advanced/ii/ui/ui-performance.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅该篇提问)、docs/advanced/ii/ui/{layer-transform-performance,builtin-list-and-containers,ui-controller-and-stack}.md(已扩写的缓存/列表/栈,只回指)、packages/render/src/core/{item,container,render}.ts(缓存、脏标记、命中遍历)</read_first>
<action>**只改 `ui-performance.md` 与 NOTES;不碰其它篇目与 demo。**
扩写要点:
- 新增 `## 性能问题先定位在哪一层`:绘制、命中遍历、组件重渲染、列表/滚动、纹理、UI 栈六层;每层给一个典型症状与判断方法;不要把「卡」一律归因成缓存。
- 新增 `## 缓存:什么时候有用、什么时候有害`:静态复杂子树适合缓存;频繁变化的文本/图标/列表项不适合;父级缓存与子级脏更新的关系;`nocache` 优先级;给一个「给会变的容器开缓存」的错误示范与修正。
- 新增 `## 显示开关:hidden 还是卸载`:频繁开关优先 `hidden`;只在必须释放/重置时卸载;列表项大量且长期不用才考虑卸载;与 10-49 层级篇、10-50 条件篇口径一致。
- 新增 `## 列表与滚动`:可视区外是否还绘制/命中;分页与滚动的选择;key 与节点复用对性能的影响;不要用「全部渲染 + 裁剪」解决超大列表而不看组件能力。
- 新增 `## 命中与事件`:`noevent` 减少命中、`actionStroke` 缩小命中区域、重叠元素多时命中遍历的成本;不要用大量透明全屏遮罩接收事件。
- 新增 `## 纹理与文字`:大图/多图的内存、像素图缩放、文字测量与重排;纹理释放时机(组件卸载)。
- 新增 `## 观测与验证`:如何用浏览器性能面板/帧率观察;给一个「先量再改」的检查清单;不写没有依据的具体毫秒数。
- 保留现有表格并补「症状 → 先查哪一层 → 常见修正」三列表。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88);不编造没有测过的数字。
- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。
- 完成后更新 NOTES 覆盖表该行为 `已讲`(或 `不适用:理由`),追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $p='docs/advanced/ii/ui/ui-performance.md'; if(-not(Test-Path -LiteralPath $p)){ Write-Error 'MISSING-PAGE' }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); foreach($k in @('缓存','hidden','列表','命中','纹理','观测','渲染树')){ if($t.IndexOf($k) -lt 0){ Write-Error "PERF-MISSING $k" } }; if($t -match '简化版|以后再做|v1'){ Write-Error 'SCOPE-REDUCTION' }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-51 深度扩写(Part 4)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '(?m)^已完成扩写:docs/advanced/ii/ui/ui-performance\.md\s*$'){ Write-Error 'NO-DONE-MARK' }; if($np -notmatch '(?m)^自查:docs/advanced/ii/ui/ui-performance\.md'){ Write-Error 'NO-SELF-CHECK' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/ui-performance\.md' }); if($row.Count -ne 1){ Write-Error 'NO-MATRIX-ROW' }; if($row[0] -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check $p" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING-PAGE", "PERF-MISSING", "SCOPE-REDUCTION", "NO-DONE-MARK", "NO-SELF-CHECK", "NO-MATRIX-ROW", "MATRIX-STILL-PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>性能篇补齐六层定位、缓存取舍与错误示范、`hidden` vs 卸载、列表/滚动、命中与事件、纹理与文字、观测清单;保留并扩展现有表格;不编造毫秒数;每次代码后有模型解释;NOTES 覆盖表该行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>性能篇已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 5: 门禁 + D-93 抽查 + 体量记录 + 停止</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2–4 已把 5 篇的四类内容格改为 `已讲`(或 `不适用:理由`),并各写入 `自查:` 与 `已完成扩写:`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-51 深度扩写(Part 4)` 全部内容)、docs/advanced/ii/ui/ 下 5 篇、.planning/ROADMAP.md、.planning/STATE.md</read_first>
<action>**只校验、记录与停止;除 NOTES 外不改任何文件。**
1. **D-93 抽查**:逐篇核对四类内容;每篇写 `D-93 抽查:<path> — 通过` 或 `— 发现缺口(缺口一句)`;有缺口先修到通过。
2. **结构门禁**:25 篇 / 24 demo 不变;5 篇 CRLF;无 `待补` 覆盖格;每篇有 `自查:` 与 `已完成扩写:`;无「模板 / 需改 / 简化版 / v1 / 以后再做」。
3. **聚合哈希门禁**:重算 `本批外文件聚合哈希`、`ROADMAP 全文哈希`、`STATE 全文哈希`,与 Task 1 一致;重算 `扩写后本批页面聚合哈希`,必须与扩写前不同。
4. **prettier**:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后 `--check`。
5. **ESLint**:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,exit 0、输出不含 `error` / `warning`。
6. **docs 类型**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,`docs/` 路径 0 条 `error TS`;既有引擎报错只记录条数。
7. **构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,exit 0、含 `build complete`、无 `dead link`;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。
8. **写 NOTES**:追加 `扩写后本批页面聚合哈希`、`体量参考(扩写后)`(逐篇行数 + 总行数,再次写明不设 300 行门禁)、`### 10-51 门禁`(命令、结果、`docs/` 路径 0 类型错误、既有引擎报错条数、构建耗时、25 HTML、D-93 逐篇结论)、`停止点:10-51 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-52..10-54;未 commit。`
9. **立即停止**:不创建 SUMMARY、不改 ROADMAP / STATE、不 commit、不派发读者。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-51 深度扩写(Part 4)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; $pages=@('docs/advanced/ii/ui/builtin-text-and-input.md','docs/advanced/ii/ui/builtin-list-and-containers.md','docs/advanced/ii/ui/ui-controller-and-stack.md','docs/advanced/ii/ui/replace-builtin-ui.md','docs/advanced/ii/ui/ui-performance.md'); foreach($k in @('扩写后本批页面聚合哈希:','体量参考(扩写后):','### 10-51 门禁','D-93 抽查:','停止点:10-51 扩写结束')){ if($sec.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($sec -notmatch '(?m)^扩写后本批页面聚合哈希:[0-9a-f]{64}'){ Write-Error 'NO-POST-HASH' }; $mpre=[regex]::Match($sec,'(?m)^扩写前本批页面聚合哈希:([0-9a-f]{64})'); $mpost=[regex]::Match($sec,'(?m)^扩写后本批页面聚合哈希:([0-9a-f]{64})'); if(-not $mpre.Success -or -not $mpost.Success){ Write-Error 'NO-BATCH-HASH' }; if($mpre.Groups[1].Value -eq $mpost.Groups[1].Value){ Write-Error 'BATCH-UNCHANGED' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; if($m.Groups[1].Value -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; foreach($p in $pages){ if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" }; if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" } }; $d93bad=@(); foreach($p in $pages){ $d93lines=@($sec -split "`r?`n" | Where-Object { $_ -match ('^D-93 抽查:'+[regex]::Escape($p)) }); if($d93lines.Count -eq 0){ $d93bad += ($p+':NO-LINE') } elseif($d93lines[-1] -match '发现缺口'){ $d93bad += $p } }; if($d93bad.Count -gt 0){ Write-Error ('D93-GAP '+($d93bad -join ',')) }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($p in $pages){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match "(?<!\r)\n"){ Write-Error "LF-ONLY $p" }; if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $sorted=@($pages | Sort-Object); $joined=($sorted | ForEach-Object { $_ + ':' + ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $_)))).Replace('-','').ToLower()) }) -join "`n"; $h=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($joined))).Replace('-','').ToLower(); if($sec -notmatch ('(?m)^扩写后本批页面聚合哈希:'+$h)){ Write-Error 'POST-HASH-MISMATCH' }; $roadText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md')); $roadHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($roadText))).Replace('-','').ToLower(); $mr=[regex]::Match($np,'(?m)^ROADMAP 全文哈希:([0-9a-f]{64})'); if(-not $mr.Success -or $mr.Groups[1].Value -ne $roadHash){ Write-Error 'ROADMAP-MODIFIED' }; $stText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); $stHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($stText))).Replace('-','').ToLower(); $ms=[regex]::Match($np,'(?m)^STATE 全文哈希:([0-9a-f]{64})'); if(-not $ms.Success -or $ms.Groups[1].Value -ne $stHash){ Write-Error 'STATE-MODIFIED' }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr=@($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $built=@(Get-ChildItem -LiteralPath 'public/_docs/advanced/ii/ui' -Filter *.html -File -ErrorAction SilentlyContinue); if($built.Count -ne 25){ Write-Error ('PAGE-NOT-BUILT:'+$built.Count) }; foreach($s in @('10-51-SUMMARY.md','10-53-SUMMARY.md','10-54-SUMMARY.md')){ if(Test-Path -LiteralPath ('.planning/phases/10-docs-restructure/'Line truncated
<fails_when>non-zero exit, or output contains "NOTES-MISSING", "NO-POST-HASH", "NO-BATCH-HASH", "BATCH-UNCHANGED", "NO-MATRIX-SECTION", "MATRIX-STILL-PENDING", "NO-SELF-CHECK", "NO-DONE", "D93-GAP", "MD-COUNT", "DEMO-COUNT", "LF-ONLY", "SCOPE-REDUCTION", "POST-HASH-MISMATCH", "ROADMAP-MODIFIED", "STATE-MODIFIED", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "UNEXPECTED-SUMMARY"; or output lacks "T5-OK"</fails_when>
</verify>
<acceptance_criteria>5 篇覆盖格无 `待补`、逐篇 `自查:` / `已完成扩写:`、`D-93 抽查` 无缺口;`扩写后本批页面聚合哈希` 与扩写前不同且与重算一致;批外/ROADMAP/STATE 哈希未变;25 篇 / 24 demo 不变;5 篇 CRLF、无降级表述;prettier / ESLint 0/0 / `docs/` 路径 0 类型错误 / 构建 green + 0 dead link / 25 个 HTML;NOTES 有体量参考、`### 10-51 门禁`、停止点;未创建 SUMMARY。</acceptance_criteria>
<done>Part 4 扩写完成并通过门禁,停在读者循环之前。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 写作者 → 正文 | 内置组件必须讲行为边界与设计原因,不能只给 props 表 |
| 替换文档 → 实际注册点 | 替换内置 UI 必须核对真实入口,不能声称任意覆盖 |
| 本计划 → 批外文档 | 只允许改 5 篇;其余 20 篇、导览、demo、侧边栏不得改动 |
| 本计划 → 账本 | 不写 SUMMARY、不改 ROADMAP / STATE、不 commit |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-180 | Tampering | 内置组件写成 props 表 | high | mitigate | 每篇必须回答「替你决定了什么/树落点/事件/组合/不适用」;Task 5 抽查 |
| T-10-181 | Tampering | 替换内置 UI 写错注册点 | high | mitigate | Task 3 先核对 `src/client/ui/*` 与入口;不确认的入口不写;构建 + 静态检查 |
| T-10-182 | Tampering | 批外文档被改动 | high | mitigate | Task 1 记录 `本批外文件聚合哈希`;Task 5 重算比对 |
| T-10-183 | Repudiation | 扩写退化为只补读者问题 | high | mitigate | D-93 四类覆盖表逐页判定;覆盖格必须 `已讲` 或 `不适用:理由` |
| T-10-184 | Tampering | 为凑 300 行注水 / 编造性能数字 | medium | mitigate | 体量只记录不设门禁;禁止无依据的毫秒数;禁止接口表堆砌 |
| T-10-185 | Information Disclosure | 把 Round 1 读者记录交给用户 | medium | mitigate | Round 1 仅内部输入;本计划不产出用户可读审阅摘要 |
| T-10-186 | Repudiation | 越界写 SUMMARY / ROADMAP / STATE | medium | mitigate | Task 5 校验 ROADMAP / STATE 全文哈希;禁止创建 SUMMARY |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 关卡门禁:Task 0 已获「可以执行」;10-50 已写入停止点。
- 基线门禁:Task 1 写入 5 篇范围、Round 1 计数、基线 HEAD、两个聚合哈希、两个账本哈希、D-93 覆盖表、体量参考。
- 覆盖门禁:5 篇四类内容格为 `已讲` 或 `不适用:理由`,无 `待补`;每篇有 `自查:` 与 `已完成扩写:`;`D-93 抽查` 无缺口。
- 内置组件门禁:每篇回答「替你决定了什么 / 树落点 / 事件 / 组合 / 不适用」;UI 栈篇背景四个名字与策略齐全;替换篇注册点与风险齐全。
- 范围门禁:25 篇 / 24 demo;`本批外文件聚合哈希` 与基线一致;未改导览、侧边栏、`packages*` / `src`。
- 质量门禁:5 篇 CRLF;prettier `--check`;ESLint 0/0;`docs/` 路径 0 类型错误;构建 green + 0 dead link;25 个 HTML。
- 体量门禁:只记录行数;不设 300 行下限/上限;不因低于 300 行失败。
- 停止门禁:NOTES 有 `停止点:10-51 扩写结束`;未创建 SUMMARY;ROADMAP / STATE 哈希未变;未 commit。
</verification>
<success_criteria>
- Part 4 的 5 篇按 D-93 讲清内置组件的职责边界、树落点、事件、组合与不适用,以及 UI 栈/背景/替换/性能的模型与风险。
- 读者能独立判断「该用哪个组件、替换后要保留什么、性能问题先查哪一层」,并能改写示例。
- 没有新增/删除页面与 demo,没有改动批外文档与源码,没有编造性能数字。
- 门禁全绿,体量只作参考记录,本计划停在读者循环之前。
</success_criteria>
<output>
本计划**不写 SUMMARY**。完成后在对话中报告 5 篇扩写清单、逐篇行数(体量参考)、D-93 抽查结论与门禁结果,然后停止。读者循环由 `10-53-PLAN.md` 执行,用户审阅由 `10-54-PLAN.md` 执行。
</output>
@@ -0,0 +1,357 @@
---
phase: 10-docs-restructure
plan: 52
type: execute
wave: 10
depends_on:
- 10-51
files_modified:
- docs/advanced/ii/ui/inventory-example-1-skeleton.md
- docs/advanced/ii/ui/inventory-example-2-grid.md
- docs/advanced/ii/ui/inventory-example-3-detail.md
- docs/advanced/ii/ui/inventory-example-4-scroll.md
- docs/advanced/ii/ui/inventory-example-5-state.md
- docs/advanced/ii/ui/inventory-example-6-animation-and-register.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 70000
raw_tokens: 42000
tasks: 6
confidence: low
must_haves:
truths:
- "Part 5 的 6 篇按 D-93 讲清每一步在渲染树/事件/组件模型中的位置与理由,不能只给可复制代码(D-93 第 4 条)"
- "6 篇共享一份系列一致性契约:`items` 的响应式形态、`Item` 来源、`selectedId` 的空值语义、关闭归属、最终左侧方案、布局坐标、组件拆分与 props 链必须逐页一致(D-93 / Round 1 跨篇问题)"
- "扩写不新增、不删除页面,仍为 25 篇正文与 24 个 demo;不改 demo、不改侧边栏、不改其它 19 篇"
- "每篇长度由内容决定:~300 行只是体量参考,不设下限/上限,不因低于 300 行失败;不注水(D-88)"
- "Round 1 的 116 条提问只作内部输入,不交给用户;跨篇问题必须收口成契约,不能只在单页打补丁(D-91 / D-93 第 5 条)"
- "本计划只改 Part 5 的 6 篇与 NOTES;不写 SUMMARY、不改 ROADMAP / STATE、不 commit、不进入读者循环"
artifacts:
- "docs/advanced/ii/ui/inventory-example-{1-skeleton,2-grid,3-detail}.md(目标、骨架、网格、详情:树结构与状态归属)"
- "docs/advanced/ii/ui/inventory-example-{4-scroll,5-state,6-animation-and-register}.md(滚动、交互状态、动画与注册:最终组装与一致性)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 `## 10-52 深度扩写(Part 5)`:基线、D-93 覆盖表、系列一致性契约、体量参考、门禁、停止点)"
key_links:
- "先定系列一致性契约再改单页:6 篇是同一个背包的连续教程,单页各自正确但跨页矛盾会让读者拼不出最终代码(Round 1 跨篇问题)"
- "每一步都要说明「这次新增的节点挂在哪、事件从哪来、状态归谁」,否则读者只会按顺序抄,无法自己改(D-93 第 1–3 条)"
- "最终组装必须只有一个答案:左侧用 `Scroll`、`selectedId` 可为 `null`、关闭归 `InventoryPanel`、布局坐标不重叠;不能在不同页给不同方案"
- "示例后解释先于下一段代码:读者要能复述「为什么现在加这个组件」,而不是等最后才明白(D-93 第 4 条)"
---
<scope_justification>
本计划承担 25 篇中的 Part 5(6 篇)。切分理由与 10-49 相同:25 篇按每计划 ≤8 篇分为 7 / 7 / 5 / 6 四份,四份串行以保护共享 NOTES 与构建产物。
- Part 5 是同一个背包示例的六个连续步骤,必须放在一个计划里统一契约:`items` 的形态、`selectedId` 的空值、关闭归属、左侧方案、布局坐标、组件拆分与 props 链。拆到多个计划会再次产生跨页矛盾。
- 本计划不动 Part 0–4 的 19 篇;不新增/删除页面与 demo;不写 SUMMARY、不改 ROADMAP / STATE、不 commit。
</scope_justification>
<objective>
按 D-93 把 Part 5 的 6 篇从「按顺序抄代码」扩写成「知道每一步为什么这样做」:先定系列一致性契约,再逐篇讲清目标、骨架、网格、详情、滚动、状态、动画与注册;每一步都说明新增节点挂在渲染树哪里、事件从哪条路径进入、状态归谁、props 怎么流,以及为什么现在做这一步。
Purpose: 这 6 篇是读者第一次把零件装成完整 UI;当前单页能跑,但跨页存在 `items` 形态、`selectedId` 空值、关闭归属、左侧方案与布局坐标不一致,读者拼不出最终代码(Round 1 跨篇问题)。
Output: 6 篇扩写后的正文 + NOTES 中的基线、D-93 覆盖表、系列一致性契约、体量参考与门禁记录。**不新增/删除页面、不改 demo、不改其它 19 篇、不写 SUMMARY / ROADMAP / STATE、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-49-PLAN.md
@.planning/phases/10-docs-restructure/10-50-PLAN.md
@.planning/phases/10-docs-restructure/10-51-PLAN.md
@.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
@docs/.vitepress/config.ts
**流程约定:**
- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-51` 计划与 SUMMARY、不改 POC 文件、不改 `docs/` 其它页面与 demo、不改 `packages/` / `packages-user/` / `src/`。
- **Task 0 是硬关卡**:汇报扩写范围、系列一致性契约、D-93 四类口径、体量口径与停止条件,等用户明确回复「可以执行」。
- 修改方式为**派发子代理执行**;正文扩写一律派发子代理,改文件前先声明。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 代码注释;不 commit(D-90)。
- 写作口径按 D-59..D-74、D-77..D-88、D-91..D-93;示例注释按 D-65,代码块保留完整类/组件上下文按 D-70,不写源码叙述按 D-80,不写使用概率元信息按 D-79。
- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。
**本批事实(执行时以这些为准):**
- 10-49..10-51 已完成 Part 0–4 的深度扩写并各自停在读者循环之前;本计划承接 Part 5,只回指已讲清的渲染树、事件、组件、内置组件与 UI 栈。
- Round 1 的跨篇问题(`items` 形态、`selectedId` 空值、关闭归属、左侧方案、布局坐标、组件拆分与 props 链)是本计划必须收口的契约;契约写入 NOTES 后,6 篇按契约统一,不再各写一套。
- 6 篇现有代码是写作期示例,不是 live demo 的逐行镜像;本计划不改 24 个 demo,只改正文示例与解释。live 仍按正文说明「等价元素」口径处理。
- 最终背包的左侧方案、坐标、关闭归属由本计划 Task 1 的契约一次性确定;后续任务不得另起方案。</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报 Part 5 扩写范围、系列一致性契约与停止条件,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CONTEXT.md(D-88、D-91、D-92、D-93)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(跨篇问题 1–34,只读作内部输入)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-49..10-51 扩写小节与命名总表)、docs/advanced/ii/ui/ 下 6 篇现文、docs/.vitepress/components/demos/ui/inventory-*.tsx(只读现状,不改)</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——按 D-93 深度扩写 Part 5 的 6 篇背包示例(`inventory-example-1-skeleton` 到 `inventory-example-6-animation-and-register`)。先定系列一致性契约,再逐篇讲清每一步的树位置、事件路径、状态归属与理由;不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不进入读者循环与用户审阅。
**为什么**——这 6 篇是同一个背包的连续教程,当前单页能跑但跨页有矛盾:`items` 有的是普通数组、有的是 `ref`;`selectedId` 有的初始化成有效 id、有的依赖 `undefined`;关闭有的归控制器、有的只改提示;左侧有的普通网格、有的 `Scroll`、有的 `ListPage`;布局坐标还可能重叠。读者按顺序读到最后拼不出一个自洽的实现。只补单页问题会继续制造矛盾,所以先定契约再改。
**大致怎么做**——Task 1 写基线、D-93 覆盖表与「系列一致性契约」(`items` 形态、`Item` 来源、`selectedId` 空值、关闭归属、左侧方案、布局坐标、组件拆分、props 链、key、事件流);Task 2 扩写示例一至三;Task 3 扩写示例四至六;Task 4 做跨页一致性核对(按契约逐条比对 6 篇)并修不一致;Task 5 跑门禁、D-93 抽查、体量记录并停止。
**影响范围**——只改上述 6 篇与 NOTES。不改其余 19 篇、两份导览、侧边栏、24 个 demo、`packages/` / `packages-user/` / `src/`、既有 JSDoc/注释、ROADMAP / STATE;不写 SUMMARY;不 commit。
**系列一致性契约(将写入 NOTES,后续任务不得另起方案):**
1. `items` 在 `InventoryPanel` 里是 `ref<Item[]>`;子组件收到的是 `items`(父级解包后的数组)或明确的 props,不在子组件里直接引用父级闭包变量;派生列表用 `computed`。
2. `Item` 类型只定义一次,放在示例说明的共享类型位置;后续页面引用它,不各自重写。
3. `selectedId` 是 `ref<string | null>`;初始为 `null`(显示「请选择道具」);点击有效项写 id;提供「取消选择」或明确说明如何回到未选中。
4. 关闭归 `InventoryPanel`:面板的关闭按钮调用 `props.controller.close(props.instance)`;子组件不直接关闭面板,需要关闭时通过回调上报。
5. 左侧最终方案是 `Scroll`(示例四引入);示例二/三的普通网格是阶段性实现,示例四明确替换关系,示例五/六不再回到普通网格或 `ListPage`。
6. 布局坐标(layout)以最终组装页为准:左侧网格/滚动区与底部 `ActionBar` 不重叠;各页坐标若调整,必须在当页说明与最终页的关系。
7. 组件拆分为 `InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar`;每层的 props 链在契约里列清,后续页面不新增未声明的隐式依赖。
8. 列表 key 用 `item.id`;不用下标代替会变化的身份;无状态静态列表的例外要写明。
9. 事件流:`ItemCell` 点击 → 上报 `onSelect(id)` → `ItemGrid` → `InventoryPanel` 更新 `selectedId`;操作按钮 → 上报动作 → 面板决定装备/使用/关闭。
**体量口径**——每篇长度由内容决定;~300 行只是参考,不是门禁;不注水、不因低于 300 行失败(D-88)。
**Round 1 边界**——116 条提问只作内部输入,不交给用户;跨篇问题收口成上述契约,不能只在单页打补丁。
**请用户确认:**
1. 扩写范围是 Part 5 的 6 篇;不新增/删除页面与 demo,不改其它 19 篇与导览。
2. 先定系列一致性契约,再逐篇扩写;契约九条如上(如某条要改,请在回复中直接给出)。
3. 每篇讲清「新增节点挂在哪、事件从哪来、状态归谁、为什么现在做」,不能只给可复制代码。
4. 四类 D-93 内容逐页判定;不适用写「不适用:理由」,不能留空或写「待补」。
5. 体量只记录不设门禁;不注水。
6. 停止条件:扩写与门禁结束即停止;不进入读者循环、不写 SUMMARY / ROADMAP / STATE、不 commit。
7. 本次修改方式为**派发子代理执行**;不改既有注释;不调用 `opencode` 命令。
**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报扩写范围、系列一致性契约、D-93 口径、体量口径与停止条件。</what-built>
<how-to-verify>确认:①6 篇范围与不改批外内容;②系列一致性契约九条(`items`/`Item`/`selectedId`/关闭/左侧/坐标/拆分/key/事件流);③每篇讲树位置、事件、状态与理由;④四类 D-93 逐页判定;⑤体量不设门禁;⑥结束即停、不写 SUMMARY / ROADMAP / STATE、不 commit。</how-to-verify>
<resume-signal>回复「可以执行」以继续;其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且扩写范围、系列一致性契约、D-93 四类口径、体量口径、停止条件、派发方式六项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,且扩写范围、系列一致性契约、D-93 口径、体量口径、停止条件、派发方式均已确认。</human-check>
</verify>
<done>用户回复「可以执行」且六项待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 扩写前基线 + D-93 覆盖表 + 系列一致性契约 + 体量参考(不改正文)</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>`10-51` 已写入 `停止点:10-51 扩写结束`;`10-CUSTOM-UI-NOTES.md` 含 `## 10-51 深度扩写(Part 4)`;用户已在 Task 0 回复「可以执行」。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-49..10-51 扩写小节、命名总表)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(跨篇问题与 inventory 各页提问,只读)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/ui/inventory-example-*.md(6 篇现文)、docs/.vitepress/components/demos/ui/inventory-*.tsx(只读现状)</read_first>
<action>**本任务只建基线、覆盖表与系列一致性契约,绝对不改 `docs/` 正文、不改 ROADMAP / STATE、不改 demo。**
向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-52 深度扩写(Part 5)` 小节,依次写入:
1. `扩写范围:` + Part 5 的 6 篇完整路径;写「不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 19 篇、两份导览与 24 个 demo」。
2. `Round 1 内部输入:` + `10-49-READER-REVIEW.md(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单`。
3. `基线 HEAD(10-52 深度扩写):` + `git rev-parse HEAD` 完整 sha。
4. `扩写前本批页面聚合哈希:` + 对 6 篇取聚合 SHA-256(算法与 10-49 Task 1 相同:按 `docs/advanced/ii/ui/...` 相对路径排序,逐文件取 SHA-256,拼 `相对路径:hash` 后 LF 连接,再 SHA-256)。
5. `本批外文件聚合哈希:` + 对其余 19 篇 + 两份导览取同一算法聚合 SHA-256(demo 不参与正文哈希,另记 `demo 快照哈希:` 以证明未改:24 个 `.tsx` 按 `docs/.vitepress/components/demos/ui/...` 相对路径排序,逐文件取 SHA-256,拼 `相对路径:hash` 后 LF 连接,再 SHA-256)。
6. `ROADMAP 全文哈希:`、`STATE 全文哈希:`、`demo 快照哈希:` + 各自 SHA-256。
7. `### D-93 覆盖表` + 6 行表格,表头逐字 `| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |`;四类内容格先写 `待补`;行数写当前值。
8. `系列一致性契约` + 九条,逐条写成 `契约 N:` 开头的独立行(内容按 Task 0 的九条,逐字落地;第 6 条必须包含 `layout` 字样;如用户改过,以用户回复为准)。九条必须覆盖:`items` 形态、`Item` 来源、`selectedId` 空值、关闭归属、左侧最终方案、布局坐标(layout)、组件拆分与 props 链、key、事件流。
9. `体量参考(非门禁):` + 6 篇当前总行数与平均行数,写明「~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)」。
10. `停止点:10-52 只做 Part 5 深度扩写;不改 10-53 / 10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。`
**本任务不得修改任何 `docs/` 文件、不得改 ROADMAP / STATE / demo、不得派发扩写子代理。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-52 深度扩写(Part 5)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '停止点:10-51 扩写结束'){ Write-Error 'NO-1051-STOP' }; $pages=@('docs/advanced/ii/ui/inventory-example-1-skeleton.md','docs/advanced/ii/ui/inventory-example-2-grid.md','docs/advanced/ii/ui/inventory-example-3-detail.md','docs/advanced/ii/ui/inventory-example-4-scroll.md','docs/advanced/ii/ui/inventory-example-5-state.md','docs/advanced/ii/ui/inventory-example-6-animation-and-register.md'); foreach($k in @('## 10-52 深度扩写(Part 5)','扩写范围:','Round 1 内部输入:','基线 HEAD(10-52 深度扩写):','扩写前本批页面聚合哈希:','本批外文件聚合哈希:','ROADMAP 全文哈希:','STATE 全文哈希:','demo 快照哈希:','D-93 覆盖表','系列一致性契约','体量参考(非门禁):','停止点:10-52 只做')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-52 深度扩写):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('扩写前本批页面聚合哈希','本批外文件聚合哈希','ROADMAP 全文哈希','STATE 全文哈希','demo 快照哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; for($i=1;$i -le 9;$i++){ if($np -notmatch ('(?m)^契约 '+$i+':\S')){ Write-Error "NO-CONTRACT-$i" } }; foreach($k in @('items','selectedId','关闭','Scroll','layout','key','事件流')){ if($np.IndexOf($k) -lt 0){ Write-Error "CONTRACT-MISSING $k" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; $rows=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/' }); if($rows.Count -ne 6){ Write-Error ('MATRIX-ROWS:'+$rows.Count) }; foreach($p in $pages){ if(-not ($rows | Where-Object { $_.IndexOf($p) -ge 0 })){ Write-Error "NO-MATRIX-ROW $p" } }; foreach($r in $rows){ $c=@($r.Trim('|') -split '\|'); if($c.Count -lt 6){ Write-Error 'MATRIX-COLS' }; for($i=0;$i -lt 6;$i++){ if([string]::IsNullOrWhiteSpace($c[$i])){ Write-Error 'MATRIX-EMPTY' } } }; if($np -notmatch '116 条提问'){ Write-Error 'NO-ROUND1-COUNT' }; if($np -notmatch '178 行分节概率'){ Write-Error 'NO-PROB-COUNT' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-1051-STOP", "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NO-CONTRACT", "CONTRACT-MISSING", "NO-MATRIX-SECTION", "MATRIX-ROWS", "NO-MATRIX-ROW", "MATRIX-COLS", "MATRIX-EMPTY", "NO-ROUND1-COUNT", "NO-PROB-COUNT", "MD-COUNT", "DEMO-COUNT"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 有 `## 10-52 深度扩写(Part 5)` 与十项固定行;`契约 1:`..`契约 9:` 九条齐全且覆盖 `items` / `selectedId` / 关闭 / `Scroll` / 布局 / key / 事件流;覆盖表 6 篇完整路径、六列、四类内容格非空、行数为数字;Round 1 计数已记录;五个哈希为 64 位小写 hex;25 篇 / 24 demo 不变;未改任何 `docs/` 正文、ROADMAP / STATE、demo。</acceptance_criteria>
<done>Part 5 基线、覆盖表与系列一致性契约已落盘,正文未动。</done>
</task>
<task type="auto">
<name>Task 2: 扩写示例一至三(骨架、网格、详情:树与状态的第一次成型)</name>
<files>docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1 已写入 `## 10-52 深度扩写(Part 5)`、D-93 覆盖表与九条契约;6 篇现文未被本计划改动。</precondition>
<read_first>docs/advanced/ii/ui/{inventory-example-1-skeleton,inventory-example-2-grid,inventory-example-3-detail}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(这 3 篇提问与跨篇问题 12/13/29/31/32/33)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`契约 1`..`契约 9`)、docs/advanced/ii/ui/{props,component-tsx,events,conditional-and-list-rendering,builtin-list-and-containers}.md(已扩写的基础篇,只回指)</read_first>
<action>**只改示例一至三与 NOTES;不碰示例四至六、其它篇目与 demo。**
三篇按「目标 → 模型 → 代码 → 解释」组织,严格遵循 Task 1 的九条契约:
**(1)`inventory-example-1-skeleton.md`**
- 新增 `## 这一步要解决什么`:背包的目标、最终结构(左侧列表 + 右侧详情 + 底部操作)、本步只搭骨架不填数据;说明为什么先定骨架而不是先写数据。
- 新增 `## 骨架在渲染树里的位置`:720×480 根容器;左/右/底三个区域是根容器的子容器;区域坐标、尺寸、`zIndex` 与命中范围;底部操作条不与左侧列表重叠(坐标按契约 6)。
- 新增 `## 组件与文件怎么分`:五个文件的职责(`inventory-panel` / `item-grid` / `item-cell` / `item-detail` / `action-bar`);`InventoryPanel` 是根组件,其余是子树;本步只落地 `InventoryPanel` 与占位区。
- 新增 `## 打开、状态与关闭归谁`:`props.state.sceneController.open(InventoryUI, {})` / 面板内 `props.controller.open(...)`;`instance` 与关闭;`InventoryUI` 是 `GameUI` 对象;关闭归 `InventoryPanel`(契约 4)。
- 代码后解释:每个占位区在树上对应哪个子树、后续哪一步会替换它。
**(2)`inventory-example-2-grid.md`**
- 新增 `## 从占位到网格`:说明本步替换左侧占位区,右侧/底部仍是占位;`Item` 类型只定义一次(契约 2);`items` 是 `ref<Item[]>`(契约 1)。
- 新增 `## 网格的树结构`:`ItemGrid` 容器 → 若干 `ItemCell`;行列计算、间距、`loc` 相对网格容器;5 列示例的坐标来源;`zIndex` 与命中。
- 新增 `## 数据如何进入网格`:`InventoryPanel` 把 `items` 传给 `ItemGrid`,`ItemGrid` 用 `computed`/`map` 生成格子;`ItemCell` 只接收 `item` 与 `selected`,不直接读父级闭包(契约 7)。
- 新增 `## 点击如何上报`:`ItemCell` 的 `onClick` → `onSelect(item.id)` → `ItemGrid` → `InventoryPanel` 更新 `selectedId`(契约 9);给出调用链与每层职责。
- 新增 `## 这一步的边界`:网格暂不滚动;数据多时下一步用 `Scroll` 替换(契约 5);不要把本步的普通网格当成最终方案。
- 代码后解释:格子挂在树上哪一层、点击路径经过谁、`selectedId` 为什么在面板层。
**(3)`inventory-example-3-detail.md`**
- 新增 `## 详情区接的是哪个状态`:`selectedId` 是 `ref<string | null>`(契约 3);`null` 时显示「请选择道具」,有效 id 时显示详情;明确用户如何进入未选中状态(取消选择/初始状态),不要依赖 `undefined`。
- 新增 `## 详情区的树结构`:`ItemDetail` 容器 → 标题、图标、说明、数值;各子树与 `loc`;文本换行/滚动的边界(需要时用内置文本组件)。
- 新增 `## 选中态如何流到详情`:`InventoryPanel` 用 `computed` 从 `items` + `selectedId` 派生 `selectedItem`,传给 `ItemDetail`;不要在详情组件里再查一遍列表(契约 7)。
- 新增 `## 空态与边界`:未选中、选中项被删除、`items` 为空三种情况;每种给显示与恢复方式。
- 代码后解释:详情子树在树上的位置、选中态从哪来、为什么空态是面板的职责。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整组件上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 三篇之间的契约必须一致:`items` 形态、`Item` 来源、`selectedId` 空值、关闭归属、组件 props 链;发现前文与本计划契约冲突时以契约为准并在当页说明替换关系。
- 完成后更新 NOTES 覆盖表这 3 行为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $pages=@('docs/advanced/ii/ui/inventory-example-1-skeleton.md','docs/advanced/ii/ui/inventory-example-2-grid.md','docs/advanced/ii/ui/inventory-example-3-detail.md'); foreach($p in $pages){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $a=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[0])); foreach($k in @('720','480','渲染树','关闭','GameUI','占位')){ if($a.IndexOf($k) -lt 0){ Write-Error "EX1-MISSING $k" } }; $b=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[1])); foreach($k in @('Item','ref','ItemGrid','ItemCell','selectedId','onSelect','5 列')){ if($b.IndexOf($k) -lt 0){ Write-Error "EX2-MISSING $k" } }; $c=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[2])); foreach($k in @('selectedId','null','selectedItem','未选中','ItemDetail')){ if($c.IndexOf($k) -lt 0){ Write-Error "EX3-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-52 深度扩写(Part 5)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in $pages){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths=($pages -join ' '); $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "EX1-MISSING", "EX2-MISSING", "EX3-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>示例一讲清目标、720×480 骨架树、五个文件职责、打开/关闭归属与占位替换;示例二讲清 `Item` 单一定义、`items=ref<Item[]>`、网格树、数据与 props 链、点击上报、普通网格的阶段性;示例三讲清 `selectedId=ref<string|null>`、`selectedItem` 派生、详情树、空态与恢复。三篇契约一致;每次代码后有模型解释;NOTES 覆盖表 3 行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>示例一至三已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 3: 扩写示例四至六(滚动、状态、动画与注册:最终组装与一致性)</name>
<files>docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2 已写入 3 条 `已完成扩写:`;覆盖表这 3 行无 `待补`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>docs/advanced/ii/ui/{inventory-example-4-scroll,inventory-example-5-state,inventory-example-6-animation-and-register}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(这 3 篇提问与跨篇问题 12/13/29/31/32/33/34)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`契约 1`..`契约 9`)、docs/advanced/ii/ui/{builtin-list-and-containers,ui-controller-and-stack,ui-performance}.md(已扩写的基础篇,只回指)</read_first>
<action>**只改示例四至六与 NOTES;不碰示例一至三、其它篇目与 demo。**
三篇继续按「目标 → 模型 → 代码 → 解释」组织,严格遵循九条契约,并明确替换关系:
**(1)`inventory-example-4-scroll.md`**
- 新增 `## 为什么要换滚动`:网格超出左侧区域;普通容器不裁剪/不回收;`Scroll` 的职责与代价;明确本步替换示例二的普通网格(契约 5),示例五/六不再回到普通网格或 `ListPage`。
- 新增 `## Scroll 在渲染树里的位置`:`Scroll` 容器 → 内容容器 → `ItemGrid` → `ItemCell`;裁剪区域与命中;`zIndex` 与详情/操作条的关系;滚动位置在开关面板时是否保留。
- 新增 `## 数据与选中态如何穿过滚动层`:`items` 仍由 `InventoryPanel` 持有(契约 1);`Scroll` 只负责视口,不持有数据;`selectedId` 仍由面板持有;`ItemGrid` 的 props 链不变(契约 7)。
- 新增 `## 滚动与事件`:滚轮事件在 `Scroll` 上如何处理;子元素点击与滚动的手势冲突;`noevent`/`actionStroke` 是否需要。
- 代码后解释:新增的滚动层在树上插入在哪、哪些节点被裁剪、事件先经过谁。
**(2)`inventory-example-5-state.md`**
- 新增 `## 这一步把交互接起来`:装备、使用、关闭三类操作;状态归属(面板持有 `selectedId` 与提示文本,子组件只上报);关闭归面板(契约 4)。
- 新增 `## 操作条的树与事件流`:`ActionBar` → 按钮 → `onEquip` / `onUse` / `onClose` 回调 → 面板;按钮的禁用态(未选中时);事件路径与 `stopPropagation` 边界。
- 新增 `## 状态变化如何反映到画面`:点击装备/使用后 `items` 或提示如何变化;`selectedItem` 重算;不要直接改子组件内部状态来“假装”更新。
- 新增 `## 关闭的完整路径`:面板关闭按钮 → `props.controller.close(props.instance)`;子组件不直接关闭;关闭后实例与状态释放;如果用户要求“关闭前确认”,确认框走 UI 栈而不是在面板里硬编码。
- 代码后解释:操作条挂在树上哪一层、点击经过哪些回调、状态为什么集中在面板。
**(3)`inventory-example-6-animation-and-register.md`**
- 新增 `## 最后一步要收什么`:动画、五个文件落位、`GameUI` 注册、打开验证;列出最终文件清单与每个文件的职责(契约 7)。
- 新增 `## 动画作用在树的哪一层`:面板出现/关闭、选中高亮、提示淡出分别作用在哪个节点;动画不改变数据流与事件路径;卸载时清理定时器/监听。
- 新增 `## 最终组装与契约核对`:逐条对照契约 1–9(`items`、`Item`、`selectedId`、关闭、`Scroll`、布局坐标、组件拆分与 props 链、key、事件流);发现前文不一致时在当页给出最终写法与替换说明,不另起方案。
- 新增 `## 注册与打开`:`src/client/ui/<name>.tsx`、导出 `GameUI`、`src/client/ui/index.ts` 导出、从场景/主界面打开;`instance` 与关闭;`GameUI` 是对象不是名字查找。
- 新增 `## 最终验证清单`:打开、选中、滚动、装备/使用、关闭、再次打开;每项对应一条事件路径或树位置。
- 代码后解释:动画节点在树上的位置、注册后 UI 从哪条栈打开、最终代码为什么是自洽的。
**写法硬要求:**
- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整组件上下文(D-70),注释充足(D-65)。
- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。
- 三篇必须与示例一至三及九条契约一致;最终只保留一个左侧方案(`Scroll`)、一个 `selectedId` 空值语义、一个关闭归属;不得在同一篇里给两个方案让读者选。
- 完成后更新 NOTES 覆盖表这 3 行为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,记录门禁结果。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $pages=@('docs/advanced/ii/ui/inventory-example-4-scroll.md','docs/advanced/ii/ui/inventory-example-5-state.md','docs/advanced/ii/ui/inventory-example-6-animation-and-register.md'); foreach($p in $pages){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $a=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[0])); foreach($k in @('Scroll','裁剪','命中','ItemGrid','selectedId','渲染树')){ if($a.IndexOf($k) -lt 0){ Write-Error "EX4-MISSING $k" } }; $b=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[1])); foreach($k in @('ActionBar','onEquip','onUse','onClose','controller.close','状态')){ if($b.IndexOf($k) -lt 0){ Write-Error "EX5-MISSING $k" } }; $c=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[2])); foreach($k in @('动画','GameUI','src/client/ui','index.ts','契约','验证')){ if($c.IndexOf($k) -lt 0){ Write-Error "EX6-MISSING $k" } }; if($c -match 'ListPage'){ if($c -notmatch '不再|替换|不回|不使用|非最终|(?s)最终.*Scroll'){ Write-Error 'EX6-AMBIGUOUS-LEFT' } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-52 深度扩写(Part 5)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in $pages){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths=($pages -join ' '); $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "EX4-MISSING", "EX5-MISSING", "EX6-MISSING", "EX6-AMBIGUOUS-LEFT", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>示例四讲清滚动替换关系、`Scroll` 树位置、裁剪与命中、数据/选中态穿过滚动层、滚动手势与事件;示例五讲清操作条树与事件流、状态归属、关闭路径;示例六讲清动画作用层、最终组装与契约 1–9 核对、注册与打开、最终验证清单。三篇只保留 `Scroll` 一个左侧方案、一个 `selectedId` 语义、一个关闭归属;每次代码后有模型解释;NOTES 覆盖表 3 行为 `已讲` 且有 `自查:` / `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>示例四至六已按 D-93 扩写并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 4: 跨页一致性核对(按契约逐条比对 6 篇并修不一致)</name>
<files>docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 已完成并写入 3 条 `已完成扩写:`;覆盖表 6 行均无 `待补`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>6 篇扩写后的正文、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`契约 1`..`契约 9`)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(跨篇问题 12/13/29/31/32/33,只读)</read_first>
<action>**本任务只修 6 篇之间的不一致与 NOTES 记录;不新增功能、不另起方案、不碰 demo 与其它篇目。**
1. 逐条按契约 1–9 比对 6 篇:
- 契约 1:`items` 是否在 `InventoryPanel` 为 `ref<Item[]>`;子组件是否只通过 props 拿数据,是否出现直接引用父级闭包。
- 契约 2:`Item` 是否只定义一次;后续页面是否引用而不是重写。
- 契约 3:`selectedId` 是否统一为 `ref<string | null>`;初始值、有效值、未选中显示是否一致。
- 契约 4:关闭是否统一归 `InventoryPanel`;是否还有子组件直接 `close` 或只改提示的写法。
- 契约 5:左侧最终是否统一 `Scroll`;普通网格是否明确为阶段性实现;是否还有 `ListPage` 作为最终方案。
- 契约 6:布局坐标是否不重叠;各页坐标与最终页是否一致或有明确替换说明。
- 契约 7:五组件拆分与 props 链是否一致;是否出现未声明的隐式依赖。
- 契约 8:key 是否用 `item.id`;是否还有下标 key 被当成通用做法。
- 契约 9:事件流是否统一为 `ItemCell → ItemGrid → InventoryPanel`;操作条是否通过回调上报。
2. 发现不一致时,**只改与契约冲突的那几段/那几行**,保留其余内容;每处修正追加一行 `一致性修正:<path> — 契约 N:<原写法> → <最终写法>`。
3. 在 NOTES 追加 `### 10-52 一致性核对`,逐条写 `契约 N:通过` 或 `契约 N:已修正(见上)`;九条都必须出现。
4. 复核 6 篇的四类 D-93 覆盖仍为 `已讲`;不得因为修一致性把某篇的模型解释删掉。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-52 深度扩写(Part 5)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '(?m)^### 10-52 一致性核对'){ Write-Error 'NO-CONSISTENCY-SECTION' }; for($i=1;$i -le 9;$i++){ if($np -notmatch ('(?m)^契约 '+$i+':(通过|已修正)')){ Write-Error "NO-CONTRACT-CHECK-$i" } }; $pages=@('docs/advanced/ii/ui/inventory-example-1-skeleton.md','docs/advanced/ii/ui/inventory-example-2-grid.md','docs/advanced/ii/ui/inventory-example-3-detail.md','docs/advanced/ii/ui/inventory-example-4-scroll.md','docs/advanced/ii/ui/inventory-example-5-state.md','docs/advanced/ii/ui/inventory-example-6-animation-and-register.md'); $all=($pages | ForEach-Object { [IO.File]::ReadAllText((Resolve-Path -LiteralPath $_)) }) -join "`n"; if($all -notmatch 'ref<Item\[\]>'){ Write-Error 'NO-ITEMS-REF' }; if($all -notmatch 'ref<string \| null>'){ Write-Error 'NO-SELECTED-NULL' }; if($all -notmatch 'controller\.close\(props\.instance\)'){ Write-Error 'NO-CLOSE-OWNER' }; $badLeft=@($all -split "`r?`n" | Where-Object { (($_ -match '最终方案\s*是\s*ListPage') -or ($_ -match '最终.*(采用|使用|保留|选择)\s*[`"'']?ListPage')) -and $_ -notmatch '不|非|不是|排除|替换' }); if($badLeft.Count -gt 0){ Write-Error 'LEFT-FINAL-LISTPAGE' }; if($all -notmatch '(?s)最终.*Scroll|(?s)Scroll.*最终'){ Write-Error 'NO-FINAL-SCROLL' }; if($all -match 'key=\{index\}' -and $all -notmatch '无状态|静态列表'){ Write-Error 'KEY-INDEX-UNEXPLAINED' }; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if($m.Groups[1].Value -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths=($pages -join ' '); $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-CONSISTENCY-SECTION", "NO-CONTRACT-CHECK", "NO-ITEMS-REF", "NO-SELECTED-NULL", "NO-CLOSE-OWNER", "LEFT-FINAL-LISTPAGE", "NO-FINAL-SCROLL", "KEY-INDEX-UNEXPLAINED", "NO-DONE", "NO-SELF-CHECK", "MATRIX-STILL-PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>6 篇按契约 1–9 统一:`items` 为 `ref<Item[]>`、`Item` 单一定义、`selectedId` 为 `ref<string | null>`、关闭归面板、最终左侧为 `Scroll`(只有肯定性 ListPage 终选才失败;ListPage 作为阶段性对照允许)、布局不重叠、五组件 props 链一致、key 用 `item.id`、事件流统一;NOTES 有 `### 10-52 一致性核对` 且九条均有 `通过` / `已修正`;每次修正有 `一致性修正:` 行;四类覆盖仍为 `已讲`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。</acceptance_criteria>
<done>6 篇跨页一致性已按契约收口,构建通过。</done>
</task>
<task type="auto">
<name>Task 5: 门禁 + D-93 抽查 + 体量记录 + 停止</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2–4 已把 6 篇的四类内容格改为 `已讲`(或 `不适用:理由`),并各写入 `自查:` 与 `已完成扩写:`;一致性核对九条已记录;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-52 深度扩写(Part 5)` 全部内容与一致性核对)、docs/advanced/ii/ui/inventory-example-*.md(6 篇)、.planning/ROADMAP.md、.planning/STATE.md</read_first>
<action>**只校验、记录与停止;除 NOTES 外不改任何文件。**
1. **D-93 抽查**:逐篇核对四类内容;每篇写 `D-93 抽查:<path> — 通过` 或 `— 发现缺口(缺口一句)`;有缺口先修到通过。
2. **结构门禁**:25 篇 / 24 demo 不变;6 篇 CRLF;无 `待补` 覆盖格;每篇有 `自查:` 与 `已完成扩写:`;无「模板 / 需改 / 简化版 / v1 / 以后再做」;一致性核对九条齐全。
3. **聚合哈希门禁**:重算 `本批外文件聚合哈希`、`ROADMAP 全文哈希`、`STATE 全文哈希`、`demo 快照哈希`,与 Task 1 一致;重算 `扩写后本批页面聚合哈希`,必须与扩写前不同。
4. **prettier**:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后 `--check`。
5. **ESLint**:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,exit 0、输出不含 `error` / `warning`。
6. **docs 类型**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,`docs/` 路径 0 条 `error TS`;既有引擎报错只记录条数。
7. **构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,exit 0、含 `build complete`、无 `dead link`;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。
8. **写 NOTES**:追加 `扩写后本批页面聚合哈希`、`体量参考(扩写后)`(逐篇行数 + 总行数,再次写明不设 300 行门禁)、`### 10-52 门禁`(命令、结果、`docs/` 路径 0 类型错误、既有引擎报错条数、构建耗时、25 HTML、D-93 逐篇结论)、`停止点:10-52 扩写结束;25 篇扩写全部完成;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-53 / 10-54;未 commit。`
9. **立即停止**:不创建 SUMMARY、不改 ROADMAP / STATE、不 commit、不派发读者。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-52 深度扩写(Part 5)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; $pages=@('docs/advanced/ii/ui/inventory-example-1-skeleton.md','docs/advanced/ii/ui/inventory-example-2-grid.md','docs/advanced/ii/ui/inventory-example-3-detail.md','docs/advanced/ii/ui/inventory-example-4-scroll.md','docs/advanced/ii/ui/inventory-example-5-state.md','docs/advanced/ii/ui/inventory-example-6-animation-and-register.md'); foreach($k in @('扩写后本批页面聚合哈希:','体量参考(扩写后):','### 10-52 门禁','D-93 抽查:','停止点:10-52 扩写结束')){ if($sec.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($sec -notmatch '(?m)^扩写后本批页面聚合哈希:[0-9a-f]{64}'){ Write-Error 'NO-POST-HASH' }; $mpre=[regex]::Match($sec,'(?m)^扩写前本批页面聚合哈希:([0-9a-f]{64})'); $mpost=[regex]::Match($sec,'(?m)^扩写后本批页面聚合哈希:([0-9a-f]{64})'); if(-not $mpre.Success -or -not $mpost.Success){ Write-Error 'NO-BATCH-HASH' }; if($mpre.Groups[1].Value -eq $mpost.Groups[1].Value){ Write-Error 'BATCH-UNCHANGED' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; if($m.Groups[1].Value -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; foreach($p in $pages){ if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" }; if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" } }; $d93bad=@(); foreach($p in $pages){ $d93lines=@($sec -split "`r?`n" | Where-Object { $_ -match ('^D-93 抽查:'+[regex]::Escape($p)) }); if($d93lines.Count -eq 0){ $d93bad += ($p+':NO-LINE') } elseif($d93lines[-1] -match '发现缺口'){ $d93bad += $p } }; if($d93bad.Count -gt 0){ Write-Error ('D93-GAP '+($d93bad -join ',')) }; for($i=1;$i -le 9;$i++){ if($np -notmatch ('(?m)^契约 '+$i+':(通过|已修正)')){ Write-Error "NO-CONTRACT-CHECK-$i" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($p in $pages){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match "(?<!\r)\n"){ Write-Error "LF-ONLY $p" }; if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $sorted=@($pages | Sort-Object); $joined=($sorted | ForEach-Object { $_ + ':' + ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $_)))).Replace('-','').ToLower()) }) -join "`n"; $h=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($joined))).Replace('-','').ToLower(); if($sec -notmatch ('(?m)^扩写后本批页面聚合哈希:'+$h)){ Write-Error 'POST-HASH-MISMATCH' }; $roadText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md')); $roadHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($roadText))).Replace('-','').ToLower(); $mr=[regex]::Match($np,'(?m)^ROADMAP 全文哈希:([0-9a-f]{64})'); if(-not $mr.Success -or $mr.Groups[1].Value -ne $roadHash){ Write-Error 'ROADMAP-MODIFIED' }; $stText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); $stHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($stText))).Replace('-','').ToLower(); $ms=[regex]::Match($np,'(?m)^STATE 全文哈希:([0-9a-f]{64})'); if(-not $ms.Success -or $ms.Groups[1].Value -ne $stHash){ Write-Error 'STATE-MODIFIED' }; $demoPaths=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File | ForEach-Object { 'docs/.vitepress/components/demos/ui/' + $_.Name } | Sort-Object); $demoJoined=($demoPaths | ForEach-Object { $_ + ':' + ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $_)))).Replace('-','').ToLower()) }) -join "`n"; $demoH=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($demoJoined))).Replace('-','').ToLower(); $mdemo=[regex]::Match($np,'(?m)^demo 快照哈希:([0-9a-f]{64})'); if(-not $mdemo.Success -or $mdemo.Groups[1].Value -ne $demoH){ Write-Error 'DEMO-MODIFIED' }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0Line truncated
<fails_when>non-zero exit, or output contains "NOTES-MISSING", "NO-POST-HASH", "NO-BATCH-HASH", "BATCH-UNCHANGED", "NO-MATRIX-SECTION", "MATRIX-STILL-PENDING", "NO-SELF-CHECK", "NO-DONE", "D93-GAP", "NO-CONTRACT-CHECK", "MD-COUNT", "DEMO-COUNT", "DEMO-MODIFIED", "LF-ONLY", "SCOPE-REDUCTION", "POST-HASH-MISMATCH", "ROADMAP-MODIFIED", "STATE-MODIFIED", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "UNEXPECTED-SUMMARY"; or output lacks "T5-OK"</fails_when>
</verify>
<acceptance_criteria>6 篇覆盖格无 `待补`、逐篇 `自查:` / `已完成扩写:`、`D-93 抽查` 无缺口、九条契约核对齐全;`扩写后本批页面聚合哈希` 与扩写前不同且与重算一致;批外/ROADMAP/STATE/demo 哈希未变;25 篇 / 24 demo 不变;6 篇 CRLF、无降级表述;prettier / ESLint 0/0 / `docs/` 路径 0 类型错误 / 构建 green + 0 dead link / 25 个 HTML;NOTES 有体量参考、`### 10-52 门禁`、停止点;未创建 SUMMARY。</acceptance_criteria>
<done>Part 5 扩写完成,25 篇全部扩写完毕并通过门禁,停在读者循环之前。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 6 篇示例 → 读者 | 必须讲清每一步的树/事件/状态与理由,不能只给连续代码 |
| 单页 → 系列契约 | 单页改动不得另起方案;跨页必须与九条契约一致 |
| 本计划 → 批外文档 | 只允许改 6 篇;其余 19 篇、导览、demo、侧边栏不得改动 |
| 本计划 → 账本 | 不写 SUMMARY、不改 ROADMAP / STATE、不 commit |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-187 | Tampering | 跨页方案不一致 | high | mitigate | Task 1 九条契约;Task 4 逐条核对并修不一致;Task 5 校验契约核对九条 |
| T-10-188 | Tampering | 示例写成代码堆叠 | high | mitigate | 每篇「目标→模型→代码→解释」;每次代码后解释树/事件/状态与理由 |
| T-10-189 | Tampering | 批外文档 / demo 被改动 | high | mitigate | Task 1 记录 `本批外文件聚合哈希` 与 `demo 快照哈希`;Task 5 重算比对 |
| T-10-190 | Repudiation | 扩写退化为只补读者问题 | high | mitigate | D-93 四类覆盖表逐页判定;跨篇问题收口成契约 |
| T-10-191 | Tampering | 为凑 300 行注水 | medium | mitigate | 体量只记录不设门禁;禁止接口表堆砌与降级表述 |
| T-10-192 | Information Disclosure | 把 Round 1 读者记录交给用户 | medium | mitigate | Round 1 仅内部输入;本计划不产出用户可读审阅摘要 |
| T-10-193 | Repudiation | 越界写 SUMMARY / ROADMAP / STATE | medium | mitigate | Task 5 校验 ROADMAP / STATE 全文哈希;禁止创建 SUMMARY |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 关卡门禁:Task 0 已获「可以执行」;10-51 已写入停止点。
- 基线门禁:Task 1 写入 6 篇范围、Round 1 计数、基线 HEAD、两个聚合哈希、两个账本哈希、demo 快照哈希、九条契约、体量参考。
- 覆盖门禁:6 篇四类内容格为 `已讲` 或 `不适用:理由`,无 `待补`;每篇有 `自查:` 与 `已完成扩写:`;`D-93 抽查` 无缺口。
- 一致性门禁:契约 1–9 均有 `通过` / `已修正`;6 篇统一 `items=ref<Item[]>`、`Item` 单一定义、`selectedId=ref<string|null>`、关闭归面板、最终左侧 `Scroll`、布局不重叠、五组件 props 链、key 用 `item.id`、事件流统一。
- 范围门禁:25 篇 / 24 demo;`本批外文件聚合哈希` 与 `demo 快照哈希` 与基线一致;未改导览、侧边栏、`packages*` / `src`。
- 质量门禁:6 篇 CRLF;prettier `--check`;ESLint 0/0;`docs/` 路径 0 类型错误;构建 green + 0 dead link;25 个 HTML。
- 体量门禁:只记录行数;不设 300 行下限/上限;不因低于 300 行失败。
- 停止门禁:NOTES 有 `停止点:10-52 扩写结束`;未创建 SUMMARY;ROADMAP / STATE / demo 哈希未变;未 commit。
</verification>
<success_criteria>
- Part 5 的 6 篇按 D-93 讲清每一步的树位置、事件路径、状态归属与理由,读者能复述「为什么现在加这个组件」。
- 6 篇按九条契约自洽:`items`、`Item`、`selectedId`、关闭、左侧方案、布局、组件拆分、key、事件流只有一个答案,读者能拼出最终代码。
- 没有新增/删除页面与 demo,没有改动批外文档、demo 与源码。
- 门禁全绿,体量只作参考记录,25 篇扩写全部完成并停在读者循环之前。
</success_criteria>
<output>
本计划**不写 SUMMARY**。完成后在对话中报告 6 篇扩写清单、逐篇行数(体量参考)、九条契约核对结论、D-93 抽查结论与门禁结果,然后停止。读者循环由 `10-53-PLAN.md` 执行,用户审阅由 `10-54-PLAN.md` 执行。
</output>
@@ -0,0 +1,367 @@
---
phase: 10-docs-restructure
plan: 53
type: execute
wave: 11
depends_on:
- 10-49
- 10-50
- 10-51
- 10-52
files_modified:
- .planning/phases/10-docs-restructure/10-53-READER-REVIEW.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- docs/advanced/ii/ui/ui-template.md
- docs/advanced/ii/ui/container-and-coordinates.md
- docs/advanced/ii/ui/basic-shapes.md
- docs/advanced/ii/ui/curves-and-paths.md
- docs/advanced/ii/ui/text.md
- docs/advanced/ii/ui/image-and-texture.md
- docs/advanced/ii/ui/layer-transform-performance.md
- docs/advanced/ii/ui/reactivity.md
- docs/advanced/ii/ui/events.md
- docs/advanced/ii/ui/hotkey-in-ui.md
- docs/advanced/ii/ui/conditional-and-list-rendering.md
- docs/advanced/ii/ui/props.md
- docs/advanced/ii/ui/component-tsx.md
- docs/advanced/ii/ui/slots-and-attrs.md
- docs/advanced/ii/ui/builtin-text-and-input.md
- docs/advanced/ii/ui/builtin-list-and-containers.md
- docs/advanced/ii/ui/ui-controller-and-stack.md
- docs/advanced/ii/ui/replace-builtin-ui.md
- docs/advanced/ii/ui/ui-performance.md
- docs/advanced/ii/ui/inventory-example-1-skeleton.md
- docs/advanced/ii/ui/inventory-example-2-grid.md
- docs/advanced/ii/ui/inventory-example-3-detail.md
- docs/advanced/ii/ui/inventory-example-4-scroll.md
- docs/advanced/ii/ui/inventory-example-5-state.md
- docs/advanced/ii/ui/inventory-example-6-animation-and-register.md
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 92000
raw_tokens: 56000
tasks: 6
confidence: low
must_haves:
truths:
- "Round 1 已完成并保留在 `10-49-READER-REVIEW.md`;本计划只执行 Round 2 与 Round 3,总计不超过 3 轮(D-91 第 3 条)"
- "每轮由 orchestrator 分别派发多个独立读者,按 Part 分组(Part 0–1 / 2–3 / 4 / 5),不得由一个子代理包办全部篇目;复审使用新上下文,不复用上一轮问题清单(D-91 第 2 条)"
- "读者只读 Markdown、不读源码、不做 live、只提问,不判断对错、不提修改方案(D-91 第 1 条 / D-89)"
- "每轮汇总后只修阻断性问题:缺前置、术语未定义、步骤缺失导致无法继续、明确矛盾、缺 import/入口、D-93 的模型/事件/组件没讲清;设计取舍、风格、详略、是否补充内容不作为缺陷(D-91 第 3 条 / D-93 第 5 条)"
- "修订者必须同时收到 D-93 与该轮审阅结论,不能只按问题清单修;每轮修订后重新派新读者复审(D-91 第 4 条 / D-93 第 5 条)"
- "记录 append-only、带 `### 第 N 轮`,只写在 `10-53-READER-REVIEW.md` 与 NOTES;不写入 docs 正文,不交给用户(D-91 第 5 条 / D-92)"
- "连续一轮无阻断即结束;3 轮后仍有阻断,停止并只报告受影响页面/章节,不向用户展示读者问题清单(D-91 第 4 条)"
- "循环结束即停止:不进入用户审阅、不写 SUMMARY / ROADMAP / STATE、不 commit(D-90 / D-92)"
artifacts:
- ".planning/phases/10-docs-restructure/10-53-READER-REVIEW.md(第 2/3 轮读者问题、分诊、修订、复审结论;append-only)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 `## 10-53 独立读者循环(第 2/3 轮)`:基线、派发方式、轮次结论、最终门禁、停止点)"
- "docs/advanced/ii/ui/*.md(只修阻断性问题的段落;不新增/删除页面,不改 demo)"
key_links:
- "Round 1 是输入不是答案:它只提供 116 条历史问题,Round 2 必须用新读者、新上下文重新提问,否则会把旧结论当现状(D-91 第 2 条)"
- "阻断与偏好分离:把设计取舍当阻断会让文档被改成读者口味;把真正的阻断当偏好会留下读不下去的页面(D-91 第 3 条)"
- "修订者必须收到 D-93:只按问题清单修会漏掉同类缺口,下一轮又会出现同型问题(D-93 第 5 条)"
- "记录不交用户:读者记录是内部质量环节;用户审阅只看最终文档(D-92 第 1 条)"
---
<scope_justification>
本计划是独立的读者内部循环,承接 10-49..10-52 的 25 篇深度扩写:
- Round 1 已完成(`10-49-READER-REVIEW.md`:25 篇、116 条提问、178 行分节概率),本计划只执行 Round 2 与 Round 3,总计 3 轮,符合 D-91 的上限。
- 每轮按 Part 分派多个读者,而不是一个读者读 25 篇:D-91 明确禁止单代理包办;按 Part 分组也让每个读者只携带自己那组的前置上下文,问题更接近真实阅读。
- 只修阻断性问题:设计取舍、风格、详略偏好不进入修订;否则会违背 D-88 / D-91,把内部循环变成无休止的改写。
- 本计划只改正文中阻断性问题的段落、读书记录与 NOTES;不新增/删除页面与 demo、不写 SUMMARY、不改 ROADMAP / STATE、不 commit。
</scope_justification>
<objective>
在 25 篇深度扩写完成后,执行 D-91 的 Round 2 / Round 3 独立读者循环:每轮由 orchestrator 按 Part 分派多个与新上下文无关的读者,只读 Markdown、只提问;汇总后只修阻断性问题,修订者同时收到 D-93 与该轮结论;每轮修订后派新读者复审,连续一轮无阻断即结束,3 轮后仍有阻断则停止并只记录受影响页面/章节。
Purpose: 深度扩写是否真的能让目标读者只靠文档写出 UI,不能由写作者自评;但读者问题也不等于缺陷,必须按 D-91 只修阻断问题,且记录不交给用户(D-92)。
Output: `10-53-READER-REVIEW.md`(第 2/3 轮完整记录)+ NOTES 中的基线、派发方式、轮次结论与最终门禁。**不进入用户审阅、不写 SUMMARY / ROADMAP / STATE、不 commit。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md
@.planning/phases/10-docs-restructure/10-49-PLAN.md
@.planning/phases/10-docs-restructure/10-50-PLAN.md
@.planning/phases/10-docs-restructure/10-51-PLAN.md
@.planning/phases/10-docs-restructure/10-52-PLAN.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
@docs/.vitepress/config.ts
**流程约定:**
- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-52` 计划与 SUMMARY、不改 POC 文件、不改 `docs/` 其它页面与 demo、不改 `packages/` / `packages-user/` / `src/`。
- **Task 0 是硬关卡**:汇报 Round 2/3 的派发方式、读者人格、阻断判定、修订范围、记录归属与停止条件,等用户明确回复「可以执行」。
- 修改方式为**派发子代理执行**;读者与修订者都由 orchestrator 派发,executor 只做基线、汇总、分诊记录与门禁。**不得由一个子代理包办全部篇目,不得由写作者自审替代。**
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 代码注释;不 commit(D-90)。
- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。
**本批事实(执行时以这些为准):**
- 10-49..10-52 已完成 25 篇深度扩写,各自停在读者循环之前;Round 1 记录在 `10-49-READER-REVIEW.md`,本计划不复制、不改写该文件,只把它当内部输入。
- 25 篇顺序与 Part 分组以 `docs/.vitepress/config.ts` 为准:Part 0–1(7 篇)、Part 2–3(7 篇)、Part 4(5 篇)、Part 5(6 篇)。
- 读者不得读 `packages/`、`packages-user/`、`src/` 下任何源码,也不得读 `.ts` / `.tsx` 实现;不做 live。
- 修订只允许改阻断性问题对应的段落;新增/删除页面、改 demo、改导览、改侧边栏一律禁止。
- 记录只追加,不覆盖;每轮用 `### 第 N 轮` 标题;历史轮次逐字保留。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报 Round 2/3 派发方式、阻断判定与停止条件,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CONTEXT.md(D-89、D-90、D-91、D-92、D-93)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构与计数,不复制)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-49..10-52 扩写小节与停止点)、docs/advanced/ii/index.md、docs/.vitepress/config.ts</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——只做一件事:执行 D-91 的 Round 2 与 Round 3 独立读者循环(Round 1 已完成,计入 3 轮上限)。每轮按 Part 分派多个读者,只读 25 篇 Markdown、只提问;汇总后只修阻断性问题;修订后派新读者复审;连续一轮无阻断即结束。**不进入用户审阅、不写 SUMMARY / ROADMAP / STATE、不 commit。**
**为什么**——深度扩写是否可读不能由写作者自评;但读者问题也不等于缺陷,很多是设计取舍或风格偏好。D-91 要求只修阻断问题,并把读者记录留在内部;D-92 要求用户只看最终文档,不看读者问题清单。
**大致怎么做**——Task 1 写基线与 Round 1 输入边界,创建 `10-53-READER-REVIEW.md`(含 `### 第 2 轮` 占位,不复制 Round 1 内容);Task 2 派 4 个读者(Part 0–1 / 2–3 / 4 / 5)做 Round 2,汇总并分诊;Task 3 只修阻断问题(修订者收到 D-93 + 本轮结论);Task 4 若 Round 2 有阻断,派全新读者做 Round 3;若 Round 2 无阻断,记录「第 3 轮未执行」并结束;Task 5 跑最终门禁、写结论并停止。
**影响范围**——只新增/追加 `10-53-READER-REVIEW.md` 与 NOTES,只改正文中阻断问题对应的段落。不改其它计划、导览、侧边栏、24 个 demo、`packages/` / `packages-user/` / `src/`、既有注释、ROADMAP / STATE;不写 SUMMARY;不 commit。
**读者人格(逐字,每轮复用;复审使用新上下文):**
「你是一位刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。你完全没写过 UI,不知道 canvas 是什么,也不会 Vue 的组件写法;你只掌握了基础 TS/JS、函数、对象、数组和一点点模板语法。你手里只有这套文档,不能看源码,也没有人可以问。你的任务不是评价文档好坏,而是老老实实按顺序读,读到哪里卡住就记下:我在哪一段卡住、我从文档里已经知道了什么、我还缺什么才能继续往下做。」
**派发与分组(硬约束):**
- Round 2 至少 4 个读者:A(Part 0–1,7 篇)、B(Part 2–3,7 篇)、C(Part 4,5 篇)、D(Part 5,6 篇)。每个读者只读自己那组 + 必要前置,不读其它组全文。
- 不得由一个子代理读完全部 25 篇;不得由写作者或 executor 自审替代。
- Round 3 使用全新上下文,**不附上一轮问题清单**;只给 D-93 检查项与该组篇目。
- 若 executor 不能派发,立即返回 `## READER-DISPATCH-REQUIRED`,由 orchestrator 派发;executor 只做记录与门禁。
**阻断判定(只修这些):**
- 缺前置:读到这里需要某个概念/接口,但文档没有指路或没有解释。
- 术语未定义:关键术语首次出现没有定义,读者无法继续。
- 步骤缺失:照文档做无法继续(缺一个必要步骤、缺 import/入口、缺注册点)。
- 明确矛盾:同一篇或跨篇对同一件事给出互斥说法。
- D-93 的模型/事件/组件没讲清:读者无法复述渲染树、捕获/冒泡、组件拆分与 props/slots/attrs 的作用。
- **不修**:设计取舍、风格、详略、是否补充更多示例、假设性边界。
**记录归属**——`10-53-READER-REVIEW.md` 与 NOTES 只作内部记录,append-only,带 `### 第 N 轮`;不写入 docs 正文,不交给用户(D-91 / D-92)。
**请用户确认:**
1. 执行 Round 2 / Round 3,Round 1 计入,最多 3 轮。
2. Round 2 至少 4 个读者按 Part 分组;不得单代理包办;Round 3 用新上下文、不附上一轮问题清单。
3. 只修上述阻断问题;设计取舍/风格/详略不修。
4. 修订者必须收到 D-93 + 该轮结论;每轮修订后派新读者复审。
5. 记录 append-only、不交给用户;循环结束即停止,不进入用户审阅、不写 SUMMARY / ROADMAP / STATE、不 commit。
6. 本次修改方式为**派发子代理执行**;不改既有注释;不调用 `opencode` 命令。
**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报循环范围、派发方式、阻断判定、修订要求、记录归属与停止条件。</what-built>
<how-to-verify>确认:①Round 2/3、最多 3 轮;②至少 4 读者按 Part 分组、不得单代理包办、Round 3 新上下文;③只修阻断问题、不修偏好;④修订者收到 D-93 + 轮次结论;⑤记录 append-only 不交用户;⑥结束即停、不写 SUMMARY / ROADMAP / STATE、不 commit。</how-to-verify>
<resume-signal>回复「可以执行」以继续;其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且循环轮次、读者分组、阻断判定、修订要求、记录归属、停止条件六项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,且循环轮次、读者分组、阻断判定、修订要求、记录归属、停止条件均已确认。</human-check>
</verify>
<done>用户回复「可以执行」且六项待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 循环前基线 + Round 1 输入边界 + 创建第 2 轮记录骨架(不改正文)</name>
<files>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>10-49..10-52 均已写入 `停止点:10-5X 扩写结束`;`10-49-READER-REVIEW.md` 存在;25 篇已扩写完成;用户已在 Task 0 回复「可以执行」。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(四个扩写小节与停止点)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读标题/计数/结构,不复制内容)、docs/.vitepress/config.ts(25 条顺序与 6 个 Part)、docs/advanced/ii/index.md、docs/advanced/index.md</read_first>
<action>**本任务只建基线与记录骨架,绝对不改 `docs/` 正文、不派读者。**
**(1)向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-53 独立读者循环(第 2/3 轮)`**,写入以下固定行:
1. `循环范围:` 25 篇 `docs/advanced/ii/ui/*.md`;Round 1 已完成(`10-49-READER-REVIEW.md`:25 篇、116 条提问、178 行分节概率),本计划执行 Round 2 / Round 3,最多 3 轮。
2. `Round 1 输入边界:` 只作内部输入,不复制、不改写、不交给用户;Round 2 读者使用新上下文。
3. `基线 HEAD(10-53 读者循环):` + `git rev-parse HEAD` 完整 sha。
4. `循环前 docs 快照哈希:` + 对 25 篇 + `docs/advanced/ii/index.md` + `docs/advanced/index.md` 取聚合 SHA-256(按 `docs/...` 相对路径排序,逐文件取 SHA-256,拼 `相对路径:hash` 后 LF 连接,再 SHA-256)。
5. `读者派发方式:` 先写 `待派发`,Task 2 派发后改为 `orchestrator 子代理(4 组)`。
6. `阻断判定口径:` 缺前置、术语未定义、步骤缺失、明确矛盾、缺 import/入口、D-93 模型/事件/组件没讲清;设计取舍/风格/详略不修。
7. `停止点:10-53 只做读者循环;不进入 10-54 用户审阅;不写 SUMMARY / ROADMAP / STATE;不 commit。`
**(2)新建 `.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md`**(CRLF、UTF-8、append-only):
1. 标题 `# 10-53 独立读者循环记录(第 2/3 轮)`。
2. 一句说明「Round 1 见 `10-49-READER-REVIEW.md`,本文件只记录 Round 2/3,不复制 Round 1 内容;记录不交给用户。」
3. `### 第 2 轮` 标题,下面先写 `派发状态:见 Task 2`。
4. 末尾一句「以下按轮追加;历史轮次逐字保留,不得覆盖、合并或改写。」
**本任务不得改任何 `docs/` 文件、不得派发读者、不得写第 3 轮内容。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '停止点:10-52 扩写结束'){ Write-Error 'NO-1052-STOP' }; foreach($k in @('## 10-53 独立读者循环(第 2/3 轮)','循环范围:','Round 1 输入边界:','基线 HEAD(10-53 读者循环):','循环前 docs 快照哈希:','读者派发方式:','阻断判定口径:','停止点:10-53 只做读者循环')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-53 读者循环):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; if($np -notmatch '(?m)^循环前 docs 快照哈希:[0-9a-f]{64}'){ Write-Error 'NO-SNAPSHOT' }; if($np -notmatch '(?m)^读者派发方式:(待派发|orchestrator 子代理(4 组))'){ Write-Error 'BAD-DISPATCH' }; $r='.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md'; if(-not(Test-Path -LiteralPath $r)){ Write-Error 'MISSING-REVIEW' }; $rp=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $r)); foreach($k in @('# 10-53 独立读者循环记录(第 2/3 轮)','10-49-READER-REVIEW.md','### 第 2 轮','派发状态:见 Task 2','不交给用户')){ if($rp.IndexOf($k) -lt 0){ Write-Error "REVIEW-MISSING $k" } }; if($rp -match "(?<!\r)\n"){ Write-Error 'REVIEW-LF-ONLY' }; if($rp.IndexOf('### 第 3 轮') -ge 0){ Write-Error 'ROUND3-TOO-EARLY' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-1052-STOP", "NOTES-MISSING", "BAD-BASE-HEAD", "NO-SNAPSHOT", "BAD-DISPATCH", "MISSING-REVIEW", "REVIEW-MISSING", "REVIEW-LF-ONLY", "ROUND3-TOO-EARLY", "MD-COUNT", "DEMO-COUNT"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 有 `## 10-53 独立读者循环(第 2/3 轮)` 与八项固定行;`基线 HEAD` 可解析、`循环前 docs 快照哈希` 为 64 位小写 hex、`读者派发方式` 为 `待派发` 或 `orchestrator 子代理(4 组)`;`10-53-READER-REVIEW.md` 存在、CRLF、含标题、Round 1 指针、`### 第 2 轮`、`派发状态:见 Task 2`、`不交给用户`,且尚无 `### 第 3 轮`;25 篇 / 24 demo 不变;未改任何 `docs/` 正文。</acceptance_criteria>
<done>循环基线与第 2 轮记录骨架已就绪,正文未动。</done>
</task>
<task type="auto">
<name>Task 2: Round 2 派发 4 组独立读者 + 汇总分诊</name>
<files>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 1 已创建 `10-53-READER-REVIEW.md` 的 `### 第 2 轮` 骨架;NOTES 的 `读者派发方式` 为 `待派发`;task 0 已获「可以执行」。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-53` 基线、四个扩写小节的 D-93 口径)、.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md(第 2 轮骨架)、docs/.vitepress/config.ts(25 条顺序与 6 个 Part)、docs/advanced/ii/index.md、docs/advanced/index.md</read_first>
<action>**本任务只派读者、汇总与分诊,不改 `docs/` 正文。**
**(1)派发(硬约束):**
- 由 orchestrator 分别派发 4 个独立读者子代理:A(Part 0–1,7 篇)、B(Part 2–3,7 篇)、C(Part 4,5 篇)、D(Part 5,6 篇)。每个读者只读自己那组 + 必要前置(导览、中级相关篇目),不读其它组全文。
- **不得由一个子代理读完全部 25 篇**;不得由写作者或 executor 自审替代。若执行器不能派发,立即返回 `## READER-DISPATCH-REQUIRED`,附读者 prompt 与分组,由 orchestrator 派发;executor 只做记录与门禁。
- 派出后在 NOTES 写 `读者派发方式:orchestrator 子代理(4 组)`。
**(2)读者 prompt(逐字,每轮复用;复审使用新上下文):**
「你是一位刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。你完全没写过 UI,不知道 canvas 是什么,也不会 Vue 的组件写法;你只掌握了基础 TS/JS、函数、对象、数组和一点点模板语法。你手里只有这套文档,不能看源码,也没有人可以问。你的任务不是评价文档好坏,而是老老实实按顺序读,读到哪里卡住就记下:我在哪一段卡住、我从文档里已经知道了什么、我还缺什么才能继续往下做。」
**读者硬约束(写进每次派发):**
- 只读 Markdown:本组 25 篇中的对应篇目 + 导览 + 必要前置;**不得读 `packages/`、`packages-user/`、`src/` 下任何源码**,不得读 `.ts` / `.tsx` 实现。
- 按顺序读,不跳读、不先看结论;不做 live、不启动浏览器。
- 只提问:每条含「位置 / 已经从文档知道什么 / 还缺什么 / 照着做会预期什么」;**不判断对错、不评价风格、不提修改方案、不猜实现**。
- D-93 复述检查:读完后尝试复述「渲染树怎么建立、捕获/冒泡顺序、组件拆分与 props/slots/attrs 的作用」,把复述不出来的地方作为问题记录;不要给答案。
- 不为凑数提假设性、极低概率、需要刻意构造的边界;只记正常定制流程中会遇到的卡点。
**(3)汇总与分诊:** 把 4 组结果按组写入 `10-53-READER-REVIEW.md` 的 `### 第 2 轮` 下:
- 每组一个 `#### 读者 A(Part 0–1)` / `#### 读者 B(Part 2–3)` / `#### 读者 C(Part 4)` / `#### 读者 D(Part 5)`,组内逐条问题,写完整路径与章节。
- `#### 汇总与分诊` 表格,列为 `编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由 | 处理`;编号 `R2-01` 起;「是否阻断」只能填 `阻断` 或 `非阻断`;「理由」引用 D-91 的六类阻断之一,或写「设计取舍 / 风格 / 详略 / 假设边界」;「处理」填 `修` 或 `不修`。
- 统计行:`第 2 轮阻断数:N`;`第 2 轮非阻断数:M`。
- 追加一行 `状态:已汇总`(不覆盖上面的 `派发状态` 行)。
- 追加一行 `概率继承:Round 1 的 178 行分节概率继续有效;本轮新增/重写章节由读者补「高 / 中 / 低 + 理由」,记在本轮读者小节内。`
**本任务不得修改任何 `docs/` 文件;读者提出的一切只进记录。** 若读者返回内容缺组、缺路径或缺分诊字段,让读者在记录内补齐,不得改正文。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $r='.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md'; if(-not(Test-Path -LiteralPath $r)){ Write-Error 'MISSING-REVIEW' }; $rp=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $r)); foreach($k in @('### 第 2 轮','#### 读者 A(Part 0–1)','#### 读者 B(Part 2–3)','#### 读者 C(Part 4)','#### 读者 D(Part 5)','#### 汇总与分诊','第 2 轮阻断数:','第 2 轮非阻断数:','状态:已汇总','概率继承:')){ if($rp.IndexOf($k) -lt 0){ Write-Error "REVIEW-MISSING $k" } }; if($rp -match '(?m)^状态:待派发\s*$'){ Write-Error 'STILL-PENDING' }; if($rp -match "(?<!\r)\n"){ Write-Error 'REVIEW-LF-ONLY' }; $rows=@($rp -split "`r?`n" | Where-Object { $_ -match '^\| R2-\d{2} ' }); if($rows.Count -lt 1){ Write-Error 'NO-R2-ROWS' }; foreach($row in $rows){ if($row -notmatch '\| (阻断|非阻断) \|'){ Write-Error 'BAD-TRIAGE' }; if($row -notmatch '\| (修|不修) \|'){ Write-Error 'BAD-HANDLE' } }; $block=[regex]::Match($rp,'(?m)^第 2 轮阻断数:(\d+)'); if(-not $block.Success){ Write-Error 'NO-BLOCK-COUNT' }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^读者派发方式:orchestrator 子代理(4 组)'){ Write-Error 'NO-DISPATCH-MODE' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING-REVIEW", "REVIEW-MISSING", "STILL-PENDING", "REVIEW-LF-ONLY", "NO-R2-ROWS", "BAD-TRIAGE", "BAD-HANDLE", "NO-BLOCK-COUNT", "BLOCK-COUNT-MISMATCH", "NO-DISPATCH-MODE", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T2-OK"</fails_when>
</verify>
<acceptance_criteria>`10-53-READER-REVIEW.md` 的 `### 第 2 轮` 下有 4 个读者小节(Part 0–1 / 2–3 / 4 / 5)、`#### 汇总与分诊`、`R2-01` 起的逐条行(每条有 `阻断/非阻断`、理由、`修/不修`)、两个统计行、`状态:已汇总`、`概率继承:`(Round 1 概率继续有效,新增/重写章节由读者补概率);NOTES 写 `读者派发方式:orchestrator 子代理(4 组)`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link;本任务未改任何 `docs/` 正文。</acceptance_criteria>
<done>Round 2 已由 4 组独立读者完成并汇总分诊,正文未动。</done>
</task>
<task type="auto">
<name>Task 3: Round 2 修订(只修阻断问题,修订者收到 D-93 + 本轮结论)</name>
<files>docs/advanced/ii/ui/*.md, .planning/phases/10-docs-restructure/10-53-READER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 2 已写入 `第 2 轮阻断数:N` 与逐条分诊;`10-53-READER-REVIEW.md` 状态为 `已汇总`;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md(第 2 轮全部问题与分诊)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(D-93 口径、四个扩写小节的覆盖表)、被判定为阻断的篇目与章节</read_first>
<action>**只修 `是否阻断 = 阻断` 且 `处理 = 修` 的条目;非阻断一律不修,不得顺手改风格或补内容。**
1. **派发修订者**:按阻断条目涉及的篇目派发子代理;每个修订者必须同时收到:
- `10-53-READER-REVIEW.md` 中 `### 第 2 轮` 的对应阻断条目(位置 + 已知道什么 + 还缺什么);
- D-93 的四类要求(渲染树 / 事件 / 元素组件用法 / 示例后解释)与「不能只修列出的问题」的指令;
- 本计划的「只改阻断段落、不改其它内容、不改 demo/导览/侧边栏」约束。
2. **修订范围**:只改阻断条目指向的段落或该段所属小节;必要时补齐前置、定义术语、补步骤/import/入口、消除矛盾、补 D-93 缺失的模型/事件/组件解释。不得新增页面、不得删除页面、不得改 24 个 demo、不得改其它篇目的非阻断内容。
3. **记录**:在 `10-53-READER-REVIEW.md` 的 `### 第 2 轮` 下追加 `#### 第 2 轮修订`:
- 每条阻断一行 `R2-XX:已修 — <path>#<章节>:<改了什么>`,或 `R2-XX:不修 — <一句理由>`(只有用户/计划允许的阻断才可留;默认阻断都要修)。
- 末尾 `第 2 轮修订完成:阻断 N 条,已修 K 条,未修 N-K 条`。
4. **门禁**:修订后跑一次 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 与 `--check`;跑一次 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,要求 green、`build complete`、0 dead link;确认 25 篇 / 24 demo 不变。把结果追加到 NOTES 的 `## 10-53` 小节。
5. **不改写历史**:Round 2 读者原文与分诊表逐字保留,只在 `#### 第 2 轮修订` 下追加。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $r='.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md'; $rp=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $r)); if($rp -notmatch '(?m)^#### 第 2 轮修订'){ Write-Error 'NO-R2-REVISION' }; if($rp -notmatch '(?m)^第 2 轮修订完成:阻断 \d+ 条,已修 \d+ 条,未修 \d+ 条'){ Write-Error 'NO-R2-REVISION-SUMMARY' }; if($rp -match '(?m)^状态:待派发\s*$'){ Write-Error 'STILL-PENDING' }; if($rp -match "(?<!\r)\n"){ Write-Error 'REVIEW-LF-ONLY' }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '第 2 轮修订'){ Write-Error 'NOTES-NO-R2-REVISION' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($p in $md){ $t=[IO.File]::ReadAllText($p.FullName); if($t -match "(?<!\r)\n"){ Write-Error ("LF-ONLY "+$p.Name) } }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $built=@(Get-ChildItem -LiteralPath 'public/_docs/advanced/ii/ui' -Filter *.html -File -ErrorAction SilentlyContinue); if($built.Count -ne 25){ Write-Error ('PAGE-NOT-BUILT:'+$built.Count) }; 'T3-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-R2-REVISION", "NO-R2-REVISION-SUMMARY", "STILL-PENDING", "REVIEW-LF-ONLY", "NOTES-NO-R2-REVISION", "MD-COUNT", "DEMO-COUNT", "LF-ONLY", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>`10-53-READER-REVIEW.md` 有 `#### 第 2 轮修订` 与 `第 2 轮修订完成:阻断 N 条,已修 K 条,未修 N-K 条`;所有 `阻断 + 修` 条目都有 `已修` 记录;非阻断条目未被修改;NOTES 记录第 2 轮修订与门禁结果;25 篇 / 24 demo 不变;prettier 与构建 green、0 dead link、25 个 HTML;Round 2 原文与分诊表未被覆盖。</acceptance_criteria>
<done>Round 2 阻断问题已修并记录,构建通过。</done>
</task>
<task type="auto">
<name>Task 4: Round 3 复审(无阻断则跳过)或第 3 轮全新读者复审</name>
<files>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 已写入 `第 2 轮修订完成:…`;NOTES 有第 2 轮修订记录;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md(第 2 轮阻断数、修订记录)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-53` 基线、D-93 口径)、docs/.vitepress/config.ts(25 条顺序)</read_first>
<action>**本任务按 Round 2 的阻断数分支;只追加记录,不改写历史。**
**分支 A:第 2 轮阻断数为 0。**
1. 在 `10-53-READER-REVIEW.md` 追加 `### 第 3 轮`,正文写 `未执行:第 2 轮无阻断问题,按 D-91 连续一轮无阻断即结束。`
2. 在 NOTES 的 `## 10-53` 下写 `第 3 轮:未执行(第 2 轮无阻断)` 与 `读者循环:已完成(第 2 轮无阻断)`。
3. **立即结束本任务**,进入 Task 5 门禁;不派发 Round 3 读者。
**分支 B:第 2 轮阻断数 > 0(已修)。**
1. **派发全新读者**:由 orchestrator 重新派发 4 个读者(Part 0–1 / 2–3 / 4 / 5),使用新上下文;**不附第 2 轮问题清单**,只给读者人格、D-93 复述检查项、本组篇目与前置。不得复用第 2 轮读者上下文,不得单代理包办。
2. 读者约束与 Task 2 相同:只读 Markdown、不读源码、不做 live、只提问、不判断对错、不提方案。
3. 汇总到 `10-53-READER-REVIEW.md` 的 `### 第 3 轮`:4 个 `#### 读者 A–D` 小节 + `#### 汇总与分诊`(编号 `R3-01` 起,列与 Task 2 相同)+ `第 3 轮阻断数:N` / `第 3 轮非阻断数:M` + `概率继承:Round 1 的 178 行分节概率继续有效;本轮新增/重写章节由读者补「高 / 中 / 低 + 理由」`。
4. **若第 3 轮阻断数为 0**:追加 `第 3 轮修订:无需修订` 与 `读者循环:已完成(第 3 轮无阻断)`,进入 Task 5。
5. **若第 3 轮阻断数 > 0**:只修阻断条目,追加 `#### 第 3 轮修订`(`R3-XX:已修/不修 — …`);修完后**不再派第 4 轮**(D-91 上限 3 轮),写 `读者循环:停止(3 轮后仍有阻断)`,并只列受影响页面/章节(不列读者问题清单)。进入 Task 5 门禁。
6. 每轮修订后跑一次 prettier `--write` / `--check` 与构建,记录到 NOTES。
**无论哪个分支,都不得把读者记录交给用户,不得写进 docs 正文。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $r='.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md'; $rp=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $r)); if($rp.IndexOf('### 第 3 轮') -lt 0){ Write-Error 'NO-ROUND3-SECTION' }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $b2=[regex]::Match($rp,'(?m)^第 2 轮阻断数:(\d+)'); if(-not $b2.Success){ Write-Error 'NO-R2-BLOCK-COUNT' }; $r3=[regex]::Match($rp,'(?ms)^### 第 3 轮\s*\r?\n(.*?)(?=\r?\n### |\z)').Groups[1].Value; if($b2.Groups[1].Value -eq '0'){ if($rp -notmatch '未执行:第 2 轮无阻断问题'){ Write-Error 'ROUND3-NOT-SKIPPED' }; if($np -notmatch '读者循环:已完成(第 2 轮无阻断)'){ Write-Error 'NO-DONE-R2' } } else { foreach($k in @('#### 读者 A(Part 0–1)','#### 读者 B(Part 2–3)','#### 读者 C(Part 4)','#### 读者 D(Part 5)','#### 汇总与分诊','第 3 轮阻断数:','概率继承:')){ if($r3.IndexOf($k) -lt 0){ Write-Error "ROUND3-MISSING $k" } }; $rows=@($r3 -split "`r?`n" | Where-Object { $_ -match '^\| R3-\d{2} ' }); if($rows.Count -lt 1){ Write-Error 'NO-R3-ROWS' }; if($np -notmatch '读者循环:(已完成|停止)'){ Write-Error 'NO-LOOP-CONCLUSION' } }; if($rp -match "(?<!\r)\n"){ Write-Error 'REVIEW-LF-ONLY' }; if($rp -match '(?m)^### 第 4 轮'){ Write-Error 'ROUND4-NOT-ALLOWED' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-ROUND3-SECTION", "NO-R2-BLOCK-COUNT", "ROUND3-NOT-SKIPPED", "NO-DONE-R2", "ROUND3-MISSING", "NO-R3-ROWS", "NO-LOOP-CONCLUSION", "REVIEW-LF-ONLY", "ROUND4-NOT-ALLOWED", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T4-OK"</fails_when>
</verify>
<acceptance_criteria>第 2 轮阻断为 0 时:`### 第 3 轮` 写明未执行、NOTES 有 `读者循环:已完成(第 2 轮无阻断)`;第 2 轮有阻断时:`### 第 3 轮` 有 4 个读者小节、分诊表、`R3-01` 起行、阻断统计与 `概率继承:`,NOTES 有 `读者循环:已完成` 或 `读者循环:停止`;不存在 `### 第 4 轮`;25 篇 / 24 demo 不变;prettier 与构建 green、0 dead link。</acceptance_criteria>
<done>Round 3 已按分支执行或记录跳过,循环结论已写入。</done>
</task>
<task type="auto">
<name>Task 5: 最终门禁 + 循环结论 + 停止(不进入用户审阅)</name>
<files>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 4 已写入 `### 第 3 轮` 与循环结论(完成或停止);docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md(第 2/3 轮全部记录)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-53` 全部内容)、.planning/ROADMAP.md、.planning/STATE.md</read_first>
<action>**只校验、记录与停止;除记录文件外不改任何文件。**
1. **循环完整性**:Round 2 有 4 个读者组与分诊;Round 3 有内容或明确的「未执行」;轮次不超过 3;记录 append-only、无覆盖;`读者循环:已完成` 或 `读者循环:停止(3 轮后仍有阻断)` 存在。
2. **未交用户**:确认 `10-53-READER-REVIEW.md` 仅存在于 `.planning`,没有被复制到 `docs/`;NOTES 写明「记录不交给用户」;没有在 docs 正文写入读者问题清单。
3. **结构门禁**:25 篇 / 24 demo 不变;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个;25 篇 CRLF;无新增/删除页面。
4. **质量门禁**:`prettier --write` 后 `--check`;ESLint 0/0;`vue-tsc --noEmit -p docs/tsconfig.json` 的 `docs/` 路径 0 条 `error TS`(既有引擎报错只记录条数);构建 green、`build complete`、0 dead link。
5. **哈希门禁**:重算循环后 docs 快照哈希(25 篇 + 两份导览;算法与 Task 1 相同:相对路径排序、逐文件 SHA-256、`相对路径:hash` LF 连接、再 SHA-256),写入 NOTES;与 `循环前 docs 快照哈希` 比较:若不同,说明修订确实发生,并在 NOTES 记录第 2/3 轮修订涉及的篇目;若相同且第 2 轮阻断数 > 0,说明阻断未落到正文,报错。
6. **写 NOTES**:在 `## 10-53` 下追加 `### 10-53 最终门禁`:六类命令与结果、`docs/` 路径 0 类型错误、既有引擎报错条数、构建耗时、25 个 HTML、`循环后 docs 快照哈希`、`读者循环结论:…`、`记录归属:仅 .planning,未交给用户`。
7. **不越界**:未写 SUMMARY、未改 ROADMAP / STATE、未改其它计划与 POC 文件、未改 `packages*` / `src`、未 commit。
8. **停止**:写 `停止点:10-53 读者循环结束;不进入 10-54 用户审阅;不写 SUMMARY / ROADMAP / STATE;不 commit。` 后立即停止。**不要把读者问题清单或分诊表整理给用户。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $r='.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md'; $rp=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $r)); foreach($k in @('### 第 2 轮','### 第 3 轮','第 2 轮阻断数:')){ if($rp.IndexOf($k) -lt 0){ Write-Error "REVIEW-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); foreach($k in @('### 10-53 最终门禁','循环后 docs 快照哈希:','读者循环结论:','记录归属:仅 .planning,未交给用户','停止点:10-53 读者循环结束')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^循环后 docs 快照哈希:[0-9a-f]{64}'){ Write-Error 'NO-POST-SNAPSHOT' }; if($np -notmatch '(?m)^读者循环结论:(已完成|停止)'){ Write-Error 'NO-CONCLUSION' }; if($np -notmatch '(?m)^记录归属:仅 \.planning,未交给用户'){ Write-Error 'NO-OWNERSHIP' }; $b2=[regex]::Match($rp,'(?m)^第 2 轮阻断数:(\d+)'); if($b2.Success -and $b2.Groups[1].Value -ne '0'){ $pre=[regex]::Match($np,'(?m)^循环前 docs 快照哈希:([0-9a-f]{64})'); $post=[regex]::Match($np,'(?m)^循环后 docs 快照哈希:([0-9a-f]{64})'); if($pre.Success -and $post.Success -and $pre.Groups[1].Value -eq $post.Groups[1].Value){ Write-Error 'BLOCKING-NOT-APPLIED' } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($p in $md){ $t=[IO.File]::ReadAllText($p.FullName); if($t -match "(?<!\r)\n"){ Write-Error ("LF-ONLY "+$p.Name) } }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr=@($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $built=@(Get-ChildItem -LiteralPath 'public/_docs/advanced/ii/ui' -Filter *.html -File -ErrorAction SilentlyContinue); if($built.Count -ne 25){ Write-Error ('PAGE-NOT-BUILT:'+$built.Count) }; $roadText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md')); $roadHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($roadText))).Replace('-','').ToLower(); $mr=[regex]::Match($np,'(?m)^ROADMAP 全文哈希:([0-9a-f]{64})'); if($mr.Success -and $mr.Groups[1].Value -ne $roadHash){ Write-Error 'ROADMAP-MODIFIED' }; $stText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); $stHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($stText))).Replace('-','').ToLower(); $ms=[regex]::Match($np,'(?m)^STATE 全文哈希:([0-9a-f]{64})'); if($ms.Success -and $ms.Groups[1].Value -ne $stHash){ Write-Error 'STATE-MODIFIED' }; foreach($s in @('10-53-SUMMARY.md','10-54-SUMMARY.md')){ if(Test-Path -LiteralPath ('.planning/phases/10-docs-restructure/'+$s)){ Write-Error ('UNEXPECTED-SUMMARY:'+$s) } }; $inDocs=@(Get-ChildItem -LiteralPath 'docs' -Recurse -File -Filter '*READER-REVIEW*' -ErrorAction SilentlyContinue); if($inDocs.Count -gt 0){ Write-Error 'REVIEW-COPIED-TO-DOCS' }; 'T5-OK'</automated>
<fails_when>non-zero exit, or output contains "REVIEW-MISSING", "NOTES-MISSING", "NO-POST-SNAPSHOT", "NO-CONCLUSION", "NO-OWNERSHIP", "BLOCKING-NOT-APPLIED", "MD-COUNT", "DEMO-COUNT", "LF-ONLY", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "ROADMAP-MODIFIED", "STATE-MODIFIED", "UNEXPECTED-SUMMARY", "REVIEW-COPIED-TO-DOCS"; or output lacks "T5-OK"</fails_when>
</verify>
<acceptance_criteria>第 2/3 轮记录完整(4 组读者、分诊、修订、结论),不存在第 4 轮;NOTES 有 `### 10-53 最终门禁`、`循环后 docs 快照哈希`、`读者循环结论:已完成/停止`、`记录归属:仅 .planning,未交给用户`、`停止点:10-53 读者循环结束`;25 篇 / 24 demo / 25 HTML;prettier / ESLint 0/0 / `docs/` 路径 0 类型错误 / 构建 green + 0 dead link;docs 下没有 READER-REVIEW 副本;未创建 SUMMARY;ROADMAP / STATE 未被改;未 commit。</acceptance_criteria>
<done>读者循环已收口并停在用户审阅之前。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 写作者上下文 → 独立读者 | 读者不得继承写作者的实现知识;只读 Markdown |
| 读者 → 分诊 | 读者只提问;是否阻断由 D-91 口径判定,不按读者语气 |
| 分诊 → 正文修订 | 只修阻断条目;非阻断不得顺手改 |
| 读者记录 → 用户 | 记录只在 `.planning`,不交给用户、不写进 docs |
| 本计划 → 账本 | 不写 SUMMARY、不改 ROADMAP / STATE、不 commit |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-194 | Spoofing | 单代理包办全部篇目 / 写作者自审 | high | mitigate | Task 2 强制 4 组读者;Task 4 新上下文;记录必须出现 4 个读者小节 |
| T-10-195 | Tampering | 把设计偏好当阻断大改文档 | high | mitigate | 分诊表强制 `阻断/非阻断` + D-91 六类理由;只修 `阻断 + 修` |
| T-10-196 | Tampering | 修订只按问题清单、漏同类缺口 | high | mitigate | 修订者必须收到 D-93 + 本轮结论;每轮后派新读者复审 |
| T-10-197 | Repudiation | 复用上一轮问题清单冒充新审阅 | medium | mitigate | Round 3 明确不附上一轮清单;使用新上下文;记录轮次独立 |
| T-10-198 | Information Disclosure | 读者记录被交给用户 | high | mitigate | 记录只写 `.planning`;Task 5 检查 docs 下无副本;D-92 交给 10-54 执行 |
| T-10-199 | Tampering | 超过 3 轮或新增第 4 轮 | medium | mitigate | verify 断言无 `### 第 4 轮`;3 轮后停止并只列受影响页面 |
| T-10-200 | Repudiation | 越界写 SUMMARY / ROADMAP / STATE / commit | medium | mitigate | Task 5 校验哈希与 SUMMARY 不存在;不执行 commit |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 关卡门禁:Task 0 已获「可以执行」;10-49..10-52 均已写入停止点。
- 轮次门禁:Round 2 有 4 个读者组与分诊;Round 3 有内容或明确「未执行」;不存在第 4 轮;总计不超过 3 轮。
- 阻断门禁:分诊表每条有 `阻断/非阻断` 与 D-91 理由;只修 `阻断 + 修`;每轮修订后派新读者复审(或第 2 轮无阻断跳过)。
- D-93 门禁:读者 prompt 含 D-93 复述检查;修订者收到 D-93;最终结论覆盖「渲染树 / 捕获冒泡 / 组件拆分与 props/slots/attrs」能否复述。
- 记录门禁:`10-53-READER-REVIEW.md` append-only、带 `### 第 2 轮` / `### 第 3 轮`、CRLF;不写入 docs;不交给用户。
- 范围门禁:只改阻断段落;25 篇 / 24 demo 不变;未改导览、侧边栏、`packages*` / `src`、其它计划与 POC 文件。
- 质量门禁:prettier `--check`;ESLint 0/0;`docs/` 路径 0 类型错误;构建 green + 0 dead link;25 个 HTML。
- 停止门禁:NOTES 有 `读者循环结论`、`记录归属`、`停止点:10-53 读者循环结束`;未创建 SUMMARY;ROADMAP / STATE 哈希未变;未 commit。
</verification>
<success_criteria>
- Round 2(以及必要时的 Round 3)由多个独立读者按 Part 完成,没有单代理包办、没有写作者自审、没有复用上一轮问题清单。
- 只修阻断性问题;修订者同时按 D-93 检查模型、事件与组件用法;每轮修订后重新复审。
- 读者记录完整、append-only、留在内部,不交给用户;循环在无阻断或 3 轮上限处停止。
- 25 篇 / 24 demo / 25 HTML 不变,门禁全绿,本计划停在用户审阅之前。
</success_criteria>
<output>
本计划**不写 SUMMARY**。完成后在对话中报告:读者循环结论(已完成 / 停止)、受影响页面/章节(仅当停止时)、轮次与阻断数、最终门禁结果;**不要向用户展示读者问题清单、分诊表或修订日志**。用户审阅由 `10-54-PLAN.md` 执行。
</output>
@@ -0,0 +1,238 @@
# Round 1(D-94)· 单读者
读者身份:刚读完中级教程、想给自己的魔塔做一套自定义界面的作者;只掌握基础 TS/JS(函数、对象、数组、少量模板语法),没写过 UI,不知道 canvas 是什么,也不会 Vue 组件写法;只能看这套文档,不能看源码,也没有人可以问。
## 阅读范围
### 先读的非目标文档(按 D-94 顺序)
说明:全部篇目都按顺序过了一遍标题与各级小节;标 ★ 的是逐段通读的篇目,其余为标题 + 开头正文通读(受 21:55 时限约束,未逐字读完全部数据端战斗细节)。
- `docs/intermediate/`
- ★ `code-basics.md`
- ★ `data-vs-render.md`
- ★ `src-tour.md`
- ★ `data-state-overview.md`
- ★ `data-plugins.md`
- ★ `map-structure.md`
- ★ `map-tiles.md`
- ★ `tile-store.md`
- ★ `hero-items.md`
- ★ `hero-equipment.md`
- ★ `hero-attribute.md`
- ★ `hooks.md`
- ★ `events.md`
- `flags.md`、`hero-location.md`、`replay-commands.md`
- `combat-overview.md`
- `enemy-aura.md`、`enemy-calculator.md`、`enemy-combat-script.md`、`enemy-final.md`、`enemy-map-damage.md`、`enemy-query.md`、`enemy-specials.md`、`enemy-status-hooks.md`
- ★ `docs/advanced/index.md`
- `docs/advanced/i/`
- ★ `index.md`
- `declarative-vs-imperative.md`、`plugin-system.md`、`saveable-content.md`、`replay-consistency.md`、`data-stores.md`、`hooks-in-depth.md`、`mover.md`、`face-handler.md`
- `docs/advanced/ii/`
- ★ `index.md`
- `static-vs-dynamic-tiles.md`、`point-and-tile-events.md`、`pathfinding.md`、`equipment-system.md`、`custom-replay-command.md`、`custom-range.md`、`adding-hero-attribute.md`、`adding-enemy-attribute.md`、`enemy-context-and-combat.md`
- `docs/advanced/iii/`
- ★ `index.md`
- `core-state.md`、`plugin-internals.md`、`event-system.md`、`passability-and-pathfinding.md`、`replay-internals.md`、`loading-system.md`
- 其它 `docs/`
- ★ `docs/poc/render-demo.md`
### 再读的目标 25 篇(按顺序)
1. `docs/advanced/ii/ui/ui-template.md`
2. `docs/advanced/ii/ui/container-and-coordinates.md`
3. `docs/advanced/ii/ui/basic-shapes.md`
4. `docs/advanced/ii/ui/curves-and-paths.md`
5. `docs/advanced/ii/ui/text.md`
6. `docs/advanced/ii/ui/image-and-texture.md`
7. `docs/advanced/ii/ui/layer-transform-performance.md`
8. `docs/advanced/ii/ui/reactivity.md`
9. `docs/advanced/ii/ui/events.md`
10. `docs/advanced/ii/ui/hotkey-in-ui.md`
11. `docs/advanced/ii/ui/conditional-and-list-rendering.md`
12. `docs/advanced/ii/ui/props.md`
13. `docs/advanced/ii/ui/component-tsx.md`
14. `docs/advanced/ii/ui/slots-and-attrs.md`
15. `docs/advanced/ii/ui/builtin-text-and-input.md`
16. `docs/advanced/ii/ui/builtin-list-and-containers.md`
17. `docs/advanced/ii/ui/ui-controller-and-stack.md`
18. `docs/advanced/ii/ui/replace-builtin-ui.md`
19. `docs/advanced/ii/ui/ui-performance.md`
20. `docs/advanced/ii/ui/inventory-example-1-skeleton.md`
21. `docs/advanced/ii/ui/inventory-example-2-grid.md`
22. `docs/advanced/ii/ui/inventory-example-3-detail.md`
23. `docs/advanced/ii/ui/inventory-example-4-scroll.md`
24. `docs/advanced/ii/ui/inventory-example-5-state.md`
25. `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`
## 逐篇提问
| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 |
| --- | --- | --- | --- | --- |
| 1 ui-template | 「一个最小 UI」 | UI 分四部分:Props 类型、props 列表、组件、`GameUI` 注册;三个基础 props 是 `controller`/`instance`/`state`;界面写在 render 返回的 TSX 里 | 我照抄这四段之后,第一步到底该在哪个文件里写 `open`、写哪一行,才能看见这个面板?文档只说「加入统一出口」,没有给我一条从新建文件到屏幕上出现的完整最短路径 | 新建 `src/client/ui/my-panel.tsx` 并导出后,能在游戏里打开并看到 480×320 的深色面板 |
| 1 ui-template | 「props 列表」与「边界」 | 少写 `controller`/`instance`/`state` 不报错但拿不到;基类要 `IGameUIPropsBase` 配 `DefaultProps` | 我只会基础 TS,看不懂 `satisfies SetupComponentOptions<MyPanelProps>` 需要写几个泛型;也不知道这三个 import 分别来自哪个包时我文件顶部是否已经存在 | 照抄后编辑器不报「找不到名称」,`props.state.sceneController` 能用 |
| 1 ui-template | 「运行效果」 | 文档站里有可点的 demo | 我自己的工程里这块画布在哪、`bootstrap.ts` 要不要动、TSX 编译是不是真的已经配好 | 不改任何构建配置就能跑起来 |
| 2 container-and-coordinates | 「坐标基准与画布」 | `loc` 的 480×320 是设计坐标,不是窗口像素;`renderer.width/height` 是设计尺寸;不要用 `innerWidth` | 我项目里画布的设计尺寸具体是多少?中级文档说 `src/constant.ts` 有 `RENDER_WIDTH`/`RENDER_HEIGHT` 但「一般不动」,我该读它还是读 `renderer.width` | 能按画布设计尺寸把面板居中,且不写死 480 |
| 2 container-and-coordinates | 「渲染树:根、容器与子元素」 | 树是「画布根 → UI 容器(控制器创建)→ 面板根(作者写)→ 元素」 | UI 容器自己占多大、放在画布哪里?面板根的 `[0,0]` 是相对 UI 容器,可我不知道 UI 容器是否铺满画布 | 面板根写 `[0,0,720,480]` 时正好从画布左上角开始 |
| 2 container-and-coordinates | 「容器三个职责」 | 容器给子元素局部坐标、做事件捕获单位、是缓存边界;容器不裁剪绘制但命中受矩形限制 | 我要做全屏背包,可画布只有 480×320 而设计稿 720×480;除了改坐标,是否允许把面板根设为画布尺寸再由画布整体缩放 | 面板不被裁掉一半,也不需要为每种窗口写一套坐标 |
| 3 basic-shapes | 「填充、描边与命中」 | `fill`/`stroke`/`strokeAndFill` 是模式开关,颜色在 `fillStyle`/`strokeStyle`;`actionStroke` 只按描边命中 | 我想做「只有边框可点」的按钮:是 `stroke` 加 `actionStroke`,还是 `fill`+`alpha=0`?两种做法在命中上的差别我复述不清 | 点击按钮内部能触发,而不是只有 1px 边框能点中 |
| 3 basic-shapes | 「图形作为界面零件」 | 槽位底板用 `g-rectr` 填充 + 一条内描边 | 表格里「内描边」没给写法:我不知道第二条 `g-rectr` 的 `loc` 要 inset 多少、圆角要不要同步减 | 能画出一圈不压住内容的选中边框 |
| 3 basic-shapes | 「边界与注意」 | `g-rect` 没有圆角,圆角用 `g-rectr`;默认颜色是浅灰 | 除了纯色,能不能给图形做渐变或贴图?文档只说「要显示图标用 image」 | 背景能用渐变或图片,而不是拼很多矩形 |
| 4 curves-and-paths | 「路径」 | `Path2D` 用元素局部坐标;只构造一次,不要在渲染函数里反复 new | 放在组件里时是放 `setup` 顶层、模块顶层,还是 render 外?如果形状要随 props 变化,什么时候重建 | 路径不重复创建,也不会因重渲染而缓存失效 |
| 4 curves-and-paths | 「圆角矩形」 | `circle` 1–4 项的映射;`ellipse` 每两项一组,长度只能 2/4/6/8 | `ellipse` 的 8 项到底哪一组对应哪个角,我复述不出来;「与 circle 相同」对我来说不够 | 能写出「左上、右下圆角,右上、左下直角」 |
| 4 curves-and-paths | 「三次贝塞尔」 | `curve` 数组顺序是起点 → cp1 → cp2 → 终点;长度写错不报错 | 贝塞尔没有 `loc`,那虚线、端点样式、`actionStroke` 这些还能不能照常写在它上面 | 能画一条虚线曲线,并且点不中空白区域 |
| 5 text | 「字体」 | `Font` 构造是位置参数 `(family, size, unit, weight, italic)`;默认 Verdana/16/400 | 我想用自己的字体文件或中文字体,`family` 该填什么?字体文件要放哪、要不要登记 | 面板里的中文能按我指定的字体显示 |
| 5 text | 「尺寸与居中」 | 文字宽高由测量决定;`anchorY=0.5` 用上升部/下降部居中;`width` 不裁剪 | 我想把文字在 66×66 的格子里垂直居中,但不知道测量出来的高度从哪个接口读,只能靠试 | 名称和数量在格子里居中,不靠手调 y |
| 5 text | 「为什么文字默认不缓存」 | 会变的文字不要开 `cache`;静态标题可以开 | 血量、金币这种每帧可能变的数字,是每帧都重新测量吗?我会不会把整块面板拖慢 | 高频数字不拖慢面板 |
| 6 image-and-texture | 「加载一张 PNG」 | 先 `new Image()`,`onload` 后再 `new Texture(image)`;加载期间用 `null` 占位 | 我的图片该放在哪个目录、`src` 写什么?示例给的是 `/assets/icons/potion.png`,但项目结构里没有讲素材目录 | 能把我自己的 PNG 显示出来 |
| 6 image-and-texture | 「从素材管理器取纹理」 | `props.state.materials.getImageByAlias('potion-red')` 返回 `ITexture \| null` | 别名是「素材配置、由编辑器维护」的,我不会用编辑器,能不能手写登记?写在哪个文件 | 不用编辑器也能登记并取到自己的图标 |
| 6 image-and-texture | 「像素图与高清缓存」 | `noanti` 关抗锯齿,像素图按整数倍放大;`hd` 只对开缓存的元素生效 | 我的图标 48×48 想显示 64×64,不是整数倍,除了改尺寸还有别的办法吗 | 图标放大后边缘仍然清晰 |
| 7 layer-transform-performance | 「缓存与脏更新」 | `container`/`custom` 默认缓存,`text`/`image`/`g-*` 默认不缓存;`nocache` 优先级更高 | 我的背包根容器里有一块每秒变的倒计时,是给根加 `nocache`,还是只把倒计时拆出去?我不知道哪种更省 | 倒计时变化不会重画整块面板 |
| 7 layer-transform-performance | 「显示开关」 | `hidden` 保留状态,三元销毁并重置;没有 DOM 布局流 | 隐藏的子树到底还参不参与命中遍历?本篇说 `noevent` 才是「退出遍历」,可 `hidden` 又「不参与命中」,我分不清性能差别 | 大量 hidden 面板时鼠标移动不卡 |
| 7 layer-transform-performance | 「filter 与 composite」 | 两者都存在,影响绘制不改布局与命中 | 具体能写哪些值?我只知道「模糊或灰度」,不知道字符串格式是 `blur(4px)` 还是别的 | 能给面板背后的地图做一层模糊 |
| 8 reactivity | 「ref:带 value 的盒子」 | TSX 里要写 `.value`;模板才自动解包;`reactive` 不能整体替换、解构会丢响应式 | 文档有的例子是 `defineComponent(() => ...)`,有的直接 `defineComponent(props => ...)` 用 `props.controller`,可我没看到 props 从哪声明;我该抄哪种 | 不声明 props 也能跑,或者能明确知道必须在哪声明 |
| 8 reactivity | 「什么时候会重渲染」 | 只有被渲染函数读过的响应式值变化才重渲染;普通数组不会 | 我的道具来自数据端的 `iterateItems()`(返回迭代器/Map),它不是 Vue 响应式;我该怎么把它变成 `ref` 并让界面跟着变 | 数据端加/减道具时网格自动刷新 |
| 8 reactivity | 「响应式与元素生命周期的边界」 | `hidden` 保留、三元卸载、`key` 变化视为新节点 | 这里举例提到 `v-if` 为 false 会卸载,但第 11 篇说 TSX 没有模板指令;我到底能不能写 `v-if` | 不误用导致状态意外丢失 |
| 9 events | 「事件名」 | `onClick`/`onDown`/`onUp`/`onMove`/`onEnter`/`onLeave`/`onWheel`,以及 `Capture` 版本 | `onMove` 写的是「在元素上移动」——指针在子元素上移动时,父容器的 `onMove` 会不会触发?做拖拽时我需要知道这一点 | 拖动面板时父容器能持续收到移动事件 |
| 9 events | 「事件对象」 | `offsetX/offsetY` 是元素局部坐标,`absoluteX/absoluteY` 是画布坐标;`type` 与 `buttons` 区分 | 触摸设备上 `onDown/onUp/onMove` 与鼠标是否同一套?我需不需要自己阻止页面滚动 | 手机上也能点击、拖动 |
| 9 events | 「cursor」 | `cursor` 跟随命中,`noevent`/`hidden` 时失效 | 能不能自定义光标图片,或者隐藏光标(做拖拽时) | 拖拽时换成抓取样式 |
| 10 hotkey-in-ui | 「注册新指令与分组」 | `addCommand`、`setGroup`、`KeyCode`、`HotkeyEmitMode`;`group` 只影响设置界面 | 内置指令的完整 id 列表在哪?默认表只给了 10 条,我想知道有没有「打开背包」这类现成指令 | 不重复注册、不撞 id |
| 10 hotkey-in-ui | 「按键与 UI 栈的关系」 | 按键走一条全局作用域栈,只有栈顶实现生效;`hidden` 不离开作用域 | 如果面板里有 `Input` 正在输入,按 Esc/方向键会不会被面板快捷键抢走?我该怎么让输入优先 | 输入文字时不会误关面板 |
| 10 hotkey-in-ui | 「useKey」 | 必须在 `setup` 中同步调用,返回作用域对象 | 我只会模板语法,不知道 `setup` 在 `defineComponent` 里对应哪一段;写在 `return () => ...` 之前就算 setup 吗 | 能拿到 `key` 并 `implement` |
| 11 conditional-and-list-rendering | 「key」 | 会增删/重排/带状态才需要 `key`;组件把 `key` 写在组件标签上 | 示例(四)里 `ItemGrid` 返回行数组,`key` 到底写行容器上还是写 `<ItemGrid>` 上?我不知道滚动重排时哪个才对 | 滚动/删除后列表项身份不错位 |
| 11 conditional-and-list-rendering | 「hidden 与三元」 | `hidden` 不绘制不命中但保留;三元真正卸载 | 大量长期 hidden 的面板仍占内存、仍被父级遍历——「仍被遍历」具体会不会让命中变慢,和第 19 篇的说法我串不起来 | 频繁开关的面板不卡 |
| 11 conditional-and-list-rendering | 「数据怎么变才会更新列表」 | `ref` 数组的 `push/splice/整体替换` 都会触发;`shallowRef` 只认整体替换 | 我的数组来自游戏状态而不是组件内部,我没有 `ref` 可 push;我该在数据端变化时怎么通知界面 | 数据端加道具后界面自动更新 |
| 12 props | 「组件怎么拿参数」 | Props 接口 + `props` 数组 + `emits`;`props` 数组列全才收得到 | 能不能给 props 写默认值?文档一律用 `props.x ?? 默认`,我不知道 `props` 数组里能不能写 `{ size: { default: 64 } }` | 不传 `size` 时格子是 64,且不写 `??` 也行 |
| 12 props | 「UI 的基础 props 是控制器注入的」 | `controller`/`instance`/`state` 由控制器注入;`open` 第二参是自己的 props | 我自己的 UI 想从外面传 `loc`、`title`,除了把键加进 `props` 数组,`open` 调用处还要写什么?`loc` 是不是也要自己列 | `props.loc` 在面板里拿得到 |
| 12 props | 「泛型顺序」 | Props、Emits、事件名联合、Slots;第二第三要配套 | 我用 `satisfies SetupComponentOptions<...>` 时,示例有时只给一个泛型、有时给三个;少写会不会让 `emit` 失效 | `emit('select', id)` 有类型检查 |
| 13 component-tsx | 「组件如何映射成一棵子树」 | 组件不产生节点,根元素才是父树里的挂载点;多个根会成为同父级多个子元素 | 多根组件时 `attrs` 自动透传到哪个根?又该怎么安排坐标?文档只说「自己安排 `loc` 与 `zIndex`」 | 多根组件不会叠在一起或丢属性 |
| 13 component-tsx | 「生命周期与渲染树」 | `onMounted` 在挂载后、`onUnmounted` 在卸载后;必须在 setup 内同步调用 | 我要在面板打开时从数据端读勇士背包,应该放 `setup`、`onMounted` 还是 `watch`?文档只给了定时器例子 | 打开面板时拿到的是最新数据,不是空数组 |
| 13 component-tsx | 「expose、emit 与父组件拿子组件」 | `ref<CardExpose>()` 拿子组件暴露的方法,挂载前是 `undefined` | 普通容器用 `ref<Container>()`、组件用 `ref<CardExpose>()`,两种 `ref` 的 import 来源不同,我很容易混;有没有统一的判断方法 | 类型写对,调用前判空 |
| 14 slots-and-attrs | 「slot 解决什么问题」 | slot 在 TSX 里是函数,要 `slots.title?.()`;具名 slot 用对象传 | 用 `SetupComponentOptions` 时 `slots` 字段怎么写?示例为了演示改用了手写 `PanelOptions`,我不知道该抄哪一种 | 具名 slot 有类型检查,不写 `?.()` 会报错 |
| 14 slots-and-attrs | 「attrs」 | 未声明为 props/emits 的进 `attrs`;`inheritAttrs:false` 后手动 `{...attrs}` | 我给子组件传 `loc`,它自动落到根元素上时,`loc` 这种数组属性会自动生效吗?根是 `container` 时我需不需要再手动拆 | 子组件根容器的位置被父级传的 `loc` 改变 |
| 14 slots-and-attrs | 「组件边界上的事件与属性」 | 在 `emits` 里声明了 `click`,父级 `onClick` 就不再透传,必须子组件 `emit` | 我只想额外加一个 `onEnter`、不打算声明 emits,它会作为 attrs 透传到根元素并生效吗 | 悬停事件能透传到内部根元素 |
| 15 builtin-text-and-input | 「文本组件的用法与组合」 | `TextContent` 的 `width` 必填,`loc` 第三项会被覆盖;`autoHeight` 与固定高度二选一;`lineHeight` 是行间距不是行高 | `TextContent` 的字体、字号、颜色、行高怎么传?示例只给了 `fillStyle` 和 `lineHeight`,我不知道完整属性名 | 能调出和面板一致的正文样式 |
| 15 builtin-text-and-input | 「输入组件的受控边界」 | `v-model:value`,真实输入框覆盖在画布上,失焦后移除;`hide` 不会让它失焦 | 输入框聚焦时,面板的 Esc 快捷键会不会把面板关掉?我该怎么处理「输入优先」 | 输入名字时按 Esc 只取消输入,不关面板 |
| 15 builtin-text-and-input | 「特殊组件 InputBox」 | `getInput/getInputNumber` 返回 Promise;取消时 `getInput` 给 `''`、数字给 `NaN` | 我在普通子组件(只有 props,没有 `controller`)里想弹确认/输入框,怎么拿到 controller?文档示例都是在 UI 组件里 | 子组件也能弹一次输入框 |
| 16 builtin-list-and-containers | 「List:可选中的列表」 | 组件内部有选中值,初始取第一项;挂载后改 `selected` 不会让列表改选 | 我想在「切换分类」后用代码把选中重置到第一项(或指定项),该怎么做?文档说改绑定不行 | 换分类后左侧高亮同步 |
| 16 builtin-list-and-containers | 「ListPage」 | 左侧 `List` 自带 `Scroll`;右侧 slot 收到选中 id;`close` 只发事件 | 右侧详情内容长了要滚动时,是我自己在 slot 里塞 `Scroll`,还是 `ListPage` 已经给了?和「不要在 Scroll 里套 ListPage」怎么共存 | 右侧详情能独立滚动 |
| 16 builtin-list-and-containers | 「Scroll」 | 只对直接子元素做虚拟滚动;总长度取直接子元素最大底边 + `padEnd` | 如果每行高度不固定(描述长短不一),`Scroll` 还能正确算总长度吗?行高变化时我要通知它吗 | 动态行高下列表仍能滚到底 |
| 16 builtin-list-and-containers | 「弹窗与一次性提示」 | `getConfirm`/`getChoice` 通过 UI 栈打开,弹窗 `alwaysShow` | 弹窗打开时,面板的按键作用域和弹窗谁在上?按 Esc 会关弹窗还是关面板?文档只说按键走作用域栈,没说弹窗是否压作用域 | Esc 只关最上层弹窗 |
| 17 ui-controller-and-stack | 「场景 UI 与主 UI」 | 两个控制器都从 `props.state` 取,文档明确写「没有全局 `client`」 | 但第 1 篇「打开与关闭」写的是 `client.sceneController.open(...)`(在 `src/bootstrap.ts`),那里到底有没有 `client`?我在组件外启动时该用哪个 | 在 `bootstrap.ts` 里能打开场景 UI,不报 `client` undefined |
| 17 ui-controller-and-stack | 「栈策略」 | `lastOnly` 默认、`showAll`;栈模式下 `close` 会连带关闭上层 | 打开背包 → 打开设置 → 按 Esc 关设置后,背包会自动回来吗?默认策略下我需要自己再 `open` 一次吗 | 关设置后看到背包,而不是空画面 |
| 17 ui-controller-and-stack | 「背景的四个名字」 | `showBack`/`showingBack()` 读最终结果,`showBackground`/`hideBackground` 写用户设置,`setBackground` 换背景 UI | 我想给自己的面板加一层半透明黑底,是该用 `setBackground`,还是在面板里画一个 `g-rect`?两者在栈与点击上的差别我不知道 | 背景正确显示,切面板不闪,点击不被背景吞掉 |
| 17 ui-controller-and-stack | 「事件归属与生命周期」 | `setPropsBaseCreator` 每个实例每次渲染都调用,必须带回 `state` | 默认情况下游戏是不是已经设好了 creator?什么时候需要我自己设?我不知道正常项目里这行在哪 | 不改也能拿到 `props.state`;要改时知道放哪 |
| 18 replace-builtin-ui | 「替换步骤」 | 替换点只有两个:打开处与包装层;改 `openSettings` 入口会影响所有调用方 | 我要改 `src/client/ui/settings.tsx` 里 `openSettings` 的内部,这算不算文档反复警告的「改内置」?「内置 UI」与「内置包 packages」的界线我没分清 | 能安全替换设置界面,升级时不丢改动 |
| 18 replace-builtin-ui | 「可以替换哪些、分别影响什么」 | 存档类必须保留索引/自动存档/mode/校验回调/关闭后的 Promise 结果 | `mode`、`validate` 这些具体约定在哪篇讲?文档只说「必须保留」,我不知道原语义是什么 | 换掉存档界面后仍能存到正确槽位 |
| 18 replace-builtin-ui | 「替换步骤 第二步」 | 包装层要转发全部 props、attrs、slots 与 emits | 包装组件怎么写才能把所有 slots 原样转发?示例没有给包装层代码 | 包装后原界面的行为与事件都一致 |
| 18 replace-builtin-ui | 「风险与边界」 | 不要改 `packages`/`packages-user` 里的内置实现;一次只换一个界面 | 表格给了内置 UI 的文件名,但没有目录树;我连 `src/client/ui` 下有哪些文件、`index.ts` 长什么样都要现猜 | 能按表找到文件并只改打开处 |
| 19 ui-performance | 「性能问题先定位在哪一层」 | 六层症状表;先做减法再看差异 | 文档站没有真实游戏,我在自己的工程里怎么「录一段」?看浏览器哪个面板、录什么操作 | 能定位是缓存、命中还是重渲染的问题 |
| 19 ui-performance | 「缓存」 | 结构复杂、内容稳定才缓存;过大的子树不该缓存 | 我的背包面板 720×480 接近全屏,开缓存算不算「过大」?文档没有给可判断的阈值 | 不会因为开缓存反而更卡 |
| 19 ui-performance | 「命中与事件」 | 装饰层加 `noevent`,减少全屏遮罩;每个遮罩都会参与命中遍历 | 我的面板底图是一张全屏 `image`,加 `noevent` 后点击落到哪?面板根没有 `onClick`,会不会穿透到地图触发移动 | 点面板空白处不会让勇士走路 |
| 19 ui-performance | 「观测与验证」 | 一次只改一个开关;用最坏数据测 | 「长帧」多少毫秒算长?目标帧率是多少?我不知道该拿什么标准判断有没有问题 | 能判断优化是否真的有效 |
| 20 inventory-1-skeleton | 「骨架在渲染树里的位置」 | 设计稿 720×480;面板主体 `[30,30,660,420]`;左右区域与操作条坐标 | 文档站画布是 480×320,720×480 会超出不可见;如果我的游戏画布也是 480×320,我该整体缩小坐标还是缩放面板根 | 打开后能看到完整面板,而不是只看到左上角 |
| 20 inventory-1-skeleton | 「组件与文件怎么分」 | 五个文件与各自 props;只有 `InventoryPanel` 被 `GameUI` 注册 | 我不知道现在的 `src/client/ui/index.ts` 里有什么;加一行 `export *` 会不会和已有导出重名 | 加导出后不覆盖、不冲突 |
| 20 inventory-1-skeleton | 「打开它」 | 三个入口:场景、当前控制器、主 UI 栈 | 示例只说「从某处打开」,没说我游戏里第一下该点哪里。我要加工具栏按钮还是快捷键?对应文件没给 | 能在游戏里真正触发打开 |
| 21 inventory-2-grid | 「ItemCell」 | 格子无内部状态,`selected` 由父传,点击只 `emit('select', id)` | 示例格子用 `g-rectr` + 文字,没有图标。我想加真实道具图标,`image` 该放在描边下还是上、要不要 `noevent` | 图标显示正确,点击仍由格子底板接收 |
| 21 inventory-2-grid | 「ItemGrid」 | 根容器 `400×280`;`cellSize=66`、`gap=8`;定位容器与格子同尺寸 | 如果道具数量不是 5 的倍数,最后一行不足 5 个,定位容器会不会用默认 200×200 盖住?示例(二)里行容器还没出现 | 最后一行不遮挡、不越界 |
| 21 inventory-2-grid | 「数据如何进入网格」 | 面板持有 `items: ref<Item[]>`,子组件收 `items.value` | 这是假数据;真实背包是 `state.hero.items.iterateItems()`,我不知道怎么从迭代器映射成 `Item[]`、怎么保持响应式 | 网格显示真实道具和数量 |
| 21 inventory-2-grid | 「点击如何上报」 | 三层 `emit`;`ItemCell → ItemGrid → InventoryPanel` | 表格里写 `onSelect` 是 props,正文又说 `emits: ['select']`;父级到底写 `onSelect` 还是 `@select`,我按哪个抄 | 事件链能编译、点击能选中 |
| 22 inventory-3-detail | 「详情区的树结构」 | 详情根 `196×280`;两个 `hidden` 容器切换提示与内容;描述用 `TextContent` | 两个 `hidden` 容器没写 `loc`,默认 200×200。显示时它会不会盖住下面 `[16,236,164,28]` 的「取消选择」按钮并吞掉点击 | 取消选择按钮始终可点 |
| 22 inventory-3-detail | 「ItemDetail」 | `item: Item \| null`;`TextContent` 的 `width=164`、`autoHeight` | 描述变长时 `TextContent` 高度会增,但按钮是绝对坐标 `y=236`,不会自动让位。怎么让按钮跟着下移,或者怎么限制描述区高度 | 长描述不压住按钮 |
| 22 inventory-3-detail | 「空态与边界」 | 三种空态;选中项被删除要把 `selectedId` 写回 `null` | 「删除道具」的入口在示例里没有(示例五只减数量),我不知道删除后 `selectedId` 该在哪一步清 | 删除后右侧回到「请选择道具」 |
| 23 inventory-4-scroll | 「Scroll 在渲染树里的位置」 | 视口 `372×244`;左侧区域 400 宽,右侧 28 是滚动条与内边距;行距 74 | 滚动条宽度是固定的 28 吗?换主题、换缩放或不同 DPI 后,我还按 372 算吗 | 内容不被滚动条压住,换设备也不偏 |
| 23 inventory-4-scroll | 「数据与选中态如何穿过滚动层」 | 组件不产生节点,`ItemGrid` 返回行数组,行数组成为 `Scroll` 的直接子元素 | `<Scroll><ItemGrid/></Scroll>` 里 `Scroll` 怎么知道拿到的是 5 个行容器而不是一个组件节点?我理解「组件不是节点」,但不确定 `Scroll` 是否会先看到组件边界 | 虚拟滚动真的按行生效 |
| 23 inventory-4-scroll | 「滚动与事件」 | `Scroll` 在捕获阶段把滚动偏移加回事件坐标;滚轮由 `Scroll` 处理 | 滚轮在格子上滚动时,会不会同时触发格子的 `onWheel` 或面板其它滚动容器 | 只滚左侧列表,不会带动别处 |
| 23 inventory-4-scroll | 「为什么不用 ListPage」 | `ListPage` 是单列文本列表,装不下 5 列网格 | 那我如果想让「左网格 + 右详情」按窗口宽度自适应(比如窄屏上下排),有没有现成组件?没有的话分栏比例要自己算吗 | 自己的分栏在缩放时稳定 |
| 24 inventory-5-state | 「状态放在 InventoryPanel」 | 面板持有 `items/selectedId/equippedId/hint`;派生用 `computed`,副作用用 `watch` | 这些全是假数据。我要把「装备」接到真实勇士(`state.hero.equip.equip(uid, slot)`)该写在哪?示例没提真实数据 | 点「装备」真的改变游戏里的装备槽 |
| 24 inventory-5-state | 「使用」 | `item.count -= 1`;数量为 0 时 `canUse` 失效 | 真实使用道具要走 `state.hero.items.useItem(...)`,还会触发道具效果;示例手改 `count`,我不知道该照哪个 | 点「使用」会消耗道具并触发效果 |
| 24 inventory-5-state | 「已装备的格子」 | 接口、`props` 数组、渲染三处一起改;`equippedId` 是单个 id | `equippedId` 是面板本地状态;面板关闭再打开就从 `null` 开始,读档后也不会恢复。它应该存哪、要不要进存档 | 重开面板后仍显示已装备 |
| 24 inventory-5-state | 「键盘收口」 | `useKey` 在 setup 调用;`@common/exit` 默认 Esc/X;三条关闭路径统一 | 面板里有 `Input` 正在输入时,Esc 会不会先被 `@common/exit` 拿走?示例没有输入框,我不知道怎么避免 | 输入时 Esc 只退出编辑 |
| 25 inventory-6-animation-and-register | 「动画作用在树的哪一层」 | 用 `requestAnimationFrame` 改 `alpha`,`onUnmounted` 里 `cancelAnimationFrame`;描边加 `noevent` | 文档说仓库有 `transitioned`/`transitionedColor`,返回值可空、要判空,但不给签名与用法。我不知道什么时候该用它、什么时候像本篇手写 raf | 能做渐变动画,且不用猜 API |
| 25 inventory-6-animation-and-register | 「最终组装与契约核对」 | 外层画布根 + 面板根,两层 `loc` 相同;「实际代码用 `hidden` 控制开合」 | 这个 `hidden` 变量是谁设的?面板组件自己持有,还是控制器根据实例隐藏状态注入?示例骨架里没有它 | 打开/关闭时显隐正确,不手写重复状态 |
| 25 inventory-6-animation-and-register | 「注册与打开」 | `new GameUI('inventory-panel', InventoryPanel)`;`index.ts` 统一导出;`mainUIController.open(InventoryUI, {})` | 注册只是声明 UI。我想给背包加一个工具栏按钮、再绑一个快捷键(比如 T),还要改哪几个地方?文档没有把这条链路串起来 | 能按按钮或按键打开背包 |
| 25 inventory-6-animation-and-register | 「最终验证清单」 | 8 项验证;「再次打开回到初始状态:未选中、滚动在顶部」 | 但第 23 篇说 `hide` 会保留滚动位置、只有 `close` 才回到顶部。我该用 `hide` 还是 `close` 来「再次打开」?两种行为的预期不同 | 我选的方式对应清单里的预期,不会互相矛盾 |
## D-93 复述检查(渲染树 / 事件 / 组件)
### 渲染树
我能复述的部分:
- 一棵树:画布根 → UI 容器(控制器创建)→ 面板根(作者写)→ 区域容器 → 叶子元素;每多一层,坐标系重新平移一次。
- 组件不产生节点;组件的根元素才是父树里的挂载点,多个根就是同父级的多个子元素。
- 容器有三个职责:局部坐标系(子元素 x/y 相对父容器左上角)、事件捕获单位(命中从根向里、父容器先接)、排序与缓存边界(兄弟按 `zIndex` 排序,容器默认缓存)。
- `zIndex` 只在同一父级兄弟间比较;绘制从小到大,命中从大到小。
- `hidden` 不绘制不命中但保留实例与状态;`noevent` 仍绘制但整棵子树跳过命中;容器不裁剪绘制但命中受自身矩形限制。
- 重渲染是组件级、patch 是元素级;三元/`key` 变化才会销毁重建。
我复述不出的地方:
- UI 容器自己的位置与尺寸是谁定的、是否铺满画布;面板根的 `[0,0]` 相对 UI 容器,但 UI 容器的 `loc` 全套文档没有给。
- 背景实例在树上的具体落点(只说 `zIndex 0`、`alwaysShow`,没说它在 UI 容器的哪个位置、和背景 UI 的根元素关系)。
- `template`、`custom`、`container-custom` 三者各自的节点语义与尺寸来源:只知道 `custom` 自绘、`template` 是内部容器标签,但不知道作者什么时候会看到它们。
- 「容器默认缓存」与「文字默认不缓存」同时成立时,父容器缓存里嵌文字,脏标记如何只在文字变化时避免重画整块——机制我背得出,但实际代码里怎么判断「这块该 nocache」我复述不出操作步骤。
### 事件
我能复述的部分:
- 命中:从画布根开始,每一层按 `zIndex` 从大到小检查子元素;同值后加入的先检查;图形按几何轮廓(`actionStroke` 只按描边);命中即停,不会分叉到同级其它元素。
- 捕获:根 → 命中元素,父容器先收到 `onClickCapture`;冒泡:命中元素 → 根,子元素先收到 `onClick`。
- 完整顺序:根捕获 → 父捕获 → 命中元素捕获 → 命中元素冒泡 → 父冒泡 → 根冒泡;同级其它元素不出现。
- `stopPropagation()` 在捕获阶段会同时截断内层捕获与整段冒泡,在冒泡阶段只截断向外;它不阻止同一元素上同事件名的其它监听器,也不阻止浏览器默认行为。
- `enter`/`leave` 不走普通冒泡,由根维护的悬停集合做差集:先 `leave` 后 `enter`;父容器在子元素间移动时一直留在集合里,所以不闪。
- `offsetX/offsetY` 是当前元素局部坐标,经过变换会反算;`absoluteX/absoluteY` 是画布坐标;同一元素捕获与冒泡复用同一事件对象,不同层各自计算。
- `noevent` 作用于整棵子树;`hidden` 连绘制一起跳过;`cursor` 跟随命中。
我复述不出的地方:
- `onMove` 的触发范围:只在指针位于该元素自身几何内时触发,还是位于其子树内也算?拖拽时父容器能不能一直收到 `onMove`。
- 滚动容器(`Scroll`)在捕获阶段补滚动偏移——这算事件系统的一部分还是组件自己的事?如果我自己写滚动,需不需要也做同样的换算。
- 多指触摸时 `identifier` 与 `onClick` 的关系:文档说「按下与抬起标识对不上就不产生点击」,但没说两根手指分别操作两个元素时各自的目标怎么确定。
- UI 栈里多个面板同时可见(`showAll`)时,事件是否严格按渲染树兄弟层级命中,还是按栈顺序额外排序——文档说「按渲染树规则」,但栈的 `zIndex = i*5` 与面板内部 `zIndex` 的叠加关系我没有完全复述清楚。
### 组件(props / slots / attrs 与内置组件)
我能复述的部分:
- props 管线:父组件写属性 → 子组件 VNode props → 子组件 `props` 数组挑键 → 进 `setup` 的 `props`;没挑中的进 `attrs`,默认透传到根元素。
- `props` 数组漏写键 = 收不到,且不报错;键名必须 camelCase;`v-model:xxx` 对应 `xxx` + `onUpdate:xxx`,真正 props 名是 `xxx`。
- props 是响应式的,不能解构;默认值用 `props.x ?? 默认`,用 `computed` 才能跟随变化;不要给 props 赋值。
- `emits` 声明后,父级对应的 `onXxx` 不再透传,必须子组件 `emit`;`expose` 暴露方法,父级用 `ref` 拿,挂载前是 `undefined`。
- slot 在 TSX 里是函数,用 `slots.xxx?.()` 调用;具名 slot 用对象传;`SlotsType` 决定类型;slot 只决定结构,不决定数据。
- `attrs` 是响应式的;`inheritAttrs:false` 只关闭自动落根,仍可手动 `{...attrs}`;多根组件应设 `false` 并手动分配。
- UI = 能被 `GameUI` 打开、由 UI 栈管理:Props 同时继承 `IGameUIPropsBase` 与 `DefaultProps`,`props` 数组至少含 `controller`/`instance`/`state`,组件被 `new GameUI(...)` 注册;普通组件只需 `DefaultProps`。
- 内置组件:`TextContent`(按 `width` 折行、逐字、`autoHeight`)、`Textbox`(背景/标题/内边距)、`Input`(覆盖真实输入框、`v-model:value`)、`InputBox`/`getInput`;`List`(内部选中、`v-model:selected`)、`ListPage`(左列表右详情)、`Page`(页码从 0)、`Scroll`(直接子元素虚拟滚动)、`Selection`(只画框不接事件)、`ConfirmBox`/`Choices`。
我复述不出的地方:
- `DefaultProps` 对普通组件到底是「必须」还是「推荐」:第 12 篇写「普通组件只需继承 `DefaultProps`」,第 18 篇又说第 1 篇的「配 `DefaultProps`」是推荐写法、不是运行要求。我不知道不继承会失去什么。
- `SetupComponentOptions` 的 `slots` 字段与第四个泛型 `SlotsType` 怎么配合;示例为了演示 slots 改用 `PanelOptions`,我不知道正式写法。
- 内置组件的 `emits` 全名:`List` 同时发 `update` 与 `update:selected`,`Page` 发 `pageChange` 还有 `update:page`,哪些该用 `v-model`、哪些该手监听,我背不全。
- `TextContent` / `Textbox` / `Input` 的完整属性表:只给了常用子集,字体、颜色、行距、内边距的具体键名我无法确定。
- `attrs` 透传与元素属性名的对应:`loc` 是数组、`fillStyle` 是颜色,展开到内部元素时哪些会自动生效、哪些需要手动拆,我没法从文档推出统一规则。
## 跨篇问题(仅读者困惑,不写「前后不一致/写错了」)
1. **真实数据接不进来。** 25 篇的背包示例从头到尾用 `ref<Item[]>` 假数据,我读完了仍不知道:`state.hero.items.iterateItems()` 返回的 Map 怎么变成 `Item[]`,装备怎么接到 `state.hero.equip`,使用道具怎么走 `useItem`。作为刚开始做自定义界面的作者,这是我最大的空白。
2. **素材怎么登记。** 文档反复说 `winskin`、`icon`、素材别名「由编辑器维护」,但我没有编辑器知识;除了文档站自带的 demo,我不知道自己的一张 PNG 要放在哪、怎么变成 `getImageByAlias` 能取到的别名。
3. **组件外到底有没有 `client`。** 第 1 篇写 `client.sceneController.open(...)`(`src/bootstrap.ts`),第 17 篇明确说「没有全局 client,两个控制器都从 `props.state` 取」。我在组件外启动时该用哪一个,作为读者只能二选一,不敢猜。
4. **`v-if` 能不能用。** 第 8 篇与第 13 篇都拿 `v-if` 举例说明卸载,第 11 篇却说 TSX 里没有模板指令、条件用 `hidden`/三元。我只会一点点模板语法,看到 `v-if` 会本能想写。
5. **`IGameUIPropsBase` + `DefaultProps` 是硬要求吗。** 第 1 篇与第 13 篇说「必须/判定条件」,第 18 篇说「推荐、不是运行要求」。我不知道照哪个标准检查我的组件算不算 UI。
6. **画布尺寸我该按哪个数。** 文档站 480×320、背包示例 720×480、正文说以 `renderer.width/height` 为准、中级又提到 `src/constant.ts` 的 `RENDER_WIDTH/RENDER_HEIGHT`。作为新手,我不知道自己项目该把设计稿定成多少、以及在哪里读这个值。
7. **普通子组件拿不到 `controller`。** 文档建议子组件不要接收 `controller`,需要关闭就 `emit`;但 `getInput`/`getConfirm`/`getChoice` 都要 controller。我在「详情里点使用前确认」这种场景下,不知道该由面板统一弹窗再把结果传下去,还是子组件自己想办法拿 controller。
8. **`hidden` 的成本口径。** 第 7/11 篇说 `hidden` 保留状态、仍占内存、仍被父级遍历,第 19 篇把 `hidden` 当成性能首选;我不确定「大量 hidden 面板」到底会不会拖慢鼠标移动,还是只有 `noevent` 才能减少命中遍历。
9. **默认值处处是坑。** 元素默认 200×200、`loc` 可省宽高、`container` 默认缓存、`image` 默认不缓存、`Font` 默认 Verdana、`List` 的 `lineHeight` 默认 18、`TextContent` 的 `lineHeight` 是行间距默认 0。作为读者我记不住这么多默认值,也不知道哪些会直接影响命中或排版。
10. **`@user/client-base` 与 `@motajs/*` 的 import 该不该写。** 模板篇说「文件顶部通常已有这些引入,不用再粘」,中级代码基础也说片段省略 import、缺了再补;但我新建文件时并不知道哪个文件「顶部通常已有」,只能一个个试。
## 声明
未读源码:是
未修改任何文档:是
未读上一轮审阅记录:是
live 目视验证:未执行
@@ -0,0 +1,98 @@
# Round 2(D-94)· 单读者
## 阅读范围
### 先读的非目标文档(按顺序)
- `docs/intermediate/`:`code-basics.md`、`combat-overview.md`、`data-plugins.md`、`data-state-overview.md`、`data-vs-render.md`、`enemy-aura.md`、`enemy-calculator.md`、`enemy-combat-script.md`、`enemy-final.md`、`enemy-map-damage.md`、`enemy-query.md`、`enemy-specials.md`、`enemy-status-hooks.md`、`events.md`、`flags.md`、`hero-attribute.md`、`hero-equipment.md`、`hero-items.md`、`hero-location.md`、`hooks.md`、`map-structure.md`、`map-tiles.md`、`replay-commands.md`、`src-tour.md`、`tile-store.md`
- `docs/advanced/index.md`
- `docs/advanced/i/`:`index.md`、`declarative-vs-imperative.md`、`plugin-system.md`、`saveable-content.md`、`replay-consistency.md`、`data-stores.md`、`hooks-in-depth.md`、`mover.md`、`face-handler.md`
- `docs/advanced/ii/`:`index.md`、`custom-range.md`、`static-vs-dynamic-tiles.md`、`point-and-tile-events.md`、`equipment-system.md`、`custom-replay-command.md`、`pathfinding.md`、`adding-hero-attribute.md`、`adding-enemy-attribute.md`、`enemy-context-and-combat.md`(均排除 `ui/`)
- `docs/advanced/iii/`:`index.md`、`core-state.md`、`plugin-internals.md`、`event-system.md`、`passability-and-pathfinding.md`、`replay-internals.md`、`loading-system.md`
- 其它:`docs/poc/render-demo.md`
### 后读的 25 篇目标文档(按顺序)
1. `docs/advanced/ii/ui/ui-template.md`
2. `docs/advanced/ii/ui/container-and-coordinates.md`
3. `docs/advanced/ii/ui/basic-shapes.md`
4. `docs/advanced/ii/ui/curves-and-paths.md`
5. `docs/advanced/ii/ui/text.md`
6. `docs/advanced/ii/ui/image-and-texture.md`
7. `docs/advanced/ii/ui/layer-transform-performance.md`
8. `docs/advanced/ii/ui/reactivity.md`
9. `docs/advanced/ii/ui/events.md`
10. `docs/advanced/ii/ui/hotkey-in-ui.md`
11. `docs/advanced/ii/ui/conditional-and-list-rendering.md`
12. `docs/advanced/ii/ui/props.md`
13. `docs/advanced/ii/ui/component-tsx.md`
14. `docs/advanced/ii/ui/slots-and-attrs.md`
15. `docs/advanced/ii/ui/builtin-text-and-input.md`
16. `docs/advanced/ii/ui/builtin-list-and-containers.md`
17. `docs/advanced/ii/ui/ui-controller-and-stack.md`
18. `docs/advanced/ii/ui/replace-builtin-ui.md`
19. `docs/advanced/ii/ui/ui-performance.md`
20. `docs/advanced/ii/ui/inventory-example-1-skeleton.md`
21. `docs/advanced/ii/ui/inventory-example-2-grid.md`
22. `docs/advanced/ii/ui/inventory-example-3-detail.md`
23. `docs/advanced/ii/ui/inventory-example-4-scroll.md`
24. `docs/advanced/ii/ui/inventory-example-5-state.md`
25. `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`
## 逐篇提问
| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 |
| --- | --- | --- | --- | --- |
| 1 UI 通用模板 | 「一个最小 UI」「打开与关闭」「边界与注意」 | 一个 UI 由 Props 类型、props 列表、组件、`GameUI` 四部分组成;面板根 `container` 的 `[0,0]` 相对 UI 容器;`controller`、`instance`、`state` 必须写进 props 列表;打开时传 `GameUI` 对象而不是名字。 | 我第一次把模板放进 `src/client/ui/my-panel.tsx` 后,应该从哪里打开它?文档给了 `sceneController`、`mainUIController`、`props.controller` 三个入口,但独立文件里没有 `props`;`bootstrap.ts` 里的 `client` 又只存在于启动文件。我缺一个「此刻我人在哪里、该用哪个入口」的判断。 | 我会先在 `src/client/ui` 建文件并在 `index.ts` 导出;打开时可能选错控制器,看到面板开在场景层而不是主 UI 栈,或者因为拿不到 `props` 而无法打开。 |
| 2 容器与坐标 | 「渲染树」「坐标与变换」「loc 与锚点」「边界与注意」 | 画布根 → UI 容器(控制器创建)→ 面板根(作者写)→ 元素;子元素坐标相对父容器;锚点决定元素哪个点落在 `x/y`;`zIndex` 只在同一父级比较;容器不裁剪绘制,但命中受父容器矩形限制。 | 面板根写 `[0,0,480,320]` 时,它相对 UI 容器;但 UI 容器本身在哪里、多大、是否等于画布根、是否铺满,我在文档里没有拿到。没有这个尺寸,我无法判断面板会不会被画布裁掉,也无法自己算居中。 | 面板会出现在左上角一块;如果画布比 480×320 小,超出部分看不见;如果画布更大,它也不会自动居中。 |
| 3 基础图形 | 「填充、描边与命中」的组合表;「边界与注意」 | `g-rect`、`g-circle`、`g-ellipse`、`g-line` 的几何参数;`fill` / `stroke` / `strokeAndFill` 是模式开关,颜色在 `fillStyle` / `strokeStyle`;图形按几何轮廓命中;`actionStroke` 的命中宽度跟 `lineWidth`。 | 表里同时写 `fill={false}`、`stroke={false}` 时结果仍是「填充」;我想让矩形“完全不画但保留一个可点热区”或“完全不可见且不挡事件”时,不确定该用 `alpha={0}`、`noevent` 还是别的组合。 | 我会先画出填充矩形;想关闭填充时按表写 `fill={false}` 可能仍然看到填充,只能改用透明色或额外包一层。 |
| 4 曲线与路径 | 「路径与曲线的坐标基准」「路径在渲染树与命中中的位置」「圆角矩形」 | 贝塞尔没有 `loc`,点坐标相对父容器;`g-path` 的 `Path2D` 是元素局部坐标;元素自动取包围盒;路径按几何轮廓命中;`Path2D` 不能序列化进存档。 | 如果曲线/路径要随数据变化(例如选中项改变形状),应该在什么时机重建 `Path2D`?文档只说“不要在渲染函数里每次新建”,但没有给“数据变了以后怎么更新一个已有路径”的写法。旋转/缩放时,曲线围绕哪个点变换,也没有和锚点一起说明。 | 静态曲线能画出来;动态路径我可能每次渲染都重建,或者建了一次却永远不更新;旋转时的视觉中心也可能和我想的不一样。 |
| 5 文字 | 「尺寸与居中」「loc 与锚点」「边界与注意」 | `text` 只画一行,宽高由字体测量决定;`fillStyle` 默认白色;`Font` 构造参数顺序是 family/size/unit/weight;`anchorX={1}` 可右对齐数值;文字默认不缓存。 | 「尺寸与居中」的示例在 `loc` 里写了后两项 `0.5, 0.5`,又同时写了 `anchorX={0.5}` / `anchorY={0.5}`;正文说两种写法只写一种。我照抄时该删哪一处?另外,`width/height` 不会裁剪文字,我要固定占位、避免文字压住下面元素时,应该包一层什么尺寸的容器? | 我能让文字居中/右对齐;但复制示例可能依赖属性处理顺序,结果不稳定;固定占位时可能要反复试外层容器尺寸。 |
| 6 图片与最小纹理 | 「纹理从哪里来」「从素材管理器取纹理」「像素图与高清缓存」 | `image` 把纹理铺满自己的 `loc`;`Texture` 接受 canvas / ImageBitmap / Image;素材管理器 `getImageByAlias` / `getImage` 返回 `ITexture \| null`;像素图用 `noanti`;`hd` 只对开了缓存的元素生效。 | 示例里 `createCheckerTexture` 返回 `Texture`,素材管理器返回的是 `ITexture`;`<image image={...}>` 到底接受哪一个,两者是不是同一个类型?纹理“按自身生命周期处理”具体要调用什么;`ImageBitmap` 需不需要主动 `close()`,文档没有给。 | 我能画自己用 canvas 生成的纹理;从素材管理器取图时如果类型对不上,我不知道该不该转换;卸载后纹理是否释放也不确定。 |
| 7 层级、变换与性能 | 「变换」「缓存与脏更新」「边界与注意」 | `scale` 是 `[x,y]` 数组,`rotate` 用弧度,`alpha` 是 0–1;`zIndex` 同父级比较;`hidden` 保留状态,三元销毁;`container` 默认缓存,`nocache` 优先;`custom` 自绘改外部数据要手动触发更新。 | 我想让整个 720×480 面板适配不同画布尺寸时,应该改面板根的 `loc` 与内部布局,还是给根容器加 `scale`?文档只说不要用子元素 `scale` 去抵消父级,但没有给“整体缩放面板”的推荐做法。`custom` 自绘“主动触发一次更新”的 API 名字也没有出现。 | 我能做单个元素的缩放/旋转;整块面板适配时可能算错坐标或把命中一起缩掉;`custom` 改了外部数据后可能不重绘。 |
| 8 响应式 | 「ref」「什么时候会重渲染」「shallowRef 与 markRaw」「nextTick」 | TSX 里 `ref` 要写 `.value`;`reactive` 不能整体替换、解构会丢响应式;`computed` 惰性且缓存;`watch` 用于副作用;`nextTick` 只保证这一轮更新处理完,不保证画布已经绘制。 | 我想等“浏览器真正画完这一帧”再做后续动作时,文档说“再配合一帧的回调”,但没有给具体 API 或写法。用 `shallowRef` 装一个大数组时,每次都要替换 `.value`;那列表项的 `key`、`Scroll` 的滚动位置和子组件内部状态还能不能保持? | 计数器能正常更新;需要等画面时可能只等到 `nextTick` 而不是绘制完成;大列表优化后可能因为整体替换导致列表状态重置。 |
| 9 事件与交互 | 「事件对象」「stopPropagation」「enter 与 leave」「命中测试」 | 命中从根开始、`zIndex` 大优先、同值后加入的优先;捕获父 → 子,冒泡子 → 父;`stopPropagation` 不阻止同一元素同事件的其它监听器;`onEnter/onLeave` 由 hover 集合做差集;`offsetX/Y` 是元素局部,`absoluteX/Y` 是画布坐标。 | 我在父容器的冒泡回调里想知道“最初点中的是哪个子元素”,但文档说每个元素拿到的事件对象里 `target` 都是它自己,不是最初命中的元素。那我该读哪个字段才能拿到最初目标?另外,`MouseType.Left` 的数值是多少,`(ev.buttons & MouseType.Left) !== 0` 这种写法我无法从文档确认左键位是否成立。 | 点击换色、日志顺序能按文档跑;但“谁是最初目标”和左键判断我可能会写错,只能靠打印事件对象试。 |
| 10 按键与快捷键 | 「注册新指令与分组」「优先级与阻断」「默认按键」「按键与 UI 栈」 | `useKey` 必须在 setup 同步调用;`implement` 把指令接到回调;`addCommand` 注册默认键;`HotkeyEmitMode` 有 KeyUp/Once/Continuous;`priority`/`block` 只对抬起触发有效;只有栈顶作用域的实现会执行。 | 默认按键表里 `@common/exit` 和 `@ui/menu` 都默认 Escape。我按 Esc 时,同一次按键会匹配到两条指令;文档说 `priority` 与 `block` 比较的是同一次按键匹配到的多条指令,但没说这两条默认指令各自的优先级。我缺一个“按 Esc 到底关面板还是开菜单”的判断。 | 我在面板里 `implement('@common/exit', close)`,按 Esc 可能关闭面板,也可能同时触发菜单;如果两条都执行,我会看到面板关了又弹出菜单。 |
| 11 条件渲染与循环渲染 | 「hidden 与三元」「key」「数据怎么变才会更新列表」「列表项的事件与状态」 | `hidden` 保留实例/状态/监听,三元销毁并重置;`.map()` 生成元素数组;`key` 只在同一父级兄弟间唯一;`ref` 数组 `push/splice` 会触发,`shallowRef` 必须整体替换;列表项回调用闭包拿当前项。 | 列表项是组件时 `key` 写在组件标签上;但 `ItemGrid` 这种组件返回“行数组”时,行容器的 `key` 和格子的 `key` 分别写在哪一层?另外,用 `hidden` 保留面板时,里面的 `Input` 真实输入框和按键作用域是否仍然活跃(文档在按键篇说 `hidden` 不离开作用域,这一篇没提)? | 普通列表能增删/高亮;组件数组的 `key` 可能放错层;隐藏面板里可能仍然占着 Esc,输入框也可能没有失焦。 |
| 12 props | 「props 的完整管线」「默认值」「props 是响应式的」「UI 的基础 props」 | `props` 数组是运行时白名单,没声明的进 `attrs`;默认值用 `props.x ?? 默认`;`props` 是响应式的,不要解构;`computed` 里的默认值会跟着更新;UI 的 `controller/instance/state` 由控制器注入。 | 我把 `items.value` 作为 `items` prop 传给 `ItemGrid`,子组件拿到的是数组;父级改 `item.count -= 1` 时,子组件读 `props.item.count` 会自动更新吗?文档说 props 是响应式的,但没有明确“通过 prop 传下去的对象内部字段”是否仍被追踪。 | 简单值(`size`、`selected`)会更新;嵌套对象的 `count` 可能只在父级重新渲染时更新,详情/格子可能出现不同步。 |
| 13 组件(TSX) | 「组件如何映射成一棵子树」「一个完整组件的结构」「生命周期」「组件与 UI 的区别」 | 组件本身不产生节点,根元素才是父树里的挂载点;多个根节点会成为同一父级的多个子元素;`setup` 返回 render 函数;`onMounted/onUnmounted` 必须在 setup 同步调用;`expose` 只暴露必要方法;UI 要同时满足三个条件。 | 组件返回数组(如 `ItemGrid` 的行数组)时,父级传的未声明属性(`loc`、`onClick`)会落到哪?文档说多根节点应设 `inheritAttrs: false` 并手动决定落点,但 `ItemGrid` 这种“没有单一根元素”的组件,外层定位应该由谁接收? | 单根组件能正常挂载;数组根组件如果父级传 `loc`,可能没有唯一根元素可落,属性会丢或落到第一个节点。 |
| 14 slots 与 attrs | 「具名 slot」「slot 在渲染树里的位置」「attrs」「inheritAttrs」 | TSX 里 slot 是函数,要写 `slots.title?.()`;具名 slot 用对象传入,默认 slot 也写在对象里;slot 内容在父作用域求值,插入子组件根下;未声明属性进 `attrs`;声明了 `emits` 的 `onClick` 不再透传。 | slot 内容最终坐标相对子组件容器;但子组件根容器的尺寸/位置如何影响 slot 内容的布局?另外,`Field` 把 `attrs` 展开到内部 `<text>` 时,父级传的 `onClick` 会绑到 `text`;如果 `Field` 自己也想处理点击,两个 `onClick` 会不会叠加/如何区分? | 面板标题/内容能插入;slot 内容的位置可能受子组件根容器影响;事件归属可能变成内部 `text` 而不是 `Field`。 |
| 15 内置组件:文本与输入 | 「这些组件替你决定了什么」「Textbox」「Input 的受控边界」「InputBox」 | `TextContent` 的 `width` 必填,`loc` 第三项会被覆盖;`autoHeight` 跟内容;`Textbox` 有标题/背景/内边距;`Input` 用 `v-model:value`,失焦只移除真实输入框不移除值;`getInput` 取消返回空串,`getInputNumber` 返回 `NaN`。 | `Textbox` 的宽高到底来自 `width/height` 还是 `loc` 第三、四项?文档一处说“来自 width / height 或 loc 的第三、四项”,另一处示例又同时写 `width` 与 `loc` 宽高;我不知道只写 `loc`、不写 `width` 时正文会不会没有排版宽度。`hidden` 容器里的 `TextContent` 是否仍然测量/触发 `updateHeight`,也没有说明。 | 我能让长文折行、输入框受控;`Textbox` 尺寸可能不按我给的 `loc` 生效;隐藏的文本可能仍在后台测量。 |
| 16 内置组件:列表与容器 | 「List」「Scroll」「ListPage」「Page」「弹窗与一次性提示」 | `List` 内部有自己的选中值,初始取第一项;点击行会发 `update:selected`;`ListPage` 左列表右详情;`Page` 页码从 0 开始;`Scroll` 只对直接子元素做虚拟滚动;`ConfirmBox/Choices/InputBox` 是一次性弹窗。 | 我想在打开面板时程序化选中 `List` 的某一项(初始 `selectedId` 不是第一项),该用哪个接口?文档说挂载后改 `selected` 不会让列表改选,只能“让用户点击,或改用能驱动列表的交互”,但没有给具体写法。 | 我能让用户点击选中;如果初始选中不是第一项,左侧高亮和右侧详情会不一致,且我不知道怎么用代码修正。 |
| 17 UIController 与 UI 栈 | 「控制器、实例与栈」「背景」「栈策略」「事件归属与生命周期」 | `open` 返回实例,`close` 卸载,`hide/show` 只改可见性;`alwaysShow` 不被 `hide` 隐藏;`keep` 防止切换时背景闪;`lastOnly`/`showAll` 决定栈策略;`zIndex` 是 `i*5`;`active`、`showBack` 是引用值。 | `mainUIController.render()` 要放进主场景的哪个容器、那个容器在画布上的 `loc` 和尺寸是多少?文档说主 UI 不会自己找画布位置、面板位置由 `open` 参数决定,但我只看到 `InventoryPanel` 的 720×480 根容器,不知道它相对谁定位、会不会被主场景容器裁掉。 | 我能打开/关闭面板;但面板可能出现在主场景容器的左上角,尺寸/位置与画布不匹配,`hide` 后按键作用域还会保留。 |
| 18 修改 / 替换内置 UI | 「替换步骤」第二步、「风险与边界」 | 替换点是打开处或包装层;`openSettings` 是工具栏/快捷键/插件共用的入口;`loc` 由调用方在 `vBind` 里传;`@common/exit` 已注册,直接 `implement` 覆盖;存档界面返回值语义必须保留。 | 第 1 篇说 UI 的 Props 必须同时继承 `IGameUIPropsBase` 与 `DefaultProps`;这一篇的最小示例只继承 `IGameUIPropsBase`,并说 `DefaultProps` 只是类型提示、不是运行要求。我照哪一份写才能既通过类型检查,又让 `loc`、`hidden`、`zIndex` 正常?另外,我只读文档、不能看源码,无法搜索当前项目里所有 `openSettings` 调用方,缺一个入口清单。 | 我能替换设置面板;但 Props 基类可能少写;只改工具栏调用点时,快捷键/插件入口仍打开旧设置。 |
| 19 UI 系统性能与注意事项 | 「显示开关」「UI 栈」「缓存」「症状与排查」 | 缓存适合结构复杂、内容稳定的子树;`hidden` 保留元素/状态/监听/按键作用域,三元卸载;大量列表用 `Scroll` 平铺;装饰层加 `noevent`;性能要先测再改。 | 背包这种“关闭面板”动作,应该用 `close` 卸载,还是用 `hide` 保留?第 17 篇说“能 `hide/show` 就不重建”,这一篇说“长期不用、体积又大的子树用卸载”,我缺一个按“关闭背包”这个具体动作的选型。 | 我能按症状排查;关闭背包时可能为了保留滚动位置用 `hide`,但按键作用域和内存都还在;用 `close` 又可能每次重新创建。 |
| 20 示例(一)目标与骨架 | 「骨架在渲染树里的位置」「打开它」「边界与注意」 | 最终面板 720×480;根 `container` 下有背景、面板主体、标题、关闭按钮、左右占位;关闭归 `InventoryPanel`;状态归面板;`InventoryUI` 用 `GameUI` 注册;三个打开入口。 | 示例站画布是 480×320,720×480 面板会超出;文档说“先按画布尺寸调面板根,或整体缩放”,但没有说缩放由谁做、怎么居中、打开时 `loc` 传什么。我第一次验证应该用 `sceneController` 还是 `mainUIController`,也没有针对骨架的明确建议。 | 照抄 720×480 根容器后,在 480×320 画布里只能看到左上角一部分;我会不知道应该改根 `loc`、改内部布局,还是加 `scale`。 |
| 21 示例(二)道具网格 | 「ItemCell」「ItemGrid」「数据如何进入网格」「边界与注意」 | `Item` 只在 `item-grid.tsx` 定义一次;5 列、`cellSize=66`、`gap=8`;`ItemCell` 只接收 `item/selected/size`;`ItemGrid` 用 `computed` 算列数/尺寸;点击三层上报;`key=item.id`。 | `ItemCell` 的 `size` 是在 setup 里读一次 `props.size ?? 66`;文档说尺寸在面板生命周期内不变,若变化再改 `computed`。但我如果做窗口适配、列数或格子尺寸变化,`ItemCell` 不会跟着变。我缺一个“尺寸变化时哪些 props 要改成 computed/render 读取”的清单。 | 10 件道具能排出网格;缩放或改 `cellSize` 后,格子容器尺寸可能变了而 `ItemCell` 内部仍按旧尺寸画。 |
| 22 示例(三)详情区 | 「详情区的树结构」「ItemDetail」「空态与边界」 | `selectedId` 用 `ref<string \| null>(null)`;`selectedItem` 用 `computed` + `?? null`;提示和详情两块都用 `hidden` 切换;`TextContent width=164`、`autoHeight`;`clear` 只上报,父级写回 `null`。 | `ItemDetail` 里的提示容器和详情容器都没有写 `loc` 尺寸,只有子元素定位;它们默认 200×200,而详情区宽 196。文档没有解释这两个内部容器是否需要尺寸、默认尺寸会不会影响命中或布局。隐藏的 `TextContent` 是否仍然测量、会不会触发 `updateHeight`,也没有说明。 | 选中/取消能切换;内部容器的命中范围可能比详情区宽;隐藏文本可能仍然参与测量,长描述可能撑出高度。 |
| 23 示例(四)滚动与列表 | 「Scroll 在渲染树里的位置」「数据与选中态如何穿过滚动层」「滚动与事件」 | `Scroll` 只对直接子元素做虚拟滚动;`ItemGrid` 的根从单个 `container` 改成行数组,行成为 `Scroll` 的直接子元素;行 `key=row`,格子 `key=item.id`;`scrollTo` 收内容像素;`getScrollLength` 是内容总长减视口;`padEnd` 是像素。 | `Scroll` 判断“直接子元素”时,看的是渲染后的元素,还是它自己的 VNode children?`<ItemGrid>` 是一个组件 VNode,虽然文档说组件不产生节点,但我无法确认 `Scroll` 会不会只看到一个组件 VNode 而无法按行虚拟化。如果 `ItemGrid` 里再包一个根容器就会失效,那“组件返回数组”是唯一可行写法吗? | 40 件道具能滚动;如果 `Scroll` 读到的是组件 VNode 而不是行元素,虚拟滚动可能退化成整块;滚动条和行隐藏可能不工作。 |
| 24 示例(五)交互与状态 | 「状态放在 InventoryPanel」「状态变化如何反映到画面」「已装备的格子」「遮罩与 noevent」 | 面板持有 `items/selectedId/equippedId/hint`;`canEquip/canUse/isEquipped` 都是 `computed`;`use` 直接改 `item.count`;`watch` 只更新提示;`ActionBar` 只发 `equip/use/close`;`equipped` 是“当前选中是否已装备”;遮罩用 `noevent`。 | `use` 改的是 `selectedItem.value.count`,而 `ItemGrid` 收到的是 `items.value`、`ItemCell`/`ItemDetail` 收到的是 `item` 对象。文档说 `ref` 数组内部是深层响应式,但没有明确“通过 prop 传下去的对象内部字段”是否都被追踪。我担心详情和格子不会同时刷新。 | 使用后数量减一、按钮变淡;如果对象内部字段没有被追踪,可能出现提示更新了但格子数量没变,或者详情不刷新。 |
| 25 示例(六)动画、拆分与注册 | 「动画作用在树的哪一层」「最终组装与契约核对」「注册与打开」 | 动画只改 `pulse`/`hintAlpha` 两个响应式值,`onUnmounted` 里 `cancelAnimationFrame`;最终拆成五个文件;`InventoryUI` 在 `inventory-panel.tsx` 导出,`index.ts` 再导出;从 `mainUIController` 打开;验证清单覆盖选中/滚动/装备/使用/关闭/再次打开。 | 最终骨架里有两层同尺寸的 `container [0,0,720,480]`:外层放背景/遮罩,内层放面板内容。文档说“外层是画布根、里层是面板根”,但 `InventoryPanel` 组件返回的最外层应该就是面板根;我不确定哪一层接收 `hidden`/`zIndex` attrs,哪一层是 UI 实例的根。照抄多套一层会不会让坐标或栈出错? | 动画和面板能跑;但根层级可能多一层,`hidden`/`zIndex` 可能落到错误的容器,关闭/再次打开时状态和坐标可能不对。 |
## D-93 复述检查
- **渲染树**:画布根下是控制器创建的 UI 容器,再往下是作者写的面板根容器,面板根下才是各个元素。组件本身不产生节点,组件的根元素才是父树里的挂载点;返回多个根就是同一父级下多个子元素。容器决定子元素的局部坐标系、同父级兄弟的 `zIndex` 排序与缓存边界;容器不裁剪绘制,但命中受父容器矩形限制。`hidden` 保留元素与状态,只跳过绘制和命中;`noevent` 仍绘制但整棵子树跳过命中。
- **事件捕获/冒泡**:指针落下后从根开始按 `zIndex` 从大到小命中,同值取后加入的;图形按几何轮廓命中。命中后先捕获(根 → 命中元素),再冒泡(命中元素 → 根)。`stopPropagation` 在任一阶段截断传播,但不阻止同一元素同事件的其它监听器。`onEnter/onLeave` 不走普通冒泡,由根维护的 hover 集合做差集触发。`offsetX/Y` 是当前元素局部坐标,`absoluteX/Y` 是画布坐标。
- **组件 props/slots/attrs**:父组件写的属性先进入子组件 VNode props;只有子组件 `props` 数组里列出的键才进入 `setup(props)`,没列出的进入 `attrs`。`attrs` 默认透传到根元素,`inheritAttrs: false` 可关闭自动透传后再手动 `{...attrs}`。slot 在 TSX 里是函数,子组件用 `slots.default?.()` / `slots.title?.()` 调用;具名 slot 用对象传入,作用域 slot 由子组件把数据作为函数参数传给父组件的 slot 函数。UI 的 `controller/instance/state` 由控制器注入,必须写进 props 数组。
- **内置组件**:`TextContent` 负责按 `width` 折行、测量、打字机与 `showAll/retype/getHeight`;`Textbox` 在文本外加背景/标题/内边距/图标;`Input` 用真实 DOM 输入框覆盖画布,`v-model:value` 受控,失焦只移除输入框不移除值;`InputBox/getInput/getInputNumber` 是一次性弹窗,取消时 `getInput` 返回空串、`getInputNumber` 返回 `NaN`;`List` 管行布局、点击选中、选中光标与滚动,内部选中初值取第一项;`ListPage` 是左列表右详情;`Page` 管页码与箭头,索引从 0 开始;`Scroll` 只对直接子元素做虚拟滚动;`Selection` 只画选中框不接事件;`ConfirmBox/Choices` 通过 `getConfirm/getChoice` 返回结果,`getChoice` 没有内建取消分支。
## 跨篇问题(仅读者困惑)
1. **UI 的 Props 基类到底要不要 `DefaultProps`**:第 1 篇说 UI 必须同时继承 `IGameUIPropsBase` 与 `DefaultProps`;第 18 篇的最小示例只继承 `IGameUIPropsBase`,并说 `DefaultProps` 只是类型提示。我作为第一次写 UI 的人,不知道照哪一份写才不会让 `loc`、`hidden`、`zIndex` 的类型或 attrs 落点出问题。
2. **720×480 面板与 480×320 画布**:骨架篇和最终篇都按 720×480 写坐标,示例站画布是 480×320;文档说“先按画布调根或整体缩放”,但没有说缩放由控制器、面板根还是打开处负责,也没有给主 UI 容器的 `loc`。我无法判断面板是会被裁、被居中,还是应该自己算。
3. **关闭背包用 `close` 还是 `hide`**:UI 栈篇说能 `hide/show` 就不重建,性能篇说长期不用的大子树应卸载;按键篇说 `hidden` 不离开按键作用域,输入篇说 `hide` 不会让输入框失焦。我不知道“关闭背包”这个动作应该选哪一种,以及选完后滚动位置、按键、输入框分别是什么状态。
4. **`Scroll` 与“组件返回行数组”**:示例(四)依赖“组件本身不是节点、返回的行会成为 `Scroll` 直接子元素”。但我只读文档,无法确认 `Scroll` 是按渲染后的元素子节点还是按 VNode children 判断“直接子元素”;如果按后者,`<ItemGrid>` 这个组件标签会不会让它只看到一个组件 VNode。
5. **`Textbox` 的尺寸来源**:文本与输入篇一处说 `Textbox` 的宽高来自 `width/height` 或 `loc` 第三、四项,示例又同时写 `width` 与 `loc` 宽高;`TextContent` 则是 `width` 必填、`loc` 第三项被覆盖。我不确定只写 `loc` 时 `Textbox` 正文有没有排版宽度。
6. **`props` 传对象后内部字段的响应式**:props 篇说 props 是响应式的,响应式篇说 `ref` 数组内部是深层响应式;示例(五)又通过 `items.value` 把数组传给 `ItemGrid`,再逐项传给 `ItemCell`。我不确定在父级直接改 `item.count` 时,所有读过 `props.item.count` 的子组件是否都会更新,还是只有父级重新渲染时才更新。
7. **默认按键的重叠**:按键篇的默认按键表里 `@common/exit` 和 `@ui/menu` 都是 Escape;`priority`/`block` 只对抬起触发有效,但没有给这两条默认指令的优先级。我不知道按 Esc 时是只关面板、只开菜单,还是两条都执行。
8. **事件的最初目标**:事件篇说每个元素拿到的事件对象里 `target` 都是它自己,不是最初命中的元素;那父容器冒泡时想判断“最初点中的是哪个子元素”该读什么?文档没有给这个字段或替代做法。
## 声明
未读源码:是
未修改任何文档:是
未读上一轮审阅记录:是
live 目视验证:未执行
@@ -0,0 +1,243 @@
# Round 3(D-94)· 单读者
读者身份:刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。没写过 UI,不知道 canvas 是什么,不会 Vue 组件写法;只会基础 TS/JS、函数、对象、数组和一点模板语法。手里只有这套文档,不看源码,也没有人可以问。
## 阅读范围
### 非目标文档(先读,按顺序)
- `docs/intermediate/` 全部 `.md`:`code-basics.md`、`src-tour.md`、`data-vs-render.md`、`data-state-overview.md`、`data-plugins.md`、`map-structure.md`、`map-tiles.md`、`tile-store.md`、`combat-overview.md`、`enemy-aura.md`、`enemy-calculator.md`、`enemy-combat-script.md`、`enemy-final.md`、`enemy-map-damage.md`、`enemy-query.md`、`enemy-specials.md`、`enemy-status-hooks.md`、`events.md`、`flags.md`、`hooks.md`、`hero-attribute.md`、`hero-equipment.md`、`hero-items.md`、`hero-location.md`、`replay-commands.md`
- `docs/advanced/index.md`
- `docs/advanced/i/` 全部 `.md`:`index.md`、`declarative-vs-imperative.md`、`data-stores.md`、`hooks-in-depth.md`、`plugin-system.md`、`face-handler.md`、`mover.md`、`saveable-content.md`、`replay-consistency.md`
- `docs/advanced/ii/index.md`
- `docs/advanced/ii/` 下除 `ui/` 外的全部 `.md`:`custom-range.md`、`static-vs-dynamic-tiles.md`、`point-and-tile-events.md`、`pathfinding.md`、`equipment-system.md`、`custom-replay-command.md`、`adding-hero-attribute.md`、`adding-enemy-attribute.md`、`enemy-context-and-combat.md`
- `docs/advanced/iii/` 全部 `.md`:`index.md`、`core-state.md`、`event-system.md`、`loading-system.md`、`passability-and-pathfinding.md`、`plugin-internals.md`、`replay-internals.md`
- 其它:`docs/poc/render-demo.md`
### 目标文档(后读,25 篇,按顺序)
1. `docs/advanced/ii/ui/ui-template.md`
2. `docs/advanced/ii/ui/container-and-coordinates.md`
3. `docs/advanced/ii/ui/basic-shapes.md`
4. `docs/advanced/ii/ui/curves-and-paths.md`
5. `docs/advanced/ii/ui/text.md`
6. `docs/advanced/ii/ui/image-and-texture.md`
7. `docs/advanced/ii/ui/layer-transform-performance.md`
8. `docs/advanced/ii/ui/reactivity.md`
9. `docs/advanced/ii/ui/events.md`
10. `docs/advanced/ii/ui/hotkey-in-ui.md`
11. `docs/advanced/ii/ui/conditional-and-list-rendering.md`
12. `docs/advanced/ii/ui/props.md`
13. `docs/advanced/ii/ui/component-tsx.md`
14. `docs/advanced/ii/ui/slots-and-attrs.md`
15. `docs/advanced/ii/ui/builtin-text-and-input.md`
16. `docs/advanced/ii/ui/builtin-list-and-containers.md`
17. `docs/advanced/ii/ui/ui-controller-and-stack.md`
18. `docs/advanced/ii/ui/replace-builtin-ui.md`
19. `docs/advanced/ii/ui/ui-performance.md`
20. `docs/advanced/ii/ui/inventory-example-1-skeleton.md`
21. `docs/advanced/ii/ui/inventory-example-2-grid.md`
22. `docs/advanced/ii/ui/inventory-example-3-detail.md`
23. `docs/advanced/ii/ui/inventory-example-4-scroll.md`
24. `docs/advanced/ii/ui/inventory-example-5-state.md`
25. `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`
## 逐篇提问
| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 |
| --- | --- | --- | --- | --- |
| 1 `ui-template.md` | 「一个最小 UI」模板 | 四段:Props 类型、Props 列表(必须含 controller/instance/state)、defineComponent 里返回 render 函数、new GameUI 注册;container/g-rect/text 的用途 | 这一串 defineComponent(props 再返回函数)里,泛型、setup 参数、render 各段分别在做什么;哪一段能省、哪一段不能动,文档只给成品没拆开 | 原样抄进 `src/client/ui/my-panel.tsx` 并在 index 导出后,我以为就能在游戏里看到 480×320 深蓝面板;但下一步由谁调用 open,文档没给可照抄的入口 |
| 1 `ui-template.md` | 「文件放在哪里、怎么被用到」 | 文件放 `src/client/ui/<name>.tsx`、加入 `index.ts`;从 `bootstrap.ts` 或别的面板调用 open;client 不是全局变量 | 工程里 `src/client/ui/index.ts` 现在长什么样,以及第一次验证该把 open 写进哪个已有文件、哪一行;我没有源码,无法确认手里有没有那个变量 | 我预期复制文件、加导出一行、在某个已有文件 open 就能看到面板;找不到那个「某个已有文件」时会卡住 |
| 1 `ui-template.md` | 「GameUI 是一个对象,不是名字」 | open 传对象、名字不参与查找、重名不合并、用实例 key 区分多次打开 | key 在哪里读、长什么样;文档说用实例的 key 但没给读取示例,我不知道调试时怎么区分两次打开 | 我预期打开两次得到两个独立面板,但不知道在代码里怎么确认这是第一次那个 |
| 1 `ui-template.md` | 「三个基础 props」/「open 的第二个参数」 | controller/instance/state 由系统注入;第二个参数只放自己的 props,会被包装成响应式,父组件改它面板会更新 | 子组件能不能改 props.xxx 反向写回打开方;文档只说父改子更新,没说子改父 | 我预期 props 是只读的;如果可写,我担心误改打开方数据,但文档没有正面回答 |
| 1 `ui-template.md` | 「两条写法怎么选」 | TSX 由 Vue 管节点,元素层自己 appendChild/销毁,二者落到同一棵渲染树 | 元素层创建的 root 最后挂到哪里才算显示;示例只写到 appendChild,没有把 root 交给谁的那一步 | 我预期元素层写法也能显示,但走到最后一步会发现没有入口把 root 挂进 UI 容器 |
| 2 `container-and-coordinates.md` | 「loc 与锚点」 | loc 六元组顺序 x、y、w、h、anchorX、anchorY;宽高可省,默认 200×200;锚点决定元素哪个点落在 x/y 上 | 文档说两两一组要么都写、要么都不写,又说宽高可省;只写 x、y 两项是否合法,还是必须写全四项或六项 | 我预期只写两项会得到 200×200、左上角在坐标处的容器;但不确定默认尺寸会不会盖住邻居 |
| 2 `container-and-coordinates.md` | 「坐标与变换如何沿树传递」 | 父级平移/缩放/旋转复合到子级,锚点是变换中心;不要手算累加屏幕坐标 | 命中测试是否也按变换逆算;父容器放大 2 倍后,点视觉上的子元素位置,事件会不会正确落到子元素 | 我预期放大后仍能命中;但这一篇只讲绘制与坐标,命中要到第 9 篇才讲 |
| 2 `container-and-coordinates.md` | 「容器不裁剪绘制…」 | 容器不裁剪绘制、但命中受父容器矩形限制;0×0 容器会看得见点不到 | 父容器矩形是变换前的局部矩形还是变换后的屏幕矩形;父容器旋转后命中边界怎么算 | 我预期 0×0 容器点不到;但旋转父容器下的子元素命中是否仍按轴对齐矩形,我不确定 |
| 2 `container-and-coordinates.md` | 「坐标基准与画布」 | loc 是画布设计坐标,不是 CSS 像素;renderer.width/height 是设计尺寸,窗口缩放由客户端处理 | 真实项目里 renderer.width/height 是多少、示例站 480×320 与真实画布是否一致;文档只给了示例站数值 | 我预期按 renderer.width 居中就能适配;如果真实画布不是 480×320,我不知道该以哪个数值写死 |
| 2 `container-and-coordinates.md` | 「一个嵌套示例」元素层部分 | 元素层用 new Container、pos、size、appendChild 建立父子关系 | root 创建后由谁挂到画布;示例没有 mount 或 addChild 到渲染根的那一步 | 我预期这段代码能跑,但复制后只能得到一堆未挂载的对象 |
| 3 `basic-shapes.md` | 「四个图形」 | g-rect/g-circle/g-ellipse/g-line 的几何参数;圆默认中心锚点,矩形默认左上;线用端点而不是 loc | 圆和椭圆能不能也用 loc 定位;文档只示范 x/y/radius,我想统一用 loc 时不知道该不该这么写 | 我预期 g-circle 写 loc 不生效或语义不同;文档没有明确禁止,我不敢确定 |
| 3 `basic-shapes.md` | 「填充、描边与命中」 | fill/stroke/strokeAndFill 是模式开关,颜色在 fillStyle/strokeStyle;默认矩形填充、线描边、默认色 #ddd | strokeAndFill 与 fill 加 stroke 同时写时谁赢;表格说 strokeAndFill 优先,但漏写它只写 fill 和 stroke 时边框在内还是外 | 我预期按表格组合能得到确定结果;但三个开关照抄时容易记混顺序 |
| 3 `basic-shapes.md` | 「actionStroke」 | 只让描边命中、内部下穿,命中宽度等于 lineWidth,没有最小热区 | actionStroke 对 g-rectr 圆角矩形是否也按圆角描边命中,还是按普通矩形;这一篇只举了 g-rect | 我预期圆角矩形加 actionStroke 后点圆角外侧不命中;但圆角部分要到第 4 篇才讲 |
| 3 `basic-shapes.md` | 「图形作为界面零件」表 | 文字盖在按钮上会先命中文字,给文字 noevent 可让点击落到按钮底 | 文字默认会接事件是否意味着文字元素自带 onClick 才会接,还是只要在矩形里就会被命中;我没写过 UI,分不清可命中与绑了监听 | 我预期点文字时事件会冒泡到按钮底;如果文字没绑监听,事件是否还会以文字为目标,文档没说 |
| 3 `basic-shapes.md` | 「为什么矩形没有圆角」 | 圆角用 g-rectr,g-rect 加 radius 不生效也不报错 | g-rectr 的 circle 数组长度与角映射;这一篇只说第 4 篇讲,我照着写 circle 一个数时不知道它是半径还是别的 | 我预期一个数就是四角同半径;但不确定单位和上限 |
| 4 `curves-and-paths.md` | 「路径与曲线的坐标基准」 | 贝塞尔没有 loc、点坐标相对父容器、元素自动取包围盒;g-path 的 Path2D 坐标是元素局部坐标 | 自动取包围盒之后,元素的 x/y/w/h 还能不能读、能不能用来做锚点定位;文档说不要用 loc 挪它,但没说我怎么知道它占多大 | 我预期曲线画在父容器坐标处;但没法像矩形那样用 loc 精确对齐下一条线 |
| 4 `curves-and-paths.md` | 「路径」 | g-path 的 path 必须是 Path2D,moveTo/lineTo 组路径,路径只构造一次 | 在会随 props 变化的组件里,路径点变了要怎么重建 Path2D;文档只说渲染函数外构造一次,但我的点来自 props | 我预期 props 变了路径也要变;照文档放在渲染函数外则不会更新,我不知道该放哪 |
| 4 `curves-and-paths.md` | 「圆角矩形」 | circle 支持 1/2/3/4 项、ellipse 支持 2/4/6/8 项,角顺序左上、右上、右下、左下 | ellipse 的 0 值组怎么写才算直角;示例给两组 20 和两组 0,但我不确定 0 组是半径 0 还是不设圆角 | 我预期写 0 就是直角;但和 circle 的四项写法对照时容易混 |
| 4 `curves-and-paths.md` | 「路径在渲染树与命中中的位置」 | 路径按几何轮廓命中,画到 200×200 外仍可点,元素宽高只影响锚点与变换中心 | 路径超出父容器时,父容器命中矩形会不会把它挡住;文档说容器不裁剪绘制但命中受父容器矩形限制 | 我预期路径画到父容器外仍可见但点不到;这与路径画到元素默认 200×200 外仍可点是两层,我不确定哪层优先 |
| 5 `text.md` | 「尺寸与居中」 | 文字宽高由测量决定,给 width/height 不会裁剪;居中用 anchor 0.5;右对齐用 anchorX=1 | loc 的后两项写 0.5 与再写 anchorX/anchorY 0.5 两处都写时以哪个为准;这一篇自己又说只写一种,示例却两处都写 | 我照着示例抄会得到居中文字,但不知道删掉哪一处仍然正确;文档没有给出只写 loc 后两项或只写属性的单独版本 |
| 5 `text.md` | 「字体」 | new Font(family, size, unit, weight, italic) 是位置参数;Font.defaults/Font.clone 是对象形式;setDefaults 改全局默认 | addFallback 是实例方法还是静态方法,后备字体挂在哪个 Font 上;文档只说用 addFallback | 我预期能给一个 Font 加后备字体;但不知道调用形式,写不出来 |
| 5 `text.md` | 「一行文字」元素层部分 | new Text、pos、setText、setStyle(颜色、描边色)、setFont | 元素层怎么设描边宽度;TSX 有 strokeWidth,元素层只看到 setStyle 第二个参数是描边颜色,没有宽度入口 | 我预期元素层也能画带宽度描边的文字;但照现有 API 只能设颜色 |
| 5 `text.md` | 「为什么文字默认不缓存」 | 文字默认不缓存,静态标题可显式 cache,nocache 优先级更高 | 文字内容不变的判断标准是字符串不变还是测量结果不变;字号或字体变了但文字没变时缓存会不会失效 | 我预期改字体后缓存会重画;但文档没有说明缓存键包含哪些属性 |
| 5 `text.md` | 「不会自动换行」 | 单行 text 不换行,长文本用 TextContent,width 必填 | TextContent 的 width 与 loc 第三项冲突时以哪个为准;这一篇说具体在第 15 篇,我读到这里时还没有答案 | 我预期先读完第 15 篇才能决定;在此之前只能用多个 text 硬排 |
| 6 `image-and-texture.md` | 「图片元素与纹理」 | image 接收纹理对象,loc 决定显示大小;纹理被拉伸铺满;透明像素也算命中;图片是叶子元素 | image 的 image 属性类型是 Texture 还是 ITexture;素材管理器返回 ITexture,示例里 Texture 是类,两者能不能直接互换 | 我预期从 materials.getImageByAlias 取到的东西能直接传给 image;但类型对不上时不知道该不该 new Texture |
| 6 `image-and-texture.md` | 「纹理从哪里来」 | 可以用 canvas 构造 new Texture,纹理尺寸取图像源宽高;不要在渲染函数里重复创建 | Texture 从 @motajs/render 导入,但 ITexture 从哪导入、和 Texture 什么关系;文档没有给 ITexture 的导入路径 | 我预期写 ref 里装 Texture 或 null;如果素材管理器给的是 ITexture,这个 ref 类型就接不住 |
| 6 `image-and-texture.md` | 「加载一张 PNG」 | 先 new Image、等 onload 再 new Texture,用 null 表示未加载,加载完成写 ref | onMounted 里发起的加载在组件卸载后是否要取消;文档说不需要手动停止,如果 URL 很慢,卸载后 ref 还会不会被写 | 我预期卸载后写 ref 不报错也不重新显示;但文档只给了一句不会让已销毁的组件重新出现,我无法确认是否会泄漏请求 |
| 6 `image-and-texture.md` | 「从素材管理器取纹理」 | materials.getImageByAlias 返回 ITexture 或 null,取不到先走占位;普通子组件不要读 props.state,应在顶层取好再传 | ITexture 的公开成员有哪些(宽高?能否直接给 image?);文档没有列,只说用法与上一节完全一样 | 我预期把 ITexture 传下去就能画;但上一节的 Texture 是可构造类,我不确定两者是否同一类 |
| 6 `image-and-texture.md` | 「像素图与高清缓存」 | noanti 关抗锯齿、anti 开、hd 只对开了缓存的元素生效;像素图尽量整数倍放大 | anti 和 noanti 都不写时的默认值;文档只说 noanti 优先级高,但没给默认 | 我预期默认是抗锯齿;如果不是,我的像素图会先糊一次,需要知道默认才知道要不要显式写 |
| 7 `layer-transform-performance.md` | 「遮挡:zIndex」 | 同一父级按 zIndex 从小到大绘制、从大到小命中;同值按插入顺序;跨父级不能直接比 | zIndex 不写时的默认值;文档一直说值大的在上,但没给默认,多个元素都不写时我只能猜是 0 | 我预期都不写时按插入顺序;如果有默认非 0,我的层叠会与预期不同 |
| 7 `layer-transform-performance.md` | 「变换:scale、rotate 与 alpha」 | scale 必须是两个数的数组、rotate 用弧度、alpha 0 到 1,锚点是变换中心 | 能不能绕任意点旋转或缩放;只能改 anchor,但 anchor 是元素自身比例,不能设成任意像素点 | 我预期把按钮绕左上角旋转就设 anchor 0;想绕元素外一个点旋转时,文档没有入口 |
| 7 `layer-transform-performance.md` | 「缓存与脏更新」 | container 和 custom 默认缓存,text/image/template 与全部图形默认不缓存;nocache 优先;属性变化自动标脏沿父链上冒 | 缓存画布的默认分辨率与 hd 默认值;文档说 hd 控制高清,但没说默认是开还是关 | 我预期默认缓存是普通分辨率;如果默认高清,内存会比我预想大 |
| 7 `layer-transform-performance.md` | 「filter 与 composite」 | 它们接收画布滤镜字符串与混合模式,影响绘制不影响布局与命中 | 允许的取值列表;文档说取值很多、需要时再查对应取值,但没有链接或枚举名,我无法照抄一个可用的值 | 我预期写 CSS 风格的值能生效;但文档没有确认语法,我不敢写 |
| 7 `layer-transform-performance.md` | 「事件坐标与 noevent」 | offsetX/Y 是当前元素局部坐标、absoluteX/Y 是画布坐标,缩放旋转后会反算;noevent 跳过整个子树命中 | 父级 noevent 时,子元素自己再写 noevent 为 false 能不能恢复命中;文档说整个子树不参与命中 | 我预期不能恢复;但不知道有没有反向开关,照文档只能给每个子元素单独处理 |
| 8 `reactivity.md` | 「数据变化如何走到渲染树」 | 数据到组件渲染函数到新 VNode,再只 patch 变化的元素属性,下一帧重绘;重渲染是组件级,patch 是元素级 | 元素实例不重建是否意味着我放在模块顶层或 setup 里的普通变量会一直保留;文档举了滚动位置,但没说普通对象变量 | 我预期重渲染不会重置普通变量;如果是 setup 内每次执行都重新声明,我就分不清哪些会重置 |
| 8 `reactivity.md` | 「ref:带 value 的盒子」 | TSX 里读写都要 .value,忘记写会得到 object Object 且不更新;ref 可以包对象 | ref 从 vue 导入,但项目里是否已经装好 vue、新建文件时要不要改 package.json;文档默认模板工程已配置 | 我预期直接 import ref 就能用;如果项目没有显式依赖,我会在编辑器里看到找不到模块 |
| 8 `reactivity.md` | 「reactive:一整块对象」 | reactive 不能整体替换、解构会丢响应式、应逐字段改或用 toRefs | toRefs 的具体写法与返回类型;文档只说改用 toRefs,没给一行示例 | 我预期解构后还能用;但不知道 toRefs 之后是不是 ref、要不要 .value |
| 8 `reactivity.md` | 「什么时候用 shallowRef 与 markRaw」 | 大对象整体替换用 shallowRef、外部实例用 markRaw;纹理放进普通 ref 会被深层代理 | markRaw 与 shallowRef 一起用时先包哪个;素材管理器返回的纹理,我该 markRaw 还是 shallowRef | 我预期两种都能减少代理;但文档没有给组合写法,我怕包错导致不更新 |
| 8 `reactivity.md` | 「watch:副作用」 | watch 回调拿新值旧值、setup 内创建会自动停止、只读派生用 computed | watch 默认是浅层还是深层;监听一个 ref 内部对象的 count 时,该写 getter 还是直接传对象 | 我预期监听对象内部字段要写成 getter;文档示例只监听 ref 的 count,没有对象字段的例子 |
| 9 `events.md` | 「命中测试」 | 从根开始按 zIndex 大到小找第一个命中,同值后加入的先;容器按矩形、图形按几何;命中就停,不进兄弟 | 后加入在同 zIndex 时是否稳定,列表重排后会不会改变命中;文档说同值按插入顺序,但没说不写 zIndex 时列表重排的影响 | 我预期重叠按钮点最上面;如果两个都没写 zIndex,重排列表后可能点错,我不知道该不该显式给 zIndex |
| 9 `events.md` | 「事件名:on 加事件名」 | onClick/onDown/onUp/onMove/onEnter/onLeave/onWheel,捕获加 Capture;点击要求按下与抬起在同一元素 | 按下在子元素、抬起在父元素时,click 会不会在共同祖先上触发;文档只说同一元素才会产生 click | 我预期不会产生 click;如果同一元素指事件目标链上的共同元素,我就理解错了 |
| 9 `events.md` | 「事件对象」 | target 是当前处理事件的元素(每个元素拿到的是自己),offset 是局部坐标,absolute 是画布坐标,type 与 buttons 不同 | 最初命中的元素怎么拿;target 每个元素都是自己,那我在父容器里怎么知道点到的是哪个子元素 | 我预期用 ev.target 能拿到起点;按文档它会被改写,我需要另一个字段或方法,文档没给 |
| 9 `events.md` | 「事件对象」MouseType 示例 | type 是本次触发按键、buttons 是当前按住的所有键,判断左键点击看 type | MouseType.Left 能不能直接当位掩码用;示例写 buttons 与 MouseType.Left 做位与,但 MouseType 是按键种类枚举,不是位标志 | 我预期这段位运算能判断按住左键;如果枚举值不是 1、2、4,结果会错,我需要知道 buttons 的位定义 |
| 9 `events.md` | 「enter 与 leave 不走普通冒泡」 | enter/leave 由根维护的 hover 集合做差集,先 leave 后 enter;父容器在指针下时也在集合里 | noevent 的容器不进集合,那它的子元素即使能命中,enter/leave 还触发吗;文档说 noevent 整个子树不参与命中 | 我预期 noevent 容器及其子元素都没有 enter/leave;cursor 也失效,我不确定是否所有悬停效果都失效 |
| 10 `hotkey-in-ui.md` | 「useKey:拿到当前组件的作用域」 | useKey 必须在 setup 同步调用,返回当前组件的作用域,组件卸载自动移除;第二个参数 clearImpl 默认 true | 普通子组件(不是 UI)里怎么拿到 props.state.hotkey.system;文档说 useKey 在组件里用,但示例都默认有 props.state | 我预期子组件也能接按键;但子组件没有 props.state,我需要知道该由父级传 system 还是另有入口 |
| 10 `hotkey-in-ui.md` | 「注册新指令与分组」 | system.addCommand(id、name、选项)、props.state.hotkey.setGroup、key.implement;id 带命名空间 | addCommand 返回的对象类型是什么、setGroup 要的指令对象数组是不是就是这些返回值;文档只写把 refresh 放进去 | 我预期把 refresh 直接放进 setGroup 就能在设置界面看到;如果它返回的不是指令对象,我会传错 |
| 10 `hotkey-in-ui.md` | 「优先级与阻断」 | priority 越高越先执行、block 阻断更低优先级、同优先级都执行;只比较同一次按键匹配到的多条指令 | priority 和 block 对 Once 与 Continuous 是否也生效;文档说目前只对抬起触发的指令生效,那按住连发的冲突怎么解决 | 我预期所有模式都能排序;按文档只有 KeyUp 有效,我需要知道 Once 与 Continuous 的冲突规则 |
| 10 `hotkey-in-ui.md` | 「默认按键」 | @common/exit 默认 Escape 与 X,@ui/menu 默认 Escape,两者都可能匹配 Esc | 同一次 Esc 同时匹配两条指令时谁先执行、会不会都执行;文档只说作用域栈顶实现执行,但两条指令都在栈顶面板里实现时呢 | 我预期 Esc 只关当前面板;如果两个指令都实现,可能一次触发两个动作,我需要知道匹配与阻断规则 |
| 10 `hotkey-in-ui.md` | 「按键与 UI 栈的关系」 | 按键作用域是一条全局栈,只有栈顶作用域的实现执行;hidden 不移除作用域,close 卸载才移除 | useKey 传 false 继承下层实现后,下层实现是被复制还是引用;如果下层后来改了实现,上层会跟着变吗 | 我预期继承的是当时的实现快照;但文档说复制到新作用域里继续生效,复制的深浅不明 |
| 11 `conditional-and-list-rendering.md` | 「条件渲染改的是树,不是样式」 | hidden 保留元素与状态只跳过绘制和命中;三元返回 null 会卸载、状态重置;坐标是绝对定位,hidden 不会让兄弟上移 | hidden 能不能写在组件标签上(例如给 ItemDetail 加 hidden);这一篇的 hidden 都写在元素上 | 我预期写在组件上会作为 attrs 落到根元素;这一篇没说,要到第 14 篇才确认 |
| 11 `conditional-and-list-rendering.md` | 「循环:用 map 生成元素」 | map 返回元素数组,外层要有父容器,数组会成为父容器的子元素列表;固定顺序无状态列表不需要 key | 组件能不能直接返回一个数组作为根(第 23 篇的 ItemGrid 这么做了);这一篇说必须放在渲染函数返回的元素树里、外层要有父容器 | 我预期组件根必须是单个元素;读到第 23 篇时会怀疑两种说法能不能同时成立 |
| 11 `conditional-and-list-rendering.md` | 「key」 | key 只在同一父级兄弟间唯一,列表项是组件时 key 写在组件标签上,重排增删或有状态才需要 | key 写在组件标签上时,组件内部的根元素还需不需要 key;文档说写在内部根元素上没有用 | 我预期只写外层就够;但 map 直接返回组件数组时,key 到底落在 VNode 还是元素上,我不确定 |
| 11 `conditional-and-list-rendering.md` | 「数据怎么变才会更新列表」 | ref 数组 push、splice、整体替换都触发,shallowRef 只认整体替换,reactive 数组不能整体替换,普通数组不触发 | reactive 数组整体替换是编译错误还是运行时静默不更新;文档说变量指向新数组、代理丢失,但没说是哪一类错误 | 我预期会静默不更新;如果是编译错误,我就能在编辑器里发现,处理方式不同 |
| 11 `conditional-and-list-rendering.md` | 「列表项的事件与状态」 | 回调要闭包当前 row,用 row.id 不用 index 反查;删除时要处理选中态 | selectedId 被删除后如果不清空,详情区会怎样;这一篇只说列表,详情在第 22 篇,我读到这里还没有闭环 | 我预期详情会显示旧数据或空;需要读到后面才知道该在面板层清 selectedId |
| 12 `props.md` | 「props 的完整管线」 | 父写属性、VNode props、子组件 props 数组挑键、setup 的 props;没声明的进 attrs,默认透传根元素 | props 数组只列键名、不做类型转换,运行时如果我传错类型(string 传给 number),会不会报错;类型只在编译期检查 | 我预期传错类型会静默通过;但文档说类型由 Props 接口约束,我不确定运行时有没有兜底 |
| 12 `props.md` | 「组件怎么拿参数」 | 普通组件继承 DefaultProps、必须在 props 数组列全、emits 数组声明事件、emit 交回父级 | DefaultProps 具体包含哪些键;文档说它提供元素通用字段与事件类型,但我需要知道 loc、hidden、onClick 是否都在里面 | 我预期继承 DefaultProps 就能写 props.loc;如果不包含,我会在类型上或运行时拿不到 |
| 12 `props.md` | 「泛型顺序」 | 四个泛型是 Props、Emits、事件名联合、Slots,第二第三要配套;没有 props 可省略第二参数 | 只写 defineComponent 的 Props 泛型而省略第二个参数时,props 数组从哪来;文档说第二参数可以省略,但省略后没有 props 声明 | 我预期省略第二参数后 props 全进 attrs;但示例又显示只写泛型不传 options 的情况,我不确定能不能既声明 Props 又省略数组 |
| 12 `props.md` | 「默认值用 props.x ?? 默认」 | 用空值合并而不是逻辑或,不要给 props 赋值;会变的派生值用 computed,挂载后不变的读一次 | computed 里读 props 时,props 更新是否一定触发;文档说会跟随,但如果 props 是普通对象字面量呢 | 我预期 computed 会跟随 props 引用变化;对象内部字段变化是否触发,要看父级是否用响应式容器 |
| 12 `props.md` | 「UI 的基础 props 是控制器注入的」 | controller/instance/state 由控制器注入,open 第二个参数作为自己的 props;hidden 和 zIndex 通常走 attrs | props.loc 到底算不算注入;这一篇没提 loc,第 18 篇说 loc 由打开方传,我需要把两篇拼起来才敢写 | 我预期 UI 组件要额外声明 loc 并在 open 时传;但模板篇的 props 数组只有三项,我照着写会拿不到 loc |
| 13 `component-tsx.md` | 「组件如何映射成一棵子树」 | 组件不产生额外节点,根元素挂到父树;组件树与元素树是两层;多个根节点会成为同一父级的多个子元素 | 多个根节点时 attrs 自动透传落到哪;文档说没有唯一根元素,要到第 14 篇才知道要关掉 inheritAttrs | 我预期多根组件能正常显示;但父级传的 onClick 和 fillStyle 不知道该落哪个根,我读到这里没有答案 |
| 13 `component-tsx.md` | 「一个完整组件的结构」 | 六段:import、Props 接口、SetupComponentOptions、defineComponent、render、导出;setup 返回 render 函数 | defineComponent 里为什么 setup 要返回函数而不是直接返回 JSX;这是 Vue 的 render 约定吗 | 我预期按此结构写就能更新;但我不理解 setup 只执行一次、render 每次执行的边界,写错会把状态放到 render 里 |
| 13 `component-tsx.md` | 「生命周期与渲染树」 | 创建、挂载、更新、卸载;onMounted 拿真实元素,onUnmounted 清理;setup 内 watch 自动停止,定时器要手动清 | onMounted 里拿到的元素引用是什么类型;文档示例用 Container 的 ref,但普通元素如 g-rect 该用什么类型 | 我预期 Container 的 ref 只对 container 有效;要拿 Rect 或自定义元素时我不知道对应类名 |
| 13 `component-tsx.md` | 「expose、emit 与父组件拿子组件」 | expose 暴露方法、父组件 ref 拿到后调用,挂载前是 undefined;emit 与回调 prop 二选一 | expose 暴露的方法在父组件 ref 上的类型怎么标注;文档只给 CardExpose,但那是手写接口,我要不要每个组件都手写 | 我预期可以手写 Expose 接口;如果组件没写 expose,父组件拿到的是组件实例,其类型是什么,文档没有说 |
| 13 `component-tsx.md` | 「组件与 UI 的区别」 | UI 要同时继承 IGameUIPropsBase 与 DefaultProps、props 数组含三项、被 GameUI 注册;普通组件只继承 DefaultProps | 组件被 new GameUI 注册是否只要求导出 GameUI 对象,还是还要在某个列表里登记;文档说 GameUI 不写全局注册表 | 我预期只要 new GameUI 就能 open;但打开处怎么拿到这个对象,仍要 import,我不知道工程里有没有统一出口 |
| 14 `slots-and-attrs.md` | 「slot 解决什么问题」 | TSX 里 slot 是函数不是标签;子组件用 slots 对象调用;默认 slot 用 slots.default 加可选调用,具名同理 | SlotsType 里每个 slot 的返回值为什么必须是 VNode;如果我返回数组(多个节点)类型对不上怎么办 | 我预期 slot 可以返回多个元素;类型写 VNode 时我只能包一层 container,这与组件不产生额外节点的说法有冲突感 |
| 14 `slots-and-attrs.md` | 「具名 slot」 | 具名 slot 用对象传入,键名就是 slot 名;用对象时默认 slot 也要写在 default 键里,不能与普通子元素混写 | 传 slot 时的双层花括号为什么存在;作为没写过 Vue 的人,我不知道这是对象字面量还是某种特殊语法 | 我预期照抄能工作;但如果不理解双括号,我改结构时很容易少写一层 |
| 14 `slots-and-attrs.md` | 「attrs:没声明的属性」 | 未声明为 props 也未消费的属性进 attrs;展开 attrs 原样传给内部元素;inheritAttrs 为 false 关闭自动落根 | attrs 里会不会包含 onClick 这类事件;文档说会,但如果同时声明了 emits,onClick 就被消费不再透传 | 我预期不声明 click 时 onClick 自动落到根元素;声明后必须自己 emit,我需要记住这个分叉 |
| 14 `slots-and-attrs.md` | 「组件边界上的事件与属性」 | 父组件写 onClick 落在哪取决于子组件是否声明 click;声明了就消费,不声明就透传 | 子组件有多个根节点、又没关 inheritAttrs 时,onClick 会落到哪;文档只说没有唯一根元素时应关掉 | 我预期会警告或不生效;具体行为没有写,我排错时没有依据 |
| 14 `slots-and-attrs.md` | 「slots/attrs 在渲染树里的完整例子」 | slot 内容最终成为子组件根元素下的普通子元素,坐标相对子组件容器;attrs 只改属性 | slot 内容的坐标是在父组件作用域算还是子组件容器算;文档说坐标相对子组件容器,但内容是在父组件渲染的 | 我预期写的 loc 是相对 Panel 容器;如果不是,我的布局会整体偏移,这句话我需要确认 |
| 15 `builtin-text-and-input.md` | 「这些组件替你决定了什么」 | TextContent 按 width 折行、autoHeight、逐字显示;Textbox 加背景标题内边距;Input 点开真实输入框;InputBox 一次性弹窗 | TextContent 的 width 与 loc 第三项冲突时到底哪个赢;表里说 loc 第三项会被 width 覆盖,但示例仍写 loc 不写宽,我需要确认写法 | 我预期只传 width 就够;如果我习惯性在 loc 里写第三项,文档说会被覆盖,我不确定是否要删掉 |
| 15 `builtin-text-and-input.md` | 「多行说明」 | interval 毫秒、省略或 0 直接显示全部;showAll、retype、getHeight 通过 ref 调用;事件 onTypeEnd、onTypeStart、onUpdateHeight | TextContent 的根是 custom 元素,点击要放外层 container;但如果外层 container 没写尺寸(默认 200×200),它会不会只覆盖一部分文字 | 我预期把 onClick 放外层就能点整块;但文字高度是测量出来的,外层容器尺寸不会自动跟着变,我不知道该不该用 autoHeight 同步 |
| 15 `builtin-text-and-input.md` | 「标题加正文的说明框」 | Textbox 的 width 必填、正文宽度等于 width 减左右 padding(有图标再减图标宽)、正文高度取 loc 第四项未写按 200;hide 不销毁 | Textbox 同时写 loc 的第四项与 height 属性时哪个生效;示例两处都写了 | 我预期以某一处为准;文档没有说优先级,我照抄时不知道删哪个 |
| 15 `builtin-text-and-input.md` | 「输入组件的受控边界」 | Input 用 v-model:value(即 value 加 update:value),失焦移除真实输入框但值保留;多字段各管各的 | 点击提交按钮时,Input 先失焦再触发 click 还是 click 先;如果先失焦,值会不会刚好在 click 前更新 | 我预期点提交能拿到最新值;但 DOM 输入框与画布事件的先后文档没有说明,我担心拿到旧值 |
| 15 `builtin-text-and-input.md` | 「特殊组件 InputBox」 | getInput(controller、text、loc、width、props)返回字符串 Promise;getInputNumber 返回数字;取消时是空串或 NaN;弹窗在 UI 栈上 | loc 六元组里写 void 0 是什么意思;示例用了两个 void 0,我没见过这种写法,不知道能不能省略 | 我预期照抄能居中;但如果不理解 void 0,我改成 undefined 或删掉后可能位置不对 |
| 16 `builtin-list-and-containers.md` | 「List:可选中的列表」 | List 接收 id 与文本的二元数组、v-model:selected、内部默认选第一项;父级初值要与第一项一致 | 如果 list 数据整体替换(例如换分类),List 的内部选中值会不会跟着变成新列表第一项;文档只说挂载后再改 selected 不会改选 | 我预期换列表后选中会重置;如果不是,我需要知道怎么让它同步,文档没有给方法 |
| 16 `builtin-list-and-containers.md` | 「List」行结构 | List 内部是 Scroll 加每行 container 加 Selection,行宽取 loc 第三项,行高 lineHeight;不要外面给 key | List 的 list 项 id 能不能是数字;文档示例都是字符串,但我的道具 id 可能是数字 | 我预期数字也支持;但类型没写,我不敢传,怕 v-model 类型不匹配 |
| 16 `builtin-list-and-containers.md` | 「ListPage」 | ListPage 左列表右详情、basis 比例、close 只发事件、右侧可按 id 具名 slot 或默认 slot | closeLoc 是相对 ListPage 还是相对右侧内容;文档说相对 ListPage,但示例在 400 宽里靠右,我需要确认它是绝对坐标还是偏移 | 我预期按 ListPage 左上角定位;如果它是相对右栏,我的关闭按钮会跑位 |
| 16 `builtin-list-and-containers.md` | 「Page」 | pages 是总页数、page 从 0 开始、hideIfSingle、changePage、movePage、now、pageChange 事件 | pages 变小且当前 page 超出时会不会自动夹紧;文档说 changePage 会夹,但外部直接改 page 绑定或 pages 变化时没说 | 我预期会自动夹到最后一页;如果不夹,内容区会空白,我需要自己 watch,但文档没提示 |
| 16 `builtin-list-and-containers.md` | 「弹窗与一次性提示」 | ConfirmBox、Choices、InputBox 压 UI 栈;getConfirm 返回布尔、getChoice 返回 key、getInput 返回字符串;getChoice 没有取消分支 | getChoice 的 choices 里 key 是否可以是任意类型;示例用数字,但签名只写 key 与文本,我需要知道能不能用字符串 id | 我预期 key 类型跟数组走;如果不支持字符串,我的分类 id 就得改成数字,文档没有说明 |
| 17 `ui-controller-and-stack.md` | 「控制器、实例与栈」 | 一个 UIController 管一条栈、背景、显示策略;open 产生 UIInstance 压栈;stack 按打开顺序,第 i 层 zIndex 为 i 乘 5 | stack 是不是公开可读的数组、类型是什么;文档多次说栈,但没有给读栈的示例,我只能靠 open 返回值持有实例 | 我预期能读 controller.stack 来调试;如果它不公开,我就只能自己记录实例 |
| 17 `ui-controller-and-stack.md` | 「keep:切换面板时不闪背景」 | keep 返回控制器,close 到空栈不关背景、active 保持真;最后 safelyUnload 或 unload;标记是布尔值不是计数,一次 close 就清掉 | 一次 close 就清掉与 close 到空栈不关背景怎么同时成立;如果 close 清掉 keep,那关旧面板的瞬间背景不就关了吗 | 我预期 keep 期间 close 不会关背景;但这句话让我怀疑 keep 只能挡住栈空那一次判断,我需要知道 close 内部到底先清还是先判断 |
| 17 `ui-controller-and-stack.md` | 「栈策略」 | lastOnly 默认、showAll 可叠加、showCustom 自定义;lastOnly 关闭时从该实例起全部移除,showAll 默认只移除该实例 | 从该实例起是向栈顶方向还是向栈底方向;如果是向栈顶,关中间一个会连带上面;如果是向栈底,会连带下面,语义完全不同 | 我预期关上层弹窗不影响下层;但按从该实例起我无法判断,示例又只给了逐层关闭的情况 |
| 17 `ui-controller-and-stack.md` | 「场景 UI 与主 UI」 | sceneController 管加载、标题、主场景,mainUIController 管背包、设置等;主场景把 mainUIController.render 放进容器,active 为假整体隐藏 | render 返回的是什么(VNode、元素还是组件),也不知道该放在 JSX 的哪个位置;文档只说放进一个容器 | 我预期写 controller.render 就能显示主 UI;如果不返回可渲染节点,我会在类型上报错 |
| 17 `ui-controller-and-stack.md` | 「基础 props 的注入链」 | setPropsBaseCreator 每个实例每次渲染调用一次,返回 controller、instance、state 注入;自定义 creator 必须带回 state | 自定义 creator 里的 state 从哪来;示例只返回 instance 和 controller,文档说接到真实客户端要带回,但没给获取方式 | 我预期在创建客户端时闭包拿到 state;但我没有客户端源码,不知道那个变量叫什么、在哪一层 |
| 18 `replace-builtin-ui.md` | 「替换的是入口,不是实现」 | 每个内置 UI 导出 GameUI 常量,替换点只有打开处与包装层;修改打开入口会影响所有调用方,改单个调用点只影响一处 | 这些内置入口函数(openSettings、openReplay、saveSave 等)现在的完整签名;表里只给名字与参数轮廓,我要替换时不知道该保留哪些参数 | 我预期保留同名同签名只换内部 GameUI;如果签名比我看到的多个参数,我会漏传,文档没有给完整签名 |
| 18 `replace-builtin-ui.md` | 「替换步骤」第二步 | 新组件要接收 controller、instance、state 与 loc,props 数组列全;loc 由打开方传,不由控制器注入 | loc 的类型 ElementLocator 的六元组含义是否与 loc 属性一致;示例直接把 props.loc 传给 container,但我没确认它是不是数组 | 我预期直接把 props.loc 传给根 container;如果类型是对象而非数组,我就写错 |
| 18 `replace-builtin-ui.md` | 「替换步骤」第三步 | 两种做法:保留入口函数换内部 UI,或只改工具栏一个调用点;做法一影响所有调用方 | 保留入口函数时,原函数是否还做了 loc 默认值、背景、keep 等额外工作;文档示例只写了 controller.open,我担心漏掉原逻辑 | 我预期只换 GameUI 对象就等价;如果原入口还处理了别的事,我会丢行为,文档没有列出原函数完整实现 |
| 18 `replace-builtin-ui.md` | 「可以替换哪些、分别影响什么」存档行 | 存档界面替换后必须保留索引、自动存档槽位、mode 语义、校验回调返回值、关闭后的 Promise 结果;返回值语义不能变 | 这些返回值的具体约定(例如 -2 代表什么、Promise resolve 什么);文档只说必须一致,没有给可照抄的语义表 | 我预期换外观后存档仍能读写;但不知道返回值,我会写错槽位 |
| 18 `replace-builtin-ui.md` | 「风险与边界」包装漏转发 | 包装组件要转发全部 props、attrs、slots、emits;漏一个就出问题 | attrs 与 props 一起转发时会不会重复;也不知道 slots 要怎么原样转发(v-slots?对象?) | 我预期包装能透明;但文档没有给一个完整的包装组件示例,我不知道 slots 的转发语法 |
| 19 `ui-performance.md` | 「性能问题先定位在哪一层」 | 六个层:绘制缓存、命中遍历、组件重渲染、列表滚动、纹理文字、UI 栈背景;先做减法看差异 | 在文档站或游戏内怎么打开浏览器性能面板、怎么录帧;文档假设我会用开发者工具 | 我预期按表定位;但我连帧时间在哪里看都不确定,第一步就卡住 |
| 19 `ui-performance.md` | 「缓存:什么时候有用、什么时候有害」 | 缓存适合结构复杂内容稳定的子树,不适合简单内容、频繁变化、过大子树;容器默认缓存,文字高频变化时应拆出去 | 过大的阈值;文档说不给毫秒数,但也没给内存或尺寸的参考,我无法判断我的面板算不算过大 | 我预期小面板不用管;但 720×480 全屏缓存算不算过大,我没有依据 |
| 19 `ui-performance.md` | 「纹理与文字」 | 大图按纹理尺寸占内存、同图共享纹理、不要在渲染函数里建纹理;文字变化要重新测量排版 | 每个元素仍可能有自己的离屏缓存与第 6 篇 image 默认不缓存怎么合起来理解;image 到底默认有没有离屏缓存 | 我预期 image 默认不缓存;但这句话说可能有,我不知道什么时候会有 |
| 19 `ui-performance.md` | 「观测与验证」 | 固定最坏场景、录几秒、做减法、一次只改一个开关、回到真实数据 | 长帧的具体判定标准;文档说不给毫秒数,那我看到 30fps 算不算问题 | 我预期只能相对比较;但没有基线,我不知道优化到什么程度算够 |
| 19 `ui-performance.md` | 「UI 栈」 | 能 hide 和 show 就不 open 和 close;稳定背景用 setBackground;keep 用完卸载;栈越深越贵 | 栈越深越贵是线性还是指数;如果我要同时开 5 个面板,是否应该合并成一个 | 我预期 5 层还能接受;但没有量级,我无法决定要不要改结构 |
| 20 `inventory-example-1-skeleton.md` | 「骨架在渲染树里的位置」 | 根 container 720×480,面板主体 [30,30,660,420],左 [54,100,400,280],右 [470,100,196,280],底 [54,392,304,32];坐标相对根 | 这个 720×480 的根容器与 UI 容器、画布的关系;文档说 UI 容器由控制器创建,但没给 UI 容器的尺寸,我不知道面板会不会被裁 | 我预期打开后在画布上看到完整 720×480;如果画布只有 480×320,我看到的是被裁掉的面板,需要按文档加 scale |
| 20 `inventory-example-1-skeleton.md` | 「骨架代码」 | 完整骨架代码,包括背景、主体、标题、关闭按钮、两个占位;props 数组三项;GameUI 导出 | 这段代码里 IGameUIPropsBase 与 DefaultProps 的导入路径是否都可用;模板篇说来自 client-base 与 render-vue,这里没重复 import | 我预期照抄能编译;缺 import 时我会看到找不到名称,需要回到代码基础补,文档没有列全 import |
| 20 `inventory-example-1-skeleton.md` | 「打开它」 | 三个打开入口:sceneController、props.controller、mainUIController;区别在哪个栈 | 第一次打开这段代码放在哪;示例是在某个已有组件里用 props.state,但我还没有任何已打开的 UI 来提供 props | 我预期从 bootstrap 或主场景打开;但文档说 bootstrap 持有 client,我没有它的源码,找不到变量名 |
| 20 `inventory-example-1-skeleton.md` | 「运行效果」 | live 用 720×480,关闭按钮只显示提示,文档站没有真实 UI 栈 | live 的 720×480 与正文说的示例站画布 480×320 是什么关系;两个尺寸同时出现,我不知道该按哪个设计 | 我预期 live 能看到完整面板;但正文又说示例站是 480×320,我不确定自己的验证环境是哪一个 |
| 20 `inventory-example-1-skeleton.md` | 「边界与注意」 | 不要用真实素材、关闭按钮要先能用、Props 三件套、占位区尺寸 | 不用真实素材时图标怎么画;文档说用矩形加文字,但我的道具没有图标字段,我不知道格子该显示什么 | 我预期用纯色块加名称数量就够;视觉上怎么区分不同道具,文档没有给最小图形方案 |
| 21 `inventory-example-2-grid.md` | 「数据模型:Item 只定义一次」 | Item 有 id、name、count、desc,id 稳定唯一;Item 与 ItemGrid 同文件 export,其他文件用 import type | import type 在 ItemCell 文件里会不会造成循环依赖;文档说类型导入编译后擦除,但我还是不确定运行时是否安全 | 我预期安全;但如果 ItemGrid 又 import ItemCell,两个文件互相 import,我需要知道类型导入是否真的不生成 require |
| 21 `inventory-example-2-grid.md` | 「ItemCell:一个格子」 | ItemCell 无状态,props 有 item、selected、size,点击 emit select(id);描边选中与未选中保持尺寸一致 | size 只读一次,如果父级之后改 cellSize,格子不会跟着变;文档注释说若尺寸会随窗口变化再改成 computed | 我预期父级改尺寸时格子会更新;按示例不会,我需要知道什么时候必须用 computed |
| 21 `inventory-example-2-grid.md` | 「ItemGrid:按行列排列」 | columns、cellSize、gap 用 computed 派生,坐标按列乘间距;key 用 item.id;定位容器与格子同尺寸 | props.items 直接 map 时,如果 items 是普通数组(非响应式),父级改数组会不会重渲染;文档说 items 由面板 ref 持有,传给网格的是 items.value | 我预期父级 ref 变化会传新数组并重渲染;如果子组件拿到的是普通数组,我担心它不会追踪内部变化 |
| 21 `inventory-example-2-grid.md` | 「数据如何进入网格」 | 数据只有一条路:面板持有 items,传解包后的数组;selectedItem 在面板 computed;网格只上报 | items.value 传给子组件后,子组件改 props.items 里的对象字段(例如 count)会不会影响父级;文档说对象是响应式代理,但没说子组件能不能改 | 我预期子组件不应改 props;但示例(五)的使用是在面板改,我需要确认网格只读 |
| 21 `inventory-example-2-grid.md` | 「这一步的边界」 | 本步网格不滚动,超出的格子仍渲染在区域外;示例(四)换成 Scroll,props 与事件链不变 | 普通网格超出的格子仍渲染时,会不会盖住右侧详情区;左侧容器没有裁剪,格子画到 x 大于 400 会进入右侧 | 我预期不会盖住;但文档说容器不裁剪绘制,我需要知道右侧详情的 zIndex 或绘制顺序是否能盖住它 |
| 22 `inventory-example-3-detail.md` | 「详情区接的是哪个状态」 | selectedId 用可空字符串 ref,初始 null;selectedItem 用 computed 加空值合并收口成 null;不要用 undefined 或空串 | selectedId 为 null 时 items 的 find 比较逻辑;item.id 等于 null 永远 false,所以返回 undefined,我能推出来,但文档没有明确写 | 我预期未选中时 selectedItem 为 null;按空值合并确实如此,但我需要自己推一遍才确定 |
| 22 `inventory-example-3-detail.md` | 「详情区的树结构」 | 根 196×280,背景、标题、两块 hidden 容器、取消按钮;描述用 TextContent,width 为 164,autoHeight | 两个 hidden 容器都没写 loc 和 size 时默认 200×200 会不会互相遮挡;它们都在详情根里,200 宽超过 196,200 高到 y 为 200,而取消按钮在 236 | 我预期不会遮挡按钮;但默认尺寸超过容器宽,我不确定会不会盖住右边或影响命中 |
| 22 `inventory-example-3-detail.md` | 「ItemDetail:右侧面板」 | props.item 允许 null,两块用 hidden 切换都渲染;取消选择只 emit clear;按钮最后放所以盖在内容上 | 详情块的文本在 item 为 null 时仍会被求值并显示空串;描述 TextContent 仍会创建并测量空文本 | 我预期空文本不占高度;但 TextContent autoHeight 测出 0 时,是否仍会创建 custom 元素,我不确定 |
| 22 `inventory-example-3-detail.md` | 「空态与边界」 | 三种空态:未选中、选中项被删除、items 为空;删除时要在面板层把 selectedId 写回 null | 选中项被删除时,如果不是通过面板的删除函数,而是 items 被外部整体替换,selectedId 不会自动清;文档只说要手动检查 | 我预期外部替换 items 后详情显示旧 id 或空;我需要知道有没有统一的 watch 入口,文档没有给 |
| 22 `inventory-example-3-detail.md` | 「运行效果」 | live 用元素层文字等价展示多行,正文才是 TextContent;两者不是同一段代码 | live 与正文不一致时,我该以哪个为准;文档说两者不是同一段代码,但没说明 live 的视觉是否与真实 TextContent 一致 | 我预期 live 只用于看布局;但文字高度和换行可能不同,我无法用 live 验证真实排版 |
| 23 `inventory-example-4-scroll.md` | 「为什么要换滚动」 | Scroll 只检查直接子元素,内容不能先包大容器;组件本身不是节点,ItemGrid 返回行数组,行会平铺成 Scroll 的直接子元素 | 组件返回数组作为根是否被渲染器支持;这一篇直接说返回行数组,但第 11 篇说 map 必须放在有父容器的元素树里 | 我预期按本篇写能滚动;但按第 11 篇的理解,我会以为组件根必须是单个元素,两种说法我需要确认 |
| 23 `inventory-example-4-scroll.md` | 「Scroll 在渲染树里的位置」 | 左侧容器 [54,100,400,280],Scroll [0,0,372,244],行容器从 y 为 0、每行 74,按钮在 y 为 252;滚动条在视口右侧 | Scroll 的视口宽 372 与左侧 400 之间 28 像素,是否就是滚动条宽度;文档说右边留出的 28 像素是滚动条与内边距,但没给滚动条具体宽度 | 我预期可点击元素避开 x 为 372 附近就安全;如果滚动条更宽,我会压到它,文档没有精确值 |
| 23 `inventory-example-4-scroll.md` | 「ItemGrid 改为行容器数组」 | 行容器 key 用行号、格子 key 用 item.id;行高必须包住整行;返回 rows 数组 | rows 用空数组声明时 TypeScript 会不会推断成 any 数组;文档没有给类型,我照抄可能在严格模式下报错 | 我预期能编译;如果 noImplicitAny 开启,我需要自己标注类型,文档没提 |
| 23 `inventory-example-4-scroll.md` | 「面板里怎么接」 | Scroll 包 ItemGrid,scrollTo 回顶、scrollTo 传入 getScrollLength 到底;padEnd 给 16;hide 保留滚动位置、close 重置 | getScrollLength 在内容不足一屏时返回 0 或负数,scrollTo 负值会怎样;文档说会被夹到 0,但没说负数输入是否告警 | 我预期滚到底按钮在内容少时不动;按夹紧逻辑确实不动,但我需要确认不会报错 |
| 23 `inventory-example-4-scroll.md` | 「滚动与事件」 | Scroll 在捕获阶段补滚动偏移,格子拿到局部坐标;拖动超过阈值才算拖动,否则算点击;不要在内容上再套滚动手势 | 拖动阈值是多少;如果我的格子很小,轻微移动会不会被当成拖动而不选中 | 我预期轻点能选中;但阈值未知,触屏或手抖时可能选不中,文档没有给数值或可配置项 |
| 24 `inventory-example-5-state.md` | 「操作条的树与事件流」 | ActionBar 三个按钮横排,点击 emit equip、use、close;禁用只视觉弱化加早返回 | makeButton 在 enabled 为 false 时,容器仍然接收点击并早返回,那它会不会挡住下面同位置的元素;按钮之间没有重叠,所以暂时没事,但我不确定设计意图 | 我预期禁用按钮点不动但也不会穿透;如果是早返回,点击被吃掉,不会落到面板背景,文档没有说这是否预期 |
| 24 `inventory-example-5-state.md` | 「状态放在 InventoryPanel」 | items、selectedId、equippedId、hint;selectedItem、canEquip、canUse、isEquipped 都是 computed;使用减 count 用 watch 更新 hint | 直接改 props 传下来的对象里的 count 算不算改 props;这个 item 来自 items.value,面板持有,网格只读,但 ItemDetail 也拿到同一个对象 | 我预期面板改 count 会触发网格与详情更新;如果对象被 markRaw 或 shallowRef 包过就不会,文档警告过不要用 shallowRef,我需要确认 |
| 24 `inventory-example-5-state.md` | 「状态变化如何反映到画面」 | 装备改 equippedId、isEquipped、ItemGrid 的 equippedId、ItemCell 描边绿;使用改 count、数量文本与 canUse;提示改 hint 文本 | 监听 selectedItem 的 count 时,切换选中但 count 相同不会触发;文档说这是预期,但如果我想每次切换都提示,需要另写 watch | 我预期切换选中会刷新提示;按当前写法同数量不刷新,我需要知道这是否是我要的行为 |
| 24 `inventory-example-5-state.md` | 「关闭的完整路径」 | 三个关闭入口最终都走 controller.close(instance);ActionBar 只 emit close;Esc 用 useKey 实现 @common/exit | Esc 的实现要放在哪个 setup 阶段、和 useKey 的调用顺序有没有关系;文档说 setup 里调一次,但没给完整组件片段 | 我预期放在 setup 顶部即可;如果放在 return 之后或事件里就不生效,我需要看到完整位置才敢写 |
| 24 `inventory-example-5-state.md` | 「遮罩与 noevent」 | 遮罩放根容器第一个子节点、面板主体之前,先绘制所以面板盖住它;noevent 让点击下穿 | 遮罩铺满 720×480、面板主体只占 660×420 时,面板外的遮罩是否真的能压暗画布;如果根容器本身不绘制,遮罩就是唯一覆盖层 | 我预期面板外变暗;但最终组装里又套了一层同尺寸 container,我不确定遮罩是在内层还是外层,效果是否一样 |
| 25 `inventory-example-6-animation-and-register.md` | 「动画作用在树的哪一层」 | 只改 alpha,不重建组件;呼吸描边加 noevent,提示文字改 hintAlpha;rAF 在 onMounted 启动、onUnmounted cancel | requestAnimationFrame 每帧写 pulse 会不会导致整个面板组件重渲染;文档说只驱动响应式值、不重建组件,但响应式是组件级重渲染,元素只 patch alpha | 我预期每帧都会重跑渲染函数、只 patch alpha;如果面板很大,这可能就是性能问题,文档没有说明是否要拆成子组件 |
| 25 `inventory-example-6-animation-and-register.md` | 「最终组装与契约核对」 | 九条契约、最终骨架、坐标以本篇为准;外层画布根加内层面板根,内层实际用 hidden 控制开合 | 内层面板根为什么需要,以及 hidden 写在哪一层;文档说实际代码用 hidden 控制开合,但骨架里没给 hidden 的位置 | 我预期 hidden 写在面板根上;如果外层根也 hidden,两者区别是什么,文档没有说 |
| 25 `inventory-example-6-animation-and-register.md` | 「注册与打开」 | InventoryUI 在 inventory-panel.tsx 导出,index.ts 再导出;打开用 mainUIController.open(InventoryUI、空对象) | 这段打开代码具体放在哪个组件或文件里;文档说从主 UI 栈打开,但没有给一个宿主组件的完整片段 | 我预期在工具栏或主场景里调用;但我没有主场景源码,不知道 props.state 在那一层是否可用 |
| 25 `inventory-example-6-animation-and-register.md` | 「最终验证清单」 | 打开、选中、取消、滚动、装备、使用、关闭、再次打开的预期与对应路径;再次打开应回到初始状态 | 再次打开在文档站 live 里怎么做到;live 有重新打开按钮,但真实游戏里没有这个按钮,我需要知道关闭后从哪里再打开 | 我预期从原入口再 open;关闭后入口是否还在(工具栏是否被遮住)文档没有说 |
| 25 `inventory-example-6-animation-and-register.md` | 「边界与注意」 | 动画卸载必须停、动画节点不进子组件 props 链、拆分后逐层传 props、注册不写名字表、性能先测再改 | 最终 live 如果跑不起来、保留代码与说明是什么意思;作为读者我遇到 live 不跑时,不知道是我的环境问题还是文档问题,也不知道该检查哪些依赖 | 我预期按清单能自查;但 live 失败时没有排查步骤,我只能停在这里 |
## D-93 复述检查
### 渲染树
我现在的理解是:
- 一棵固定的树:画布根、UI 容器(控制器创建)、面板根容器(作者写)、区域容器、元素;后两层由作者控制。`container-and-coordinates.md` 说这张图是全站渲染树的权威。
- 组件不是节点:组件执行 setup 返回 render,render 返回 VNode,渲染器把 VNode 变成元素挂到父元素下;组件树与元素树是两层,组件边界不可见。若组件返回多个根,它们会成为同一父级的多个子元素。
- 容器有三个职责:局部坐标系(子元素 x、y 相对父容器)、事件捕获单位、排序与缓存边界。子元素按兄弟 zIndex 排序绘制。
- 坐标是绝对坐标,没有 DOM 布局流;hidden 不会让兄弟上移。容器不裁剪绘制,但命中受父容器矩形限制(0×0 容器看得见点不到)。
- hidden 保留实例与状态、跳过绘制与命中;三元或 key 变化会销毁重建。容器默认缓存,text、image、全部图形默认不缓存。
- UI 栈里每个打开实例是 UI 容器下的兄弟,第 i 层 zIndex 为 i 乘 5;背景在 zIndex 0。
我复述时仍不确定的:组件直接返回数组作为根是否被支持(第 11 篇与第 23 篇的读法不同);多个根时 attrs 落到哪;UI 容器的尺寸由谁定、mainUIController.render 返回什么。
### 事件捕获与冒泡
我现在的理解是:
- 命中:从画布根开始,每一层按子元素 zIndex 从大到小找第一个命中的;同值后加入的先;容器按矩形、图形按几何轮廓;命中就停,不检查同级其它元素。hidden 不绘制也不命中;noevent 仍绘制但整个子树不参与命中。
- 捕获:根到命中元素,父容器先收到 onXxxCapture。冒泡:命中元素到根,子元素先收到 onXxx。完整顺序是根捕获、各级捕获、目标捕获、目标冒泡、各级冒泡、根冒泡。
- stopPropagation 截断传播:捕获阶段调用会同时取消内层捕获与整段冒泡;冒泡阶段调用则外层不再收到。它不阻止同一元素同名监听器,也不阻止浏览器默认行为。
- onEnter 与 onLeave 不走普通冒泡:根维护 hover 集合,每次 move 后做差集,先 leave 后 enter;父容器在指针下时也在集合里,所以从父移到子不会触发 leave 或 enter。
- 事件对象:target 是当前处理事件的元素(每个元素拿到自己);offsetX 与 offsetY 是当前元素局部坐标(变换会反算);absoluteX 与 absoluteY 是画布坐标;type 是本次触发按键,buttons 是当前按住的所有键。
- actionStroke 只让描边命中,命中宽度等于 lineWidth。
我复述时仍不确定的:最初命中的元素怎么取(target 被改写后);MouseType 与 buttons 的位定义是否同一套;按下与抬起落在不同元素时 click 的归属;拖动阈值。
### 组件 props、slots、attrs 与内置组件
我现在的理解是:
- props 的管线:父组件写属性,进入 VNode props,子组件 props 数组挑出键,setup 的 props 拿到;没声明的进 attrs,默认透传到根元素。props 数组漏写等于没传,组件里读到 undefined。
- props 是只读、响应式的,不要解构;默认值用空值合并;会变的派生值用 computed。UI 额外由控制器注入 controller、instance、state;open 的第二个参数是界面自己的 props。
- attrs 是未声明属性的集合,可展开给内部元素;inheritAttrs 为 false 关掉自动落根。子组件声明了 emits 里的 click 后,父组件的 onClick 被消费,必须由子组件 emit。
- slots 在 TSX 里是函数不是标签;子组件用 slots 对象调用,默认 slot 用 slots.default 可选调用,具名 slot 用对象传入;slot 内容成为子组件根元素下的普通子元素,坐标相对子组件容器。
- 内置组件是普通组件:TextContent 负责按 width 折行、测量高度、逐字显示;Textbox 在文字外加背景标题内边距;Input 在画布上覆盖真实输入框;InputBox 通过 UI 栈弹一次拿结果;List 管行布局与选中;ListPage 管左右分栏;Page 管页码;Scroll 只管视口且只对直接子元素做虚拟滚动;Selection 只画选中框;ConfirmBox 与 Choices 是一次性弹窗。
- 内置组件的共同边界:TextContent 与 Textbox 的 width 必填且覆盖 loc 第三项;Input 的绑定是 v-model:value;Scroll 的子元素必须平铺;List 的选中由点击驱动、父级初值取第一项。
我复述时仍不确定的:DefaultProps 到底包含哪些键;Texture 与 ITexture 是否同一类型;普通子组件怎么拿按键 system;slot 返回 VNode 与返回数组的差别;包装组件怎么原样转发 slots。
## 跨篇问题(仅读者困惑)
1. 第一次 open 到底写在哪:模板篇说去 bootstrap 或某个已有面板,但没有一篇给出「从零新建文件后,在哪个已有文件的哪一行调用 open」的完整片段。我读到第 20、25 篇仍然不知道宿主是谁。
2. loc 的注入:第 1 篇说只注入 controller、instance、state,第 18 篇说替换内置 UI 时组件必须接收 loc 且 loc 由打开方传。我需要一份「UI 组件到底该声明哪些 props、分别由谁传」的清单。
3. 组件根能不能是数组:第 11 篇说 map 必须放在有父容器的元素树里,第 23 篇说 ItemGrid 返回行数组直接作为 Scroll 的子元素。我不知道该按哪句写。
4. hidden 写在组件标签上:第 11 篇只示范元素,第 12、14 篇说基础属性走 attrs 落到根元素。我不确定给 ItemDetail 加 hidden 是否等价于给它的根容器加 hidden。
5. keep 的清除语义:第 17 篇一边说 close 到空栈不关背景,一边说一次 close 就清掉 keep 标记。我不知道关旧面板那一下背景会不会闪。
6. Texture 与 ITexture:第 6 篇的示例用 new Texture,素材管理器返回 ITexture,第 8 篇又建议 markRaw 纹理。我不知道从素材管理器取到的对象能不能直接给 image。
7. text.md 的居中示例:既在 loc 后两项写 0.5,又写 anchorX 和 anchorY 为 0.5,正文却说只写一种。我不知道哪个是最终写法。
8. MouseType 与 buttons:第 9 篇示例把 MouseType.Left 当位掩码和 buttons 做位与,但同一篇说 MouseType 是按键种类。我不知道 buttons 的位定义在哪里。
9. Scroll 的直接子元素跨组件边界:第 16 篇说 Scroll 只检查直接子元素,第 23 篇说组件返回的行数组会成为直接子元素。我不知道组件边界算不算一层节点。
10. 设计尺寸 480×320 与 720×480:第 2 篇说画布设计尺寸来自 renderer,第 20 篇 live 用 720×480,正文又说示例站是 480×320。我不知道自己在验证时该按哪个尺寸。
11. useKey 在普通子组件:第 10 篇说在组件 setup 里调用,示例都默认有 props.state;第 25 篇在面板里用。我不知道子组件该由父级传 system,还是也能自己拿。
12. List 的选中同步:第 16 篇说父级初值要与第一项一致,挂载后再改 selected 不会改选。我不知道列表数据整体替换时内部选中会不会重置,以及该怎么同步。
13. 内置入口函数的完整签名:第 18 篇表格只给 openSettings、openReplay、saveSave 等名字与参数轮廓,我需要完整签名和返回值语义才能安全替换。
14. image 的缓存:第 6 篇说 image 默认不缓存,第 19 篇说每个元素仍可能有自己的离屏缓存。我不知道什么时候 image 会有离屏缓存。
## 声明
未读源码:是
未修改任何文档:是
未读上一轮审阅记录:是
live 目视验证:未执行
@@ -0,0 +1,880 @@
# 10-53 独立读者循环记录(第 2/3 轮)
Round 1 见 `10-49-READER-REVIEW.md`,本文件只记录 Round 2/3,不复制 Round 1 内容;记录不交给用户。
### 第 2 轮
派发状态:见 Task 2
用户更正(2026-11-01):Round 2/3 改为一个读者读完全部 25 篇,不是 4 组读者;4 组临时结果作废。本文件按单读者结构记录。
#### 读者
单读者,人格逐字如下:
> 你是一位刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。你完全没写过 UI,不知道 canvas 是什么,也不会 Vue 的组件写法;你只掌握了基础 TS/JS、函数、对象、数组和一点点模板语法。你手里只有这套文档,不能看源码,也没有人可以问。你的任务不是评价文档好坏,而是老老实实按顺序读,读到哪里卡住就记下:我在哪一段卡住、我从文档里已经知道什么、我还缺什么才能继续往下做。
阅读范围(25 篇,按顺序):
1. `docs/advanced/ii/ui/ui-template.md`
2. `docs/advanced/ii/ui/container-and-coordinates.md`
3. `docs/advanced/ii/ui/basic-shapes.md`
4. `docs/advanced/ii/ui/curves-and-paths.md`
5. `docs/advanced/ii/ui/text.md`
6. `docs/advanced/ii/ui/image-and-texture.md`
7. `docs/advanced/ii/ui/layer-transform-performance.md`
8. `docs/advanced/ii/ui/reactivity.md`
9. `docs/advanced/ii/ui/events.md`
10. `docs/advanced/ii/ui/hotkey-in-ui.md`
11. `docs/advanced/ii/ui/conditional-and-list-rendering.md`
12. `docs/advanced/ii/ui/props.md`
13. `docs/advanced/ii/ui/component-tsx.md`
14. `docs/advanced/ii/ui/slots-and-attrs.md`
15. `docs/advanced/ii/ui/builtin-text-and-input.md`
16. `docs/advanced/ii/ui/builtin-list-and-containers.md`
17. `docs/advanced/ii/ui/ui-controller-and-stack.md`
18. `docs/advanced/ii/ui/replace-builtin-ui.md`
19. `docs/advanced/ii/ui/ui-performance.md`
20. `docs/advanced/ii/ui/inventory-example-1-skeleton.md`
21. `docs/advanced/ii/ui/inventory-example-2-grid.md`
22. `docs/advanced/ii/ui/inventory-example-3-detail.md`
23. `docs/advanced/ii/ui/inventory-example-4-scroll.md`
24. `docs/advanced/ii/ui/inventory-example-5-state.md`
25. `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`
#### 逐篇提问
| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 |
| --- | --- | --- | --- | --- |
| `docs/advanced/ii/ui/ui-template.md` | 「一个最小 UI」代码块 | 组件由 Props 类型 + props 列表 + `defineComponent` + `GameUI` 四段组成,结构写在 render 返回的标签里 | 这些 import(`@motajs/system`、`@user/client-base`、`@motajs/render-vue`)分别是什么包、TSX 靠什么编译(jsx 配置)、我新建的 `src/client/ui/my-panel.tsx` 在什么条件下才会被编译进来 | 把这段贴进文件就能显示面板,不用再做别的配置 |
| `docs/advanced/ii/ui/ui-template.md` | 「打开与关闭」 | 知道三个打开入口,分别开在场景控制器、当前控制器、主 UI 栈上 | 这行 `open` 到底写在哪个文件;模板里没有任何地方调用 open,我不在组件里却拿不到 `props`,那主入口那一行应该长什么样 | 照抄 `props.state.sceneController.open(MyPanelUI, {})` 就能打开 |
| `docs/advanced/ii/ui/ui-template.md` | 「三个基础 props」 | 知道 `controller` / `instance` / `state` 是注入的,props 列表少写不报错、只是拿不到 | `IGameUIPropsBase` 与 `DefaultProps` 里到底有什么字段;我能不能往 props 列表里加自己的键而不改接口;`state` 上有哪些成员(这里只说「场景控制器、主 UI 控制器、素材管理器、渲染根等」) | 只要写全三个键,就能在组件里随意读 `props.state.xxx` |
| `docs/advanced/ii/ui/container-and-coordinates.md` | 「loc 与锚点」 | 知道六元组顺序、后两项可省略、默认锚点 0、圆默认 0.5、`anc` 是简写 | `zIndex` 的默认值是多少(全文第一次要判断遮挡,这里没给);「省略宽高时沿用元素当前尺寸(默认 200×200)」——首次挂载时「当前尺寸」指什么 | 不写宽高就是 200×200,之后也不会变 |
| `docs/advanced/ii/ui/container-and-coordinates.md` | 「坐标基准与画布」 | 知道 `props.state.renderer.width/height` 是设计尺寸,居中要自己算 | 我们这游戏的画布设计尺寸具体是多少、面板根会不会被控制器摆到某个位置;我以为 `[0,0,480,320]` 会出现在左上角,但没有一处确认 | 按 `renderer.width` 算出的 x/y 就是面板左上角 |
| `docs/advanced/ii/ui/basic-shapes.md` | 「填充、描边与命中」下表 | 知道三个开关的组合结果、默认色 `#ddd`、`g-line` 默认描边 | 怎么做出「完全看不见但能点」的矩形:表里「否/否」结果仍是填充;没有一处说透明怎么表达(`rgba(...,0)`?`alpha={0}`?),而「像边框下面垫一个透明的填充矩形」这句就建立在这个没解释的写法上 | 写 `alpha={0}` 或 `fillStyle="transparent"` 就得到透明热区 |
| `docs/advanced/ii/ui/basic-shapes.md` | 「图形作为界面零件」表 | 知道分隔线可加 `noevent`、遮罩可用 `alpha` + `noevent` | 表格里 `g-rectr` 的圆角写法这里没展开、按钮底与文字的命中关系这里只有一句 | 按表格拼按钮,点击一定落在按钮底 |
| `docs/advanced/ii/ui/curves-and-paths.md` | 「路径与曲线的坐标基准」 | 知道贝塞尔的点写在父容器坐标、`g-path` 的点是元素局部坐标、不写 `x/y` 时从父容器原点开始 | 两种基准混在一棵子树里时,我怎么一眼分辨;想把路径整体平移只能给元素写 `x/y`,贝塞尔却只能包容器,我不确定能不能用同一套布局手法 | 同一容器里贝塞尔与 path 的坐标基准一致,可以互换写法 |
| `docs/advanced/ii/ui/curves-and-paths.md` | 「路径」代码块后 | 知道路径要在渲染函数外构造一次、每次新建会让缓存失效 | 「渲染函数外」指 setup 顶层还是模块顶层;放模块顶层时多个面板实例共享一个 `Path2D` 会不会有问题(文档没说) | 写在任何地方都只创建一次且互不影响 |
| `docs/advanced/ii/ui/text.md` | 「字体」 | 知道 `Font` 构造是位置参数、`Font.defaults()` / `Font.clone` / `Font.setDefaults` | `addFallback` 是静态方法还是实例方法(没有任何代码);默认字体五项各自类型;`Font` 与 `Text` 一起从 `@motajs/render` 导入是否够 | 能写出 `font.addFallback('宋体')` |
| `docs/advanced/ii/ui/text.md` | 「尺寸与居中」 | 知道 `width` / `height` 不给裁剪、下次测量会覆盖 | 那 `loc` 里写高度有什么意义;只讲了 `anchorX` 右对齐,纵向靠底怎么对齐;颜色会不会从父容器继承(父容器设了 `fillStyle`,子 `<text>` 不写是不是白) | `loc` 能固定文字框,颜色会继承 |
| `docs/advanced/ii/ui/image-and-texture.md` | 「加载一张 PNG」 | 知道 `Texture` 接 `HTMLImageElement`、要等 `onload`、用 `null` 表示还没加载 | `/assets/icons/potion.png` 在我项目里指向哪里、打包时怎么处理;`getImageByAlias` 返回的 `ITexture \| null` 和 `new Texture(...)` 是不是同一个类型,能不能直接传给 `image` | 抄这段就能显示我自己的图标 |
| `docs/advanced/ii/ui/image-and-texture.md` | 「像素图与高清缓存」 | 知道 `noanti` 是主开关、`hd` 只对开缓存的元素有效 | 开了 `cache` 之后 `hd` 的默认值是什么、我什么时候该显式写 `hd={false}` | 只写 `noanti` 就够,`hd` 可以不管 |
| `docs/advanced/ii/ui/layer-transform-performance.md` | 「变换:scale、rotate 与 alpha」 | 知道 `scale` 必须数组、`rotate` 用弧度、锚点是变换中心 | `filter` / `composite` 只写「再查对应取值」,没有列表也没有链接,我不知道模糊、灰度该写什么字符串;父级 `nocache` 时父级 `alpha` 怎么作用 | 能直接写 `filter="blur(4px)"` 并生效 |
| `docs/advanced/ii/ui/layer-transform-performance.md` | 「缓存与脏更新」 | 知道默认缓存/不缓存清单、`nocache` 优先 | 旋转后的缓存按什么分辨率生成、会不会糊(只说 `hd` 管高清);缓存与 `alpha` 同时用时是先缓存再整体乘 alpha 吗 | 旋转 + 缓存的画面和直接画一样清晰 |
| `docs/advanced/ii/ui/reactivity.md` | 「响应式作为界面零件」 | 知道状态归属跟着「共同读取者」走 | 283 行写「用 `v-model:open` 或 `:open` + `@toggle` 传下去」,这是模板写法;在 TSX 里这两种到底长什么样(`v-model:open={open.value}`?),本篇没给例子 | 照这行字能写出双向绑定的开关 |
| `docs/advanced/ii/ui/reactivity.md` | 「ref:带 value 的盒子」 | 知道 TSX 里必须写 `.value`、`ref` 包对象也是深层响应 | 事件回调里改 `count.value` 触发重渲染是同步还是微任务(后面讲了合并,但「点一下按钮文字什么时候变」没有直接说) | 改完下一帧就变 |
| `docs/advanced/ii/ui/events.md` | 「事件对象」 | 知道 `target` 是「当前正在处理事件的元素」,不是最初命中的元素 | 那我判断「点到了谁」到底看什么字段;有没有 `currentTarget`;为什么要这样设计(和常见的 DOM 经验冲突,而我没有 DOM 经验反而更没法校准) | 父级 `onClick` 里 `ev.target` 是父容器 |
| `docs/advanced/ii/ui/events.md` | 「事件名:on 加事件名」表 | 知道 `onClick` / `onDown` / `onUp` / `onMove` / `onEnter` / `onLeave` / `onWheel` | 右键、双击、长按有没有事件名;`touch` 字段有了,但没有触摸专用事件名 | 右键菜单能用某个 `onXxx` 接 |
| `docs/advanced/ii/ui/events.md` | 「enter 与 leave」 | 知道由根节点比较悬停集合、先 leave 后 enter | 「每次指针移动」与「每帧比较」两种说法同时出现(`container-and-coordinates` 说每帧、这里说每次移动),快速划过时到底触发几次 | 同一帧内划过一个元素一定会触发 enter/leave |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | 「useKey」与「注册新指令」 | 知道 `useKey` 在 setup 同步调用、作用域随卸载离开、`implement` 覆盖并告警 | `props.state.hotkey` 与 `props.state.hotkey.system` 是什么关系:`addCommand` 在 `system` 上、`setGroup` 在 `hotkey` 上,我要在哪存住 `system`;`KeyCode` 与 `HotkeyEmitMode` 都从 `@motajs/system` 导入吗 | 两处能混着写,`state.hotkey` 就是 system |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | 「方向键移动选中项」 | 知道用 `ref` 存选中、画面由响应式更新 | 如果列表换成第 16 篇的内置 `List`(选中在组件内部),这个例子还成立吗 | 改 `selected.value` 就能让列表换行高亮 |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | 「循环:用 map 生成元素」 | 知道 `.map()` 放父容器里、返回数组成为子元素、无状态定长不用 `key` | 数组里能不能混 `null`(条件项);`{cond && <X/>}` 这种写法在这里等价于什么 | 列表里某些项 `return null` 会被跳过 |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | 「数据怎么变才会更新列表」表 | 知道 `ref` 数组深层响应、`shallowRef` 只认整体替换、`reactive` 不能整体替换 | 表里没有「改数组某一项的字段」这一行(`items.value[i].count -= 1`),而这种写法在第 24 篇用到了 | 改内部字段不会触发更新 |
| `docs/advanced/ii/ui/props.md` | 「props 的完整管线」 | 知道四环、数组漏写落到 attrs、默认值用 `??` | 布尔 prop 怎么写:`<ItemCell selected />` 算不算 `true`;props 数组只有字符串没有类型,数字属性传进去会不会变字符串 | 不写值的属性就是 `true` |
| `docs/advanced/ii/ui/props.md` | 「泛型顺序」 | 知道 Props / Emits / 事件名联合 / Slots 四位,第二第三要配套 | 只写 Props 时 `emit` 是「没有约束」还是报错;`satisfies SetupComponentOptions<Props>` 省略后两个泛型在示例里是合法的,我加 `emits` 时会不会类型错位 | 少写泛型也能跑,只是少了类型检查 |
| `docs/advanced/ii/ui/component-tsx.md` | 「组件如何映射成一棵子树」 | 知道组件不产生节点、根元素是挂载点、多根成为同一父级的多个子元素 | 多根组件被父级当作一个子元素使用时,父级怎么给它一个 `loc`(第 23 篇 `ItemGrid` 返回行数组,行自带坐标;如果父级只想整体摆它呢) | 多根组件能像单个元素一样被父级定位 |
| `docs/advanced/ii/ui/component-tsx.md` | 「生命周期与渲染树」 | 知道创建/挂载/更新/卸载四段,两个钩子必须同步调用 | 有没有 `onUpdated` / `onBeforeUnmount`;更新阶段能不能拿到「这次 patch 了什么」 | 只有 `onMounted` / `onUnmounted` 两个钩子可用 |
| `docs/advanced/ii/ui/slots-and-attrs.md` | 「slot 解决什么问题」 | 知道 TSX 里 slot 是函数、`?.()` 不能省、具名用对象、作用域 slot 靠 `SlotsType` 对齐 | 用 `SetupComponentOptions` 时第四个泛型与 `slots` 字段怎么写:本篇两个完整例子都用手写 `PanelOptions`,而 12/13 篇又说新组件优先用 `SetupComponentOptions` | 把 `SlotsType` 塞进 `SetupComponentOptions` 第四个泛型就能编译 |
| `docs/advanced/ii/ui/slots-and-attrs.md` | 「attrs:没声明的属性」 | 知道 `inheritAttrs: false` + `{...attrs}`、属性名不改大小写、数组属性按值比较 | `attrs` 里带 `onClick` 展开到 `<text>` 时的绑定时机与内部同名监听冲突时谁生效(只说「注意不要重复」) | 透传的事件会绑上且不会重复 |
| `docs/advanced/ii/ui/builtin-text-and-input.md` | 「TextContent」 | 知道 `width` 必填、`interval` 毫秒、三个事件三个方法、根是 `custom` | 完整属性表在哪:`lineHeight` 只出现过一次(示例写 `lineHeight={4}`),是行距还是行高;`fill` / `fillStyle` 在文本组件上是否与图形语义一致 | `lineHeight={4}` 是行距 4 像素 |
| `docs/advanced/ii/ui/builtin-text-and-input.md` | 「Input」与「InputBox」 | 知道 `v-model:value`、失焦移除真实输入框、取消返回空串、`getInputNumber` 对空串得 `NaN` | `multiline` 的高度怎么定(没有例子);`loc` 六元组里为什么写 `void 0` 而不是省略;`getInput` 的 `width` 与 `loc` 的宽度谁生效 | 多行输入框会按内容长高 |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | 「List」 | 知道行结构、内部选中值、点击后发 `update:selected`、父级初值要等于第一项 | 「挂载之后再改 `selected` 绑定,不会让列表改选另一行」——那我要用方向键换选中、删除当前项后选下一项,该怎么驱动列表?全文没给办法 | 改父级 `selected` 就能换高亮(与 `Page` 的行为相反) |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | 「Scroll」 | 知道总长度取直接子元素最大底边、`scrollTo` 用像素、`padEnd` 补尾 | 子元素宽度写多少:示例视口 220、子元素 200,横向会不会出滚动条;`hor` 没有任何例子 | 写 200 宽的子元素在 220 视口里不会横向滚动 |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 「控制器、实例与栈」 | 知道四层职责、`zIndex = i * 5`、背景固定在 0、`hide/show` 不卸载、`active`/`showBack` 要 `.value` | `keep()` / `unload()` / `safelyUnload()` 在本篇完全没有;它们第一次出现在第 18/19 篇的「关一个、开一个不闪背景」,我回头找不到定义 | 这篇能查到切面板不闪背景该怎么写 |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 「背景的四个名字」 | 知道 `showBack` 是合成结果、`setBackground` 产生 `alwaysShow` 背景实例 | `hide(instance)` 隐藏最后一个面板后,`active` 会不会变假、背景还在不在;`keep` 期间这三个值分别是什么 | 隐藏最后一个面板就等于没开 UI |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 「替换步骤」第二步代码 | 知道替换只有打开处与包装层两个点、入口函数影响所有调用方 | 这里的 `MySettingsProps extends IGameUIPropsBase` 没有 `DefaultProps`,而第 1 篇说「只能用 `IGameUIPropsBase` 配 `DefaultProps`」;少了 `DefaultProps` 会丢什么,我不知道该按哪个 | 照抄这段,组件既能关闭又不会丢通用属性 |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 「做法一」代码块 | 知道要保留 `openSettings(controller, loc)` 的签名 | `IUIController<IGameUIPropsBase>` 从哪 import、泛型参数写什么;和我自己 `props.controller` 的类型是不是一致 | 抄这个签名就能通过类型检查 |
| `docs/advanced/ii/ui/ui-performance.md` | 「症状与排查」表 | 知道六个层次、先做减法、`hidden` 的子树仍占内存 | 「切页闪烁 → 用 `keep` 包住切换」里的 `keep` 仍然没有解释;`keep` 是控制器方法、还是返回一个对象 | 能照这一行写出不闪的切换 |
| `docs/advanced/ii/ui/ui-performance.md` | 「基础 props」 | 知道 `setPropsBaseCreator` 与 `createPropsBase` 的分工、creator 每次渲染都调用 | 我调用 `setPropsBaseCreator` 会不会覆盖客户端创建时设好的那个(第 17 篇说游戏设过),默认 creator 长什么样、要不要手动合并 | 只要把 `state` 带回就不影响原行为 |
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 「骨架在渲染树里的位置」 | 知道 720×480 逻辑尺寸、三个区域坐标、不会为窗口写几套 | 720×480 与第 2 篇说的「画布设计尺寸」是不是一回事;如果客户端画布只有 480×320,这块面板是会被缩放、裁掉还是居中 | 打开后正好铺满可见区域 |
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 「组件与文件怎么分」表 | 知道五个文件的职责与最终 props、只有 `InventoryPanel` 被 `GameUI` 注册 | 表里 `ItemGrid` 的 props 有 `onSelect`、`ActionBar` 有「三个回调」,但这些在接口里写成 `emits`;我该按表里的回调名写 props,还是按 `emits` 写 | 表里的 props 名可以直接照抄 |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | 「ItemGrid:按行列排列」 | 知道列宽/间距公式、`key=item.id`、点击三层上报 | `ItemGrid` 根容器写死 `[0,0,400,280]`,但正文说「网格跟着左侧区域走」;左侧区域尺寸变了要改哪里(props 里没有尺寸) | 只改外层容器尺寸,网格就自适应 |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | 「数据如何进入网格」 | 知道 `items` 由面板持有、传 `items.value`、派生只在面板做一次 | `props.items` 里某一项的 `count` 变化时,`ItemGrid` 会不会重算(数组引用没变,只有内部字段变) | 数量变化会让格子文字更新 |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 「详情区的树结构」 | 知道四块区域、`hidden` 双块、`TextContent` 的 `width` 必填 | 描述区放不下时「在详情内部再套一个 `Scroll`」只有一句,`Scroll` 的 `loc` 与内部 `TextContent` 的 `width` 怎么配合没有例子 | 加一个 `Scroll` 就能滚长描述 |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 「空态与边界」 | 知道三种空情况、删除道具时要同时清 `selectedId` | 删除入口本身在示例里没出现(第 20–25 篇没有真正删道具的按钮),我不知道该在哪一步加、加了之后网格和详情会怎么连锁更新 | 照这段文字就能实现删除 |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 「item-grid.tsx:根节点从单个 container 改成行容器数组」 | 知道组件可以返回行数组、行 `key` 用行号、格子 `key` 用 `item.id` | 行的宽度写死 362,视口 372;换列数或格子尺寸时这 362 要不要跟着算(文档只在示例(二)算过一次总宽) | 改 `columns` 后行宽会自动跟着变 |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 「滚动与事件」 | 知道捕获阶段补滚动偏移、拖动超过阈值才算拖动、可点元素要避开右侧滚动条 | 阈值是多少;拖动结束时如果位移刚好回到起点,会不会同时触发格子的 `onClick` | 拖动时不会误触选中 |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 「状态放在 InventoryPanel」 | 知道 `equippedId` 是单个 id、`canUse` 是派生值、`watch` 只做副作用 | `watch(() => selectedItem.value?.count ?? 0)` 在切换道具时也会触发(文档承认);「改成 `selectedId` 加 `count` 的组合」没有代码,我不知道怎么写 | 照写的 watch 只在数量变化时提示 |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 「键盘收口」 | 知道 `useKey` 在 setup、三条关闭路径最终都走 `close(props.instance)` | 示例面板里 `const key = useKey(...)` 写在 `defineComponent` 的 setup 里,但文档没说这和 `key.implement` 重复调用、以及和 `props.state.hotkey` 取 system 是否要缓存 | 重复调用 `useKey` 不会出问题 |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 「动画作用在树的哪一层」 | 知道 `raf` + `onUnmounted` 停止、只改 `alpha`、动画节点加 `noevent`、不要进子组件 props 链 | 这段代码是片段,`pulse` / `hintAlpha` / `lastHintAt` 的声明位置没有;`watch(hint, ...)` 依赖第 24 篇的 `hint`,我不知道放同一个 setup 里会不会重复 | 抄两段就能动起来 |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 「最终组装的骨架」 | 知道契约表九条、九条里第 6 条给了左侧/右侧/操作条的布局坐标,并说「以本表为准」 | 我照这段写:外层已经是 `container loc={[30,30,660,420]}`,里面又放了 `loc={[30,30,660,420]}` 的呼吸描边和 `loc={[54,52]}` 的标题;按局部坐标它们会再偏移一次,我不知道标题最终在 `(54,52)` 还是 `(84,82)` | 标题在 `(54,52)`,描边与面板主体重合 |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 「注册与打开」 | 知道 `GameUI` 是对象、`index.ts` 统一导出、不要按名字查 | 这里又写「用 `props.controller.keep()` 包住切换,用完调用 `safelyUnload()`」——这是第三次出现,我仍没找到它的定义与返回值 | 能在第 17 篇查到 `keep` 的用法 |
#### D-93 复述检查
**渲染树模型**
- 能复述:画布根 → UI 容器(控制器负责)→ 面板根容器 → 区域容器 → 元素;面板根上方还有 UI 容器,面板之间靠栈顺序递增 `zIndex`,面板内部 `zIndex` 只管兄弟;子元素坐标相对父容器左上角,父级的平移/缩放/旋转复合到整棵子树,锚点同时是变换中心;绘制按 `zIndex` 从小到大、命中从大到小,同值按插入顺序(但见跨篇第 1 条);`hidden` 不绘制不命中但保留实例与状态,三元销毁并重置;容器默认缓存、文字/图片/图形默认不缓存,属性变化把脏标记沿父链上传,`custom` 自绘要自己触发更新;`close` 卸载、`hide` 只切换可见性。
- 不能复述:默认 `zIndex` 是多少;`alpha=0` 的元素是否仍参与绘制/命中;缓存与 `alpha`/`rotate` 叠加时离屏画布的分辨率;`filter` / `composite` 的可用取值;`hidden` 子树里发生的按键作用域是否仍在(这条在 10/17 篇有答案,但和「隐藏的子树不参与命中」放在一起时我要想很久才能分开);多根组件被父级定位的规则。
- 缺什么:一份「元素默认值总表」(尺寸、锚点、颜色、`zIndex`、是否缓存),让我不用在五篇里拼。
**事件模型**
- 能复述:从画布根按 `zIndex` 从大到小找第一个命中元素,命中即停、同级其它元素不参与;捕获从根向内(父先收到 `onClickCapture`),冒泡从命中元素向外(子先收到 `onClick`);`stopPropagation` 只在当前阶段截断传播、不影响同一元素上的其它监听器,也不阻止默认行为;`onClick` 需要按下与抬起都发生在同一元素,`onUp` 先于 `onClick`;`enter` / `leave` 由根节点比较前后悬停集合触发,先 leave 后 enter,父容器不会因为指针移进子元素而 leave;`noevent` 整个子树跳过命中但仍绘制,`hidden` 连绘制一起跳过;`actionStroke` 只按描边命中、宽度等于 `lineWidth`;`offsetX/Y` 是当前元素局部坐标(会做变换逆运算),`absoluteX/Y` 是画布坐标;事件对象有 `type`(本次触发的键)与 `buttons`(当前按住的键),点击判断用 `type`。
- 不能复述:`target` 为什么等于「当前处理事件的元素」、这和我原先对「事件目标」的理解怎么对应;有没有右键/双击/长按事件;`cursor` 除了 `pointer`/`text`/`default` 还有哪些值;拖动内建在 `Scroll` 里的阈值;`onEnter`/`onLeave` 在快速移动/一帧多次移动时的触发次数。
- 缺什么:一张「事件名 → 触发条件 → 有没有捕获版」的完整表;以及 `target` / `offset` 在嵌套与变换下的一个总例子。
**组件**
- 能复述:组件不产生额外节点,根元素才是挂载点,多根就是多个兄弟;props 走「父写属性 → VNode props → 子组件 props 数组 → setup 的 props」四环,没声明的进 `attrs`,默认 `inheritAttrs` 展开到根元素;`emits` 声明后 `onXxx` 不再透传、必须 `emit`;默认值用 `??`、props 不解构;拆组件的依据是复用/状态隔离/渲染范围/数据边界;普通组件只需 `DefaultProps`,UI 还要 `IGameUIPropsBase` 且 props 数组至少含三项三个键;`expose` 只暴露必要方法,父级用 `ref` 在挂载后拿到;内置组件里 `TextContent` / `Textbox` / `Input` / `List` / `ListPage` / `Page` / `Scroll` / `Selection` / `ConfirmBox` / `Choices` 各自的最小用法与 `width` 必填、`Scroll` 只认直接子元素。
- 不能复述:布尔 prop 怎么声明才能用裸属性;用 `SetupComponentOptions` 写 slot(第四个泛型 + `slots` 字段)的完整写法;`List` 的内部选中如何被外部驱动;`keep` / `unload` / `safelyUnload` 的语义与返回值;`props.loc` 是控制器注入还是某个入口函数自己加的参数;`ITexture` 与 `Texture` 的关系;`Font.addFallback` 的调用形式。
- 缺什么:一份「组件属性默认值 / 必填项」的索引,尤其内置组件;以及一份「控制器额外注入的 props 有哪些」的清单。
#### 跨篇问题
只有连续读完全部 25 篇才会遇到的读者困惑。下面每一条都是「我在 A 篇以为是 X,在 B 篇看到 Y,不知道按哪个做」。
1. **同 `zIndex` 时谁在上。** 第 2 篇说「后绘制的先接事件」,第 7、9 篇明确写「同值时后加入的在上层」,第 21 篇的网格直接靠「每格不重叠」绕开它;但第 3 篇说「`zIndex` 相同时按插入顺序,后插入的与先插入的谁在上并不由图形自己决定,需要稳定层叠时显式给 `zIndex`」。我读第 3 篇时以为插入顺序不可依赖,读第 7 篇时又以为可以依赖。最终我不知道该不该在每次 `.map()` 之后显式给 `zIndex`。
2. **`zIndex` 默认值从头到尾没有给。** 第 2 篇第一次讲层级就要求我判断遮挡;第 25 篇又说「遮罩放在第一个子节点、面板主体之前,`zIndex` 不需要额外设置」。我读第 25 篇时默认所有元素 `zIndex` 都是 0,但我从来没有在文档里读到这个数,只能从例子里反推。
3. **布尔属性怎么写,前后两套。** 第 2–7、15 篇大量使用裸属性(`fill`、`stroke`、`cache`、`autoHeight`、`noevent`);第 12、13 篇讲 props 时只说「props 数组写键名字符串」,没有一处说布尔 prop 怎么声明才能让裸属性等于 `true`,也没有说数字属性传进去会不会变字符串。我读前面时以为属性写不写值都行,读 props 篇时又怀疑组件上的裸属性是不是根本没生效。
4. **`keep` 一直在被推荐,却从没被介绍。** 第 18 篇「替换步骤」第四步、第 19 篇症状表与「UI 栈」、第 25 篇「注册与打开」都要求「用 `keep` 包住切换,用完调用 `safelyUnload()` / `unload()`」;但专门讲栈的第 17 篇里没有这三个名字。我按第 17 篇做切换时不会闪,读到后面又被告知要 `keep`,却找不到它挂在哪、返回什么。
5. **`List` 的选中是内部的,和我学到的一切相反。** 第 12、13 篇反复讲「父组件持有状态、子组件只读 props」,第 10 篇的方向键例子用 `ref` 存选中,第 21–25 篇的背包也用父级 `selectedId` 驱动高亮;但第 16 篇说 `List`「挂载之后再改 `selected` 绑定,不会让列表改选另一行」,要用户点击才动。我在第 16 篇之前以为所有组件都能被父级数据驱动。
6. **UI 的 Props 基类到底几件套。** 第 1 篇说「Props 基类只能用 `IGameUIPropsBase` 配 `DefaultProps`」,第 13 篇把这句话写成判定 UI 的三个条件之一;但第 18 篇给出的替换示例 `interface MySettingsProps extends IGameUIPropsBase` 只有前者,还多了一个 `loc: ElementLocator`。我读第 1 篇时以为是硬性要求,读第 18 篇时又以为 `DefaultProps` 可省。
7. **slot 的「标准写法」只在手写选项里出现。** 第 14 篇两次示范 slot,都用自己手写的 `PanelOptions`(`props: (keyof PanelProps)[]`),并在旁边说「新组件优先用 `SetupComponentOptions`」;第 12、13 篇把 `SetupComponentOptions` 当作唯一推荐,第四个泛型只提了一句 `SlotsType<...>`。我读第 12 篇时以为有第四个泛型就够了,读第 14 篇时发现所有能跑的 slot 例子都绕开了它。
8. **默认颜色/样式会不会继承,没有一处说。** 第 3 篇说图形默认色 `#ddd`,第 5 篇说文字默认白;第 12 篇的槽位底板示例给 `g-rectr` 写了 `fillStyle`,但第 2 篇的父容器也写过 `fillStyle`。我读第 5 篇时以为子元素会继承父容器颜色(因为父容器能设 `fillStyle`),读第 3 篇时又以为每个元素各用各的默认值。到底要不要给每个 `text` 都写 `fillStyle`,我无法确定。
9. **图片素材从哪来,文档把我推回编辑器。** 第 6 篇说「加载与解码由你或素材管理器完成」,给了 `loadTexture('/assets/icons/potion.png')` 和 `props.state.materials.getImageByAlias('potion-red')`;但 `advanced/ii/index.md` 明确说编辑器相关内容不在本层,素材别名「由编辑器维护」。我读第 6 篇时以为两种路子都能走,读导览时发现其中一条被划到本层之外。
10. **`Texture` 与 `ITexture` 是不是同一个东西。** 第 6 篇先 `new Texture(canvas)` 传给 `image image={...}`,后面又说 `getImageByAlias` 返回 `ITexture \| null`、取到后「用法与上一节完全一样」。我读前半段时把 `image` 的属性类型理解成 `Texture`,读后半段时又怀疑它接受的是 `ITexture`,两者能不能互换没有一句说明。
11. **面板会出现在屏幕哪里,三篇三种说法。** 第 1 篇说面板根 `[0,0]` 相对 UI 容器、窗口缩放不影响设计坐标;第 2 篇说画布比面板大就占左上角一块、要居中得自己用 `renderer.width` 算;第 20 篇直接给 720×480 并说「UI 被缩放显示时会按逻辑坐标整体变换」。我读第 2 篇时准备自己写居中,读第 20 篇时又以为不用管。
12. **「透明热区」的写法在四篇里被推荐,却没有一篇给写法。** 第 3 篇说细边框可以「在边框下面垫一个透明的填充矩形专门接收点击」,第 7、9、19 篇说遮罩要能挡点击就给一块「铺满的、明确接收事件的背景」,第 25 篇的遮罩又用 `alpha={0.35}` + `noevent`。我读第 3 篇时以为存在一个「透明但命中」的固定写法,读第 25 篇时又以为透明元素本来就会挡住点击。`alpha=0` 到底命中不命中,我到最后也没有依据。
13. **按键系统的两个对象没对齐。** 第 10 篇里 `addCommand` / `deleteCommand` 在 `props.state.hotkey.system` 上,`setGroup` 在 `props.state.hotkey` 上;第 16 篇又出现过 `props.state.hotkey.system` 被直接 `useKey(...)`。我读第 10 篇时把 `hotkey` 当成 system 的容器,读第 24 篇时发现两处都能取,但不知道哪个才是「系统」。
14. **最终组装与骨架的坐标对不上。** 第 20 篇骨架的标题是 `[54, 52]`、面板主体 `[30,30,660,420]`,全部相对根容器;第 25 篇的最终组装先套了一层 `container loc={[30,30,660,420]}`,里面又出现 `loc={[30,30,660,420]}` 的呼吸描边与 `loc={[54,52]}` 的标题,同时还说「以本表为准、前面坐标若不同按这里替换」。我读第 20 篇时已经记住了标题在 `(54,52)`,读第 25 篇时无法判断这层容器到底是「面板主体」还是「根容器」。
15. **UI 的 `loc` 是注入的还是入口函数自己传的。** 第 1、20 篇的 UI 组件根容器写死数字 `loc`,props 数组只有三项三个键;第 17 篇「打开与关闭的完整例子」与第 18 篇的替换示例里,组件写 `loc={props.loc}`,由 `openSettings(controller, loc)` 传进来,props 数组里也多了 `loc`。我读第 1 篇时以为 UI 的位置由自己写死,读第 17 篇时以为位置一律由打开方给。
16. **「打开处」是我自己工程的哪个文件。** 第 1 篇给了三个打开入口并说「第一次验证模板时先用场景控制器」,第 20 篇说「从示例(六)开始统一用主 UI 栈」;但整组文档都没有说主入口文件叫什么、`props` 在组件外从哪来。我读第 1 篇时以为打开代码写在面板文件里,读到第 20 篇时才意识到它必须在别的地方,却仍然不知道在哪。
#### 第 2 轮分诊
| 编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由 | 处理 |
| --- | --- | --- | --- | --- | --- |
| R2-01 | `docs/advanced/ii/ui/ui-template.md`「一个最小 UI」 | import 来自哪些包、TSX 如何编译、新文件如何进入工程 | 是 | 缺前置:照抄无法确定文件接入方式 | 修 |
| R2-02 | `docs/advanced/ii/ui/ui-template.md`「打开与关闭」 | open 写在哪个文件、组件外的 props 从哪来 | 是 | 缺入口:核心流程断点 | 修 |
| R2-03 | `docs/advanced/ii/ui/ui-template.md`「三个基础 props」 | 基类字段、state 成员、能否加自定义键 | 否 | 接口索引属额外深度,不影响继续 | 不修 |
| R2-04 | `docs/advanced/ii/ui/container-and-coordinates.md`「loc 与锚点」 | `zIndex` 默认值、首次挂载的当前尺寸 | 是 | 术语默认值未给,且与同值顺序矛盾(跨篇 1/2) | 修 |
| R2-05 | `docs/advanced/ii/ui/container-and-coordinates.md`「坐标基准与画布」 | 画布设计尺寸具体值、面板根落点 | 是 | 缺前置 + 跨篇三种说法(跨篇 11) | 修 |
| R2-06 | `docs/advanced/ii/ui/basic-shapes.md`「填充、描边与命中」 | 透明热区的具体写法、`alpha=0` 是否命中 | 是 | 缺写法:推荐了做法没给语法(跨篇 12) | 修 |
| R2-07 | `docs/advanced/ii/ui/basic-shapes.md`「图形作为界面零件」 | `g-rectr` 圆角写法、按钮底与文字命中 | 否 | 额外深度,可用简化写法继续 | 不修 |
| R2-08 | `docs/advanced/ii/ui/curves-and-paths.md`「坐标基准」 | 贝塞尔与 path 两种基准如何分辨 | 否 | 设计取舍与组织方式 | 不修 |
| R2-09 | `docs/advanced/ii/ui/curves-and-paths.md`「路径」 | `Path2D` 放 setup 还是模块顶层、能否共享 | 否 | 实现细节,两种写法都可继续 | 不修 |
| R2-10 | `docs/advanced/ii/ui/text.md`「字体」 | `addFallback` 静态还是实例、默认字体字段 | 否 | 可选 API 的补充说明 | 不修 |
| R2-11 | `docs/advanced/ii/ui/text.md`「尺寸与居中」 | `loc` 高度的意义、纵向对齐、颜色继承 | 否 | 前两项额外深度;颜色继承由跨篇 8 单独修 | 不修 |
| R2-12 | `docs/advanced/ii/ui/image-and-texture.md`「加载一张 PNG」 | 素材路径与打包、`ITexture` 与 `Texture` 关系 | 否 | 文档已给两条路径与返回类型;打包属项目范围 | 不修 |
| R2-13 | `docs/advanced/ii/ui/image-and-texture.md`「像素图与高清缓存」 | 开缓存后 `hd` 默认值 | 否 | 额外深度 | 不修 |
| R2-14 | `docs/advanced/ii/ui/layer-transform-performance.md`「变换」 | `filter` / `composite` 的可用取值 | 否 | 文档已明确指向 canvas 对应取值 | 不修 |
| R2-15 | `docs/advanced/ii/ui/layer-transform-performance.md`「缓存与脏更新」 | 旋转缓存分辨率、缓存与 alpha 顺序 | 否 | 实现细节 | 不修 |
| R2-16 | `docs/advanced/ii/ui/reactivity.md`「响应式作为界面零件」 | TSX 里双向绑定到底怎么写 | 是 | 步骤缺失:照字面写不出 | 修 |
| R2-17 | `docs/advanced/ii/ui/reactivity.md`「ref:带 value 的盒子」 | 更新是同步还是微任务 | 否 | 额外深度 | 不修 |
| R2-18 | `docs/advanced/ii/ui/events.md`「事件对象」 | `target` 为当前元素时如何判断点到谁 | 否 | 模型已讲清,处理器可挂在具体元素上 | 不修 |
| R2-19 | `docs/advanced/ii/ui/events.md`「事件名」表 | 右键、双击、长按事件名 | 否 | 额外 API,不影响主流程 | 不修 |
| R2-20 | `docs/advanced/ii/ui/events.md`「enter 与 leave」 | 「每帧」与「每次指针移动」矛盾 | 是 | 明确矛盾 | 修 |
| R2-21 | `docs/advanced/ii/ui/hotkey-in-ui.md`「注册新指令」 | `hotkey` 与 `hotkey.system` 的关系与导入 | 是 | 术语未定义:核心对象未说明(跨篇 13) | 修 |
| R2-22 | `docs/advanced/ii/ui/hotkey-in-ui.md`「方向键移动选中项」 | 与内置 `List` 的选中如何配合 | 否 | 跨篇延伸,不影响本篇示例 | 不修 |
| R2-23 | `docs/advanced/ii/ui/conditional-and-list-rendering.md`「循环」 | 数组能否混 `null`、`cond && <X/>` 的含义 | 否 | 可由现有例子推断 | 不修 |
| R2-24 | `docs/advanced/ii/ui/conditional-and-list-rendering.md`「数据怎么变」表 | 缺「改数组某一项字段」一行 | 否 | `ref` 数组深层响应已覆盖该语义 | 不修 |
| R2-25 | `docs/advanced/ii/ui/props.md`「props 的完整管线」 | 布尔裸属性、数字是否变字符串 | 是 | 缺写法:布尔 prop 无法正确传(跨篇 3) | 修 |
| R2-26 | `docs/advanced/ii/ui/props.md`「泛型顺序」 | 省略泛型时的类型行为 | 否 | 类型层细节 | 不修 |
| R2-27 | `docs/advanced/ii/ui/component-tsx.md`「组件映射成子树」 | 多根组件如何被父级整体定位 | 否 | 设计取舍 | 不修 |
| R2-28 | `docs/advanced/ii/ui/component-tsx.md`「生命周期」 | 是否还有其它生命周期钩子 | 否 | 额外 API | 不修 |
| R2-29 | `docs/advanced/ii/ui/slots-and-attrs.md`「slot 解决什么问题」 | `SetupComponentOptions` 第四泛型与 `slots` 字段写法 | 否 | 手写 `PanelOptions` 的完整例子可照抄 | 不修 |
| R2-30 | `docs/advanced/ii/ui/slots-and-attrs.md`「attrs」 | 透传 `onClick` 与内部同名监听谁生效 | 否 | 边界情况 | 不修 |
| R2-31 | `docs/advanced/ii/ui/builtin-text-and-input.md`「TextContent」 | `lineHeight` 是行距还是行高 | 是 | 术语未定义,示例正在使用 | 修 |
| R2-32 | `docs/advanced/ii/ui/builtin-text-and-input.md`「Input」 | `multiline` 高度、`void 0`、`getInput` 宽度 | 否 | 示例可照抄 | 不修 |
| R2-33 | `docs/advanced/ii/ui/builtin-list-and-containers.md`「List」 | 外部如何驱动 `List` 的选中 | 否 | 文档明确的组件限制(设计取舍) | 不修 |
| R2-34 | `docs/advanced/ii/ui/builtin-list-and-containers.md`「Scroll」 | 子元素宽度与横向滚动、`hor` 例子 | 否 | 额外深度 | 不修 |
| R2-35 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「控制器、实例与栈」 | `keep` / `unload` / `safelyUnload` 无定义 | 是 | 缺前置:后续三篇都在用(跨篇 4) | 修 |
| R2-36 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「背景的四个名字」 | `hide` 最后一个面板后的 `active` 与背景 | 否 | 语义细节,可避开 | 不修 |
| R2-37 | `docs/advanced/ii/ui/replace-builtin-ui.md`「替换步骤」 | 示例未并 `DefaultProps`,与第 1 篇说法冲突 | 是 | 明确矛盾(跨篇 6) | 修 |
| R2-38 | `docs/advanced/ii/ui/replace-builtin-ui.md`「做法一」 | `IUIController` 的 import 与泛型 | 否 | 代码块已给出 import 与泛型 | 不修 |
| R2-39 | `docs/advanced/ii/ui/ui-performance.md`「症状与排查」 | `keep` 仍未解释 | 是 | 同 R2-35(跨篇 4) | 修 |
| R2-40 | `docs/advanced/ii/ui/ui-performance.md`「基础 props」 | `setPropsBaseCreator` 是否覆盖客户端设置 | 否 | 高级配置,非自定义 UI 必需 | 不修 |
| R2-41 | `docs/advanced/ii/ui/inventory-example-1-skeleton.md`「骨架在渲染树里的位置」 | 720×480 与 480×320 画布的关系 | 是 | 跨篇矛盾(跨篇 11) | 修 |
| R2-42 | `docs/advanced/ii/ui/inventory-example-1-skeleton.md`「组件与文件怎么分」 | 表里 props 与 `emits` 该按哪个写 | 是 | 明确矛盾:表与声明方式不一致 | 修 |
| R2-43 | `docs/advanced/ii/ui/inventory-example-2-grid.md`「按行列排列」 | 根容器写死尺寸、外层变化如何联动 | 否 | 维护性偏好 | 不修 |
| R2-44 | `docs/advanced/ii/ui/inventory-example-2-grid.md`「数据如何进入网格」 | 内部字段变化是否触发重算 | 否 | 第 11/24 篇已覆盖深层响应 | 不修 |
| R2-45 | `docs/advanced/ii/ui/inventory-example-3-detail.md`「详情区的树结构」 | 详情内再套 `Scroll` 的写法 | 否 | 额外深度 | 不修 |
| R2-46 | `docs/advanced/ii/ui/inventory-example-3-detail.md`「空态与边界」 | 删除入口不在示例中 | 否 | 示例范围 | 不修 |
| R2-47 | `docs/advanced/ii/ui/inventory-example-4-scroll.md`「行容器数组」 | 行宽 362 是否随列数变化 | 否 | 额外深度 | 不修 |
| R2-48 | `docs/advanced/ii/ui/inventory-example-4-scroll.md`「滚动与事件」 | 拖动阈值、回原位是否误触点击 | 否 | `Scroll` 内部实现 | 不修 |
| R2-49 | `docs/advanced/ii/ui/inventory-example-5-state.md`「状态放在 InventoryPanel」 | `selectedId` + `count` 组合没有代码 | 否 | 文档已给出组合思路,可按需实现 | 不修 |
| R2-50 | `docs/advanced/ii/ui/inventory-example-5-state.md`「键盘收口」 | 重复 `useKey` 与缓存 `system` | 否 | 与 R2-21 同根因,修 R2-21 即可 | 不修 |
| R2-51 | `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`「动画作用在树的哪一层」 | 片段缺 `pulse` / `hintAlpha` / `lastHintAt` 声明 | 否 | 文档同一代码块已声明 | 不修 |
| R2-52 | `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`「最终组装的骨架」 | 外层容器与内部坐标重复偏移 | 是 | 明确矛盾(跨篇 14) | 修 |
| R2-53 | `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`「注册与打开」 | `keep` 第三次出现仍无定义 | 是 | 同 R2-35(跨篇 4) | 修 |
#### 跨篇问题分诊
| 编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由 | 处理 |
| --- | --- | --- | --- | --- | --- |
| R2-54 | 跨篇 1:`basic-shapes` / `layer-transform-performance` / `events` | 同 `zIndex` 时谁在上,三篇说法不同 | 是 | 明确矛盾 | 修 |
| R2-55 | 跨篇 2:`container-and-coordinates` / `inventory-example-6` | `zIndex` 默认值从未给出 | 是 | 术语默认值未定义 | 修 |
| R2-56 | 跨篇 3:`props` / `component-tsx` | 布尔裸属性与数字传参前后两套说法 | 是 | 缺写法 | 修 |
| R2-57 | 跨篇 4:`ui-controller-and-stack` / `ui-performance` / `inventory-example-6` | `keep` 被反复推荐但无定义 | 是 | 缺前置 | 修 |
| R2-58 | 跨篇 5:`builtin-list-and-containers` | `List` 选中由内部持有,与父级驱动相反 | 否 | 组件限制(设计取舍) | 不修 |
| R2-59 | 跨篇 6:`ui-template` / `replace-builtin-ui` | UI Props 基类是否必须并 `DefaultProps` | 是 | 明确矛盾 | 修 |
| R2-60 | 跨篇 7:`slots-and-attrs` / `props` / `component-tsx` | slot 的推荐写法只在手写选项里出现 | 否 | 手写示例可运行 | 不修 |
| R2-61 | 跨篇 8:`text` / `basic-shapes` | 颜色与样式是否从父容器继承 | 是 | D-93 模型未讲清 | 修 |
| R2-62 | 跨篇 9:`image-and-texture` / `advanced/ii/index.md` | 素材别名与编辑器边界 | 否 | 编辑器边界,文档已说明 | 不修 |
| R2-63 | 跨篇 10:`image-and-texture` | `Texture` 与 `ITexture` 是否可互换 | 否 | 文档已给返回类型与用法 | 不修 |
| R2-64 | 跨篇 11:`ui-template` / `container-and-coordinates` / `inventory-example-1` | 面板落点三篇三种说法 | 是 | 明确矛盾 | 修 |
| R2-65 | 跨篇 12:`basic-shapes` / `layer-transform-performance` / `events` | 透明热区被推荐但无写法、`alpha=0` 是否命中 | 是 | 缺写法 | 修 |
| R2-66 | 跨篇 13:`hotkey-in-ui` | `hotkey` 与 `hotkey.system` 两个对象未对齐 | 是 | 术语未定义 | 修 |
| R2-67 | 跨篇 14:`inventory-example-6` | 最终组装与骨架坐标对不上 | 是 | 明确矛盾 | 修 |
| R2-68 | 跨篇 15:`ui-template` / `ui-controller-and-stack` / `replace-builtin-ui` | UI 的 `loc` 是注入还是打开方传入 | 是 | 缺前置 | 修 |
| R2-69 | 跨篇 16:`ui-template` / `inventory-example-1` | 打开处到底在哪个工程文件 | 是 | 缺入口 | 修 |
第 2 轮阻断数:29
第 2 轮非阻断数:40
概率继承:Round 1 的 178 行分节概率继续有效;本轮新增/重写章节需补该节概率。
状态:已汇总
以下按轮追加;历史轮次逐字保留,不得覆盖、合并或改写。
#### 第 2 轮修订
R2-01:已修 → `docs/advanced/ii/ui/ui-template.md#一个最小 UI`:补三个 import 包来源、TSX 编译与文件接入说明。
R2-02:已修 → `docs/advanced/ii/ui/ui-template.md#文件放在哪里、怎么被用到`:补 `src/bootstrap.ts` 组件外打开示例,并说明 `loc` 不是控制器注入。
R2-04:已修 → `docs/advanced/ii/ui/container-and-coordinates.md#loc 与锚点`、`docs/advanced/ii/ui/basic-shapes.md#绘制顺序`:补 `zIndex` 默认值 `0`,统一同值按插入顺序、后加入在上层且先被命中。
R2-05:已修 → `docs/advanced/ii/ui/container-and-coordinates.md#坐标基准与画布`:补示例画布 480×320 与面板根落点说明。
R2-06:已修 → `docs/advanced/ii/ui/basic-shapes.md#actionStroke`:补透明热区写法 `alpha={0}`,说明命中按几何范围、不看透明度。
R2-16:已修 → `docs/advanced/ii/ui/reactivity.md#响应式作为界面零件`:补 TSX 中 `open` + `onUpdate:open` / `onToggle` 的写法。
R2-20:已修 → `docs/advanced/ii/ui/container-and-coordinates.md#enter 与 leave`:把「每帧比较」改为「每次指针移动后比较」。
R2-21:已修 → `docs/advanced/ii/ui/hotkey-in-ui.md#注册新指令与分组`:补 `hotkey` 门面与 `hotkey.system` 的关系及导入来源。
R2-25:已修 → `docs/advanced/ii/ui/props.md#props 的完整管线`:补裸属性为 `true`、数字表达式不变字符串。
R2-31:已修 → `docs/advanced/ii/ui/builtin-text-and-input.md#TextContent`:补 `lineHeight` 是行间距(默认 0),与 `List` 的行高不同。
R2-35:已修 → `docs/advanced/ii/ui/ui-controller-and-stack.md#keep`:新增小节,给出 `keep()` / `safelyUnload()` / `unload()` 的签名与语义。
R2-37:已修 → `docs/advanced/ii/ui/replace-builtin-ui.md#替换步骤`:说明 `DefaultProps` 是类型提示的推荐写法,不是运行要求。
R2-39:已修 → 同 R2-35:第 17 篇新增 `keep` 定义,第 19 篇的引用已可达。
R2-41:已修 → `docs/advanced/ii/ui/inventory-example-1-skeleton.md#骨架在渲染树里的位置`:补 720×480 与 `renderer.width/height` 的层级关系。
R2-42:已修 → `docs/advanced/ii/ui/inventory-example-1-skeleton.md#组件与文件怎么分`:说明表中 `onSelect` / `onClear` 是父级监听器名,子组件用 `emits` 声明。
R2-52:已修 → `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md#最终组装的骨架`:外层容器改为 `[0, 0, 720, 480]`,面板底改为 `[30, 30, 660, 420]`,并补坐标基准说明。
R2-53:已修 → 同 R2-35:第 17 篇新增 `keep` 定义,第 25 篇的引用已可达。
R2-54:已修 → 同 R2-04(`basic-shapes` 同值顺序)。
R2-55:已修 → 同 R2-04(`container-and-coordinates` 默认值)。
R2-56:已修 → 同 R2-25(`props` 布尔/数字)。
R2-57:已修 → 同 R2-35(`keep` 定义)。
R2-59:已修 → 同 R2-37(`DefaultProps` 口径)。
R2-61:已修 → `docs/advanced/ii/ui/text.md#尺寸与居中`:补颜色与样式不从父容器继承。
R2-64:已修 → 同 R2-05 / R2-41(画布与面板落点)。
R2-65:已修 → 同 R2-06(透明热区写法)。
R2-66:已修 → 同 R2-21(`hotkey` 与 `system`)。
R2-67:已修 → 同 R2-52(最终组装坐标)。
R2-68:已修 → 同 R2-02(`loc` 非注入)。
R2-69:已修 → 同 R2-02(组件外打开处)。
第 2 轮修订完成:阻断 29 条,已修 29 条,未修 0 条。
### 第 3 轮
用户更正(2026-11-01):Round 3 仍为一个读者读完全部 25 篇;读者使用新上下文,未看前两轮问题清单。
#### 读者
单读者,人格与 Round 2 相同:
> 你是一位刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。你完全没写过 UI,不知道 canvas 是什么,也不会 Vue 的组件写法;你只掌握了基础 TS/JS、函数、对象、数组和一点点模板语法。你手里只有这套文档,不能看源码,也没有人可以问。你的任务不是评价文档好坏,而是老老实实按顺序读,读到哪里卡住就记下:我在哪一段卡住、我从文档里已经知道什么、我还缺什么才能继续往下做。
阅读范围(25 篇,按顺序):
1. `docs/advanced/ii/ui/ui-template.md`
2. `docs/advanced/ii/ui/container-and-coordinates.md`
3. `docs/advanced/ii/ui/basic-shapes.md`
4. `docs/advanced/ii/ui/curves-and-paths.md`
5. `docs/advanced/ii/ui/text.md`
6. `docs/advanced/ii/ui/image-and-texture.md`
7. `docs/advanced/ii/ui/layer-transform-performance.md`
8. `docs/advanced/ii/ui/reactivity.md`
9. `docs/advanced/ii/ui/events.md`
10. `docs/advanced/ii/ui/hotkey-in-ui.md`
11. `docs/advanced/ii/ui/conditional-and-list-rendering.md`
12. `docs/advanced/ii/ui/props.md`
13. `docs/advanced/ii/ui/component-tsx.md`
14. `docs/advanced/ii/ui/slots-and-attrs.md`
15. `docs/advanced/ii/ui/builtin-text-and-input.md`
16. `docs/advanced/ii/ui/builtin-list-and-containers.md`
17. `docs/advanced/ii/ui/ui-controller-and-stack.md`
18. `docs/advanced/ii/ui/replace-builtin-ui.md`
19. `docs/advanced/ii/ui/ui-performance.md`
20. `docs/advanced/ii/ui/inventory-example-1-skeleton.md`
21. `docs/advanced/ii/ui/inventory-example-2-grid.md`
22. `docs/advanced/ii/ui/inventory-example-3-detail.md`
23. `docs/advanced/ii/ui/inventory-example-4-scroll.md`
24. `docs/advanced/ii/ui/inventory-example-5-state.md`
25. `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`
#### 逐篇提问
| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 |
| --- | --- | --- | --- | --- |
| `docs/advanced/ii/ui/ui-template.md` | 「一个最小 UI」 | 四段结构:Props 类型、props 列表、组件、`GameUI`;三个包各给什么;三个注入值 | 我不知道 `satisfies` 是什么语法;也不知道「模板工程已经配置好 TSX 编译」里的模板工程在哪、拿到后用什么命令跑起来 | 我会把这段抄成一个 `.tsx`,但下一步是编译、预览还是直接放进游戏,我判断不了 |
| `docs/advanced/ii/ui/ui-template.md` | 「文件放在哪里、怎么被用到」 | 文件放 `src/client/ui/<name>.tsx`,加入 `index.ts` 统一出口;没有目录扫描 | `@motajs/system`、`@motajs/render-vue`、`@user/client-base` 这些别名实际指向哪个目录;`src` 是仓库里的哪个根 | 我会去建文件、写 export,但找不到验证「它真的被加载」的办法 |
| `docs/advanced/ii/ui/ui-template.md` | 「这份模板在渲染树里的位置」 | Vue 组件树 → 元素渲染树 → 画布根;UI 容器在面板根之上 | 画布根和 UI 容器由谁创建;如果我不走 `GameUI`、想自己挂一棵树,入口是什么;`custom` 元素是什么 | 我能复述三层,但只会通过 `open` 间接用它们,不能自己搭根 |
| `docs/advanced/ii/ui/container-and-coordinates.md` | 「坐标从哪里来」「loc 与锚点」 | 子元素坐标相对父容器;`loc` 是六元组;锚点决定哪个点落在 x/y;默认尺寸 200×200 | 只写 `x`/`y` 时「沿用当前尺寸」,初始当前尺寸到底是多少;前两篇元素层示例里的 `Container`、`Rect` 没写 import,我不知道从哪来 | 照抄嵌套位置是对的;某个漏写尺寸的容器会变成 200×200,可能盖住邻居 |
| `docs/advanced/ii/ui/container-and-coordinates.md` | 「层级」「事件在嵌套容器中的路径」 | zIndex 只在同父级比较;绘制从小到大、命中从大到小;`hidden`/`noevent` 差别 | 这里出现的 `absoluteX`/`absoluteY` 只被提到没定义;`stopPropagation` 的完整边界被推到第 9 篇 | 调父级 zIndex 能盖住旁支;细节要等第 9 篇才敢用 |
| `docs/advanced/ii/ui/basic-shapes.md` | 「填充、描边与命中」的代码块 | `fill`/`stroke` 是模式开关;颜色在 `fillStyle`/`strokeStyle`;`strokeAndFill` 优先 | 示例里 `{/* ... */}` 与行尾 `;` 穿插,我不知道整段是放进 render 的一次性演示,还是可以在组件里逐条写 | 我照搬会得到语法错误,或者只画出一个图形 |
| `docs/advanced/ii/ui/basic-shapes.md` | 「图形作为界面零件」表 | 按钮底、分隔线、半透明遮罩的常用组合;文字默认会接事件 | `g-rectr` 的 `circle` 在这里只出现 `[16]`,完整四角/椭圆规则在第 4 篇;我现在只会单值圆角 | 简单底板能画,想做不同角要翻到下一篇 |
| `docs/advanced/ii/ui/curves-and-paths.md` | 「路径」「圆角矩形」 | `Path2D` 是浏览器全局;贝塞尔点相对父容器;`circle` 1–4 项、`ellipse` 2/4/6/8 项的映射表 | 我不知道 TS 里用 `Path2D` 要开什么编译配置;三项圆角「右上与左下共用第 2 项」我在几何上还原不出来 | 单值圆角和折线能画;三项圆角可能画成不是我想要的样子 |
| `docs/advanced/ii/ui/text.md` | 「字体」的 `addFallback` | `Font` 构造是位置参数;`Font.clone/defaults/setDefaults` 的用法 | `addFallback` 是静态方法还是实例方法、参数是什么、返回值是什么,全文没有示例 | 想加后备字体时卡住,只能先跳过 |
| `docs/advanced/ii/ui/text.md` | 「尺寸与居中」 | 文字宽高由测量决定;给 `width`/`height` 不裁剪;居中用锚点 0.5 | 测量发生在首帧前还是挂载后;我在 setup 里读不到尺寸时,该用 `onMounted` 还是等事件,没有说明 | 居中能对;「先量尺寸再排版」的场景不知道怎么接 |
| `docs/advanced/ii/ui/image-and-texture.md` | 「从素材管理器取纹理」 | `props.state.materials.getImageByAlias` 返回 `ITexture \| null`;取不到先走占位 | 第 13 篇说普通子组件不要接 `state`,那抽成深层图标组件后怎么拿 materials?只能层层传 prop 吗;`ITexture` 能不能直接给 `image` 属性 | 顶层 UI 能取图,拆成子组件后我不知道图从哪来 |
| `docs/advanced/ii/ui/image-and-texture.md` | 「边界与注意」末条 | 纹理不要在组件卸载后继续被引用 | 「按纹理自身的生命周期处理」没有给释放方法名或时机 | 小图我不管;长期反复开关的面板可能泄漏,但我不会判断 |
| `docs/advanced/ii/ui/layer-transform-performance.md` | 「缓存与脏更新」「filter 与 composite」 | 默认缓存/不缓存表;`nocache` 优先;脏标记沿父链上传 | `custom` 自定义绘制里「主动触发一次更新」的方法名没给;`container-custom`、`template` 两个默认缓存项全文没定义;filter/composite 说「再查对应取值」但没有入口 | 普通属性变化能自动重画;自定义绘制、滤镜、`template` 只能停在概念 |
| `docs/advanced/ii/ui/reactivity.md` | 「什么时候会重渲染」 | 依赖收集、组件级重跑、元素级 patch、`nextTick`、解构丢响应式 | `shallowRef` 的适用场景我还不会判断;`watch` 的 deep/immediate 没讲,我要监听对象内部时不确定 | 计数器能跑;监听对象内部字段可能漏更新 |
| `docs/advanced/ii/ui/events.md` | 「事件对象」 | `target/touch/type/buttons/identifier/offsetX/absoluteX/stopPropagation` 的含义 | `MouseType` 只出现 `Left`、`None`;右键/中键/滚轮的完整取值、`wheelType` 的单位枚举都没列;`onMove` 是否只在指针位于元素上时触发也没说 | 左键点击没问题;右键、中键、滚轮单位要靠试 |
| `docs/advanced/ii/ui/events.md` | 「stopPropagation」表 | 在捕获/冒泡各位置调用的日志结果;它不阻止同元素同事件的其它监听器 | 同一元素怎么挂两个 `onClick`、执行顺序如何,文档只说「都会执行完」 | 单监听器行为清楚;多监听器只能猜 |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | 「触发方式:HotkeyEmitMode」 | 三种模式;`timeout`/`interval`/`dt` 都是最小间隔不是精确计时 | 「激励源」是什么没定义;`Continuous` 的「按住后按激励源持续触发」我无法映射到代码 | `Once`/`KeyUp` 能用;`Continuous` 不敢开 |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | 「注册新指令与分组」 | `addCommand`/`defaults`/`setGroup`/`deleteCommand`;组合键组内最后一个是主键 | `KeyCode` 没有完整键名表,只有几个例子;三键组合怎么写没有示例 | 常用键能注册;冷门键要猜名字,三键组合要试 |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | 「循环:用 map 生成元素」 | `map` 返回数组成为父容器子元素;固定顺序可不加 `key` | 返回数组是否需要 Fragment 或外层容器;组件返回多根的写法还没给 | 单个容器内的 `map` 能跑 |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | 「key:只在需要保留身份时加」 | `key` 只在同父级兄弟间唯一;组件标签上写;不要用下标 | `key` 加错位置的具体症状我只有一句结论,没有可对照的反例 | 我会加 `key`,但不确认加错时看到什么 |
| `docs/advanced/ii/ui/props.md` | 「组件怎么拿参数」「属性名用 camelCase」 | 四环管线;`props` 数组;`emits`;camelCase;默认值用 `??` | 第 1 篇说「模板指令不适用」,这里 `v-model:selected` 又作为 TSX 写法出现;我无法判断哪些 `v-` 前缀在 TSX 能用 | 普通 props 能通;抄 `v-model` 可能编译不过或语义不对 |
| `docs/advanced/ii/ui/props.md` | 「泛型顺序」 | 四个泛型;第二三要配套;只写 Props 时 `emit` 无约束 | `SetupComponentOptions` 的 `satisfies` 与 `defineComponent` 的两处泛型必须手抄一致,我没有类型报错时的排查方法 | 照抄能过;改一个事件名可能整片飘红,我不知道先改哪 |
| `docs/advanced/ii/ui/component-tsx.md` | 「组件如何映射成一棵子树」 | 组件不产生节点;根元素是挂载点;多根成为同父级多个子元素 | 多根在 TSX 里具体返回数组还是 Fragment,示例没给;根元素尺寸为 0 会让点击落空只在第 14 篇提到 | 单根组件没问题;多根要试 |
| `docs/advanced/ii/ui/component-tsx.md` | 「expose、emit 与父组件拿子组件」 | `ref` 拿实例;`expose` 只暴露必要方法;挂载前 `undefined` | `ref<CardExpose>()` 的泛型为什么写成 expose 类型而不是组件类型;没有 `expose` 时父组件拿到什么类型 | 照抄 `expose` 可用;不 expose 的情况不敢依赖 |
| `docs/advanced/ii/ui/slots-and-attrs.md` | 「具名 slot」「attrs」 | TSX 里 slot 是函数;具名 slot 用对象;`{...attrs}`;`inheritAttrs` | 手写 `PanelOptions` 与 `SetupComponentOptions` 的兼容边界;`attrs` 里混入事件监听时的类型 | 默认 slot 能显示;具名对象形式容易漏 `default` |
| `docs/advanced/ii/ui/slots-and-attrs.md` | 「组件边界上的事件与属性」 | `emits` 声明后 `onXxx` 被消费、不再透传;四条「点了没反应」原因 | 「包装组件要转发全部 props、attrs、slots、emits」没有给完整骨架 | 做包装层时会漏,漏了只看到没反应 |
| `docs/advanced/ii/ui/builtin-text-and-input.md` | 「特殊组件 InputBox」 | `getInput`/`getInputNumber` 返回 Promise;`loc`/`width` 语义;取消返回空串/NaN | 参数里的 `void 0` 占位我不熟;`props?` 能传什么没列;弹窗被外部关闭时 Promise 不结束,我要怎么兜底取消 | 正常确认/取消可用;异常关闭会挂住 |
| `docs/advanced/ii/ui/builtin-text-and-input.md` | 「事件与渲染树」 | `TextContent` 根是 `custom`;`Input` 根是 `container`;`Textbox` 根是 `container` | `custom` 元素本身全文没定义(第 7 篇也出现过),我不知道它和 `container` 的差别 | 点击冒泡能工作;`custom` 的行为只能靠试 |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | 「List:可选中的列表」 | `list`/`selected`;初值取第一项;点击更新内部值并 `emit` | 父级代码怎么主动改选中?文档说挂载后改绑定不会改选,又没给方法;对比 `Page` 可以外部改 `page`,我不知道 `List` 的受控边界 | 用户点击正常;程序化选中做不到 |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | 「弹窗与一次性提示」 | `getConfirm`/`getChoice`;返回语义;弹窗压在栈顶 | `Tip` 被提到但从未介绍;`getChoice` 没有取消分支,外部关闭时怎么收尾没给 | 确认框可用;`Tip` 不知道是什么 |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 「场景 UI 与主 UI」 | 两个控制器;主 UI 容器在 `active` 假时整体隐藏 | `mainUIController.render()` 要放进哪个容器、放在主场景组件哪里,我没有主场景代码可对照 | 能 `open`;不知道怎么接到自己的游戏画面 |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 「事件归属与生命周期」 | 第 i 层 zIndex 是 i*5;`hide` 不卸载;`close` 卸载并清缓存 | `setPropsBaseCreator` 我作为 UI 作者要不要调用、调用时机;文档说游戏创建客户端时设置,但我找不到那一步 | 默认注入能用;自定义 creator 不敢动 |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 「替换步骤」第二步 | 保留入口函数/换对象;包装层;组件要接 `controller`/`instance`/`state`/`loc` | `loc` 到底由谁传(`open` 的 vBind 还是控制器)我仍不确定;第 17 篇只说容器渲染实例,没说 `loc` 注入 | 照抄能打开;不传 `loc` 时面板位置不明 |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 「一个最小替换示例」末段 | 保留 Esc 要 `useKey`;按键属于作用域 | 「注册与内置面板相同的指令」——`@common/exit` 已存在,我该 `implement` 还是 `addCommand`?用词让我不确定 | 可能重复注册,或者根本没接上 |
| `docs/advanced/ii/ui/ui-performance.md` | 「观测与验证」 | 六层症状表;先做减法;录性能面板;一次只改一个开关 | 「在渲染函数里临时计数」怎么写、帧时间在哪看;文档不给毫秒数,我需要一个可执行的判断阈值 | 知道方向,但无法量化「改前改后」 |
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 「骨架代码」「打开它」 | 720×480 根、各区域坐标、关闭路径、三个打开入口 | 没有「把文件放进工程后如何编译/预览」的步骤;画布 480×320 与面板 720×480 的溢出只被说明、没给适配做法 | 代码能写;实际画面可能只看到左上角一块 |
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 「组件与文件怎么分」表 | 五个文件职责与最终 props;`InventoryPanel` 是唯一 `GameUI` | 表里把 `onSelect`/`onClear` 写成 props,正文又说内部是 `emits`;我照父级用法可以,但自己建文件时不确定类型接口要不要包含回调 | 父级调用对;子组件声明容易漏 |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | 「数据模型:Item 只定义一次」 | `Item` 四字段;`id` 稳定;`items` 用 `ref` | `Item` 定义在哪个文件、其它四个文件怎么 import,没给 export 语句和路径 | 复制到多文件时类型对不上 |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | 「ItemGrid:按行列排列」 | 列/行计算;`key` 用 `item.id`;定位容器与格子同尺寸 | 根容器尺寸写死 400×280,与 props 无关;区域尺寸变了怎么传进去没讲 | 网格能排;改区域尺寸要手改常量 |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 「详情区的树结构」 | 四块;两个 `hidden` 分支;`TextContent` 的 `width` 必填 | 两个 `container hidden` 没写 `loc`,按第 2 篇默认 200×200;我不确定这是有意还是会被默认尺寸影响命中 | 视觉可能对;点击与遮挡要试 |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 「空态与边界」 | `null` 收口;删除时清理 `selectedId`;三种空态 | 删除道具的函数第 5 篇才出现,这里只说「要在面板层处理」 | 空态能显示;删除流程要等第 5 篇 |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 「数据与选中态如何穿过滚动层」 | `ItemGrid` 根从单容器改成行容器数组;行 `key` 用行号,格子 `key` 用 id | `Scroll` 的「直接子元素」是否跨越组件边界——`ItemGrid` 是组件,返回数组后这些行算不算 `Scroll` 的直接子元素?这是虚拟滚动能否成立的关键,文档只给结论没给判定方法 | 照抄可能滚不动,因为行其实在组件子树下 |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 「面板里怎么接」 | `padEnd`、`scrollTo`、`getScrollLength`、`ScrollExpose` | `scrollTo(y, time)` 的 `time` 单位没写(毫秒?帧?);`padEnd` 是像素还是比例 | 滚动能滚;动画时长和补长只能试 |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 「状态放在 InventoryPanel」 | `computed`/`watch` 分工;`item.count -= 1` 会触发重渲染;`equippedId` 只存 id | 「只在同一道具数量变化时提示」只给了一句文字,没有代码;现在的 `watch` 来源会因切换选中而误触发 | 提示会误触发,需要自己补判断 |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 「已装备的格子:三处一起改」 | 接口、`props` 数组、渲染三处必须同步;描边优先级 | 这里又用了 `ItemCellEmits`,但没重新给出定义;我要确认它还是第 2 篇那个 | 照抄能过;跨文件类型要回翻 |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 「动画作用在树的哪一层」 | `requestAnimationFrame` 循环;`onUnmounted` 取消;只改 `alpha` | `requestAnimationFrame`/`performance.now()` 在目标环境是否可用;`transitioned`/`transitionedColor` 被提到但没有文档入口 | 动画能跑;想用渐变工具找不到用法 |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 「最终组装与契约核对」 | 九条契约;最终骨架;坐标相对 720×480 根容器 | 最终骨架比第 1 篇多了一层 `container [0,0,720,480]` 包住主体与按钮,我不知道这层是不是必须、以后加内容该往哪层放 | 照抄能显示;扩展时层级容易放错 |
#### D-93 复述检查
**渲染树**
能复述:画布根 → UI 容器 → 面板根容器 → 区域容器 → 叶子元素。父子关系只有 TSX 嵌套和 `appendChild` 两种建立方式。子元素坐标相对父容器,父级的平移/缩放/旋转复合到子级,锚点是变换中心。`zIndex` 只在同父级兄弟间比较,绘制从小到大,命中从大到小,同值按插入顺序(后插入在上)。生命周期上,`hidden` 保留实例与状态只跳过绘制与命中,三元/`key` 变化会卸载重建。缓存默认按标签区分(container/custom/container-custom 默认开,text/image/template/g-* 默认不开),脏标记沿父链上传。
不能复述 / 缺什么:
- 不经过 `GameUI` 时,画布根和 UI 容器由谁创建、我能不能自己挂一棵树,这条链路没有可执行入口。
- `custom`、`container-custom`、`template` 三个元素名字反复出现在缓存表里,但没有一处像第 3 篇介绍四个图形那样介绍它们。
- 在 `custom` 里改外部数据后「主动触发一次更新」的方法名缺失,我不知道缓存脏标记怎么手动打。
- 组件边界不算节点(第 13 篇),但 `Scroll` 又要求「直接子元素」(第 16/23 篇);多根组件返回的数组是否算 `Scroll` 的直接子元素,我没有判定依据。
- 画布适配:第 2 篇说按 `renderer.width`/`height` 算,第 20 篇又直接写 720×480 压在 480×320 上;我复述不出「实际运行时到底以哪个为准」。
**事件**
能复述:指针从画布根开始,每层按 `zIndex` 从大到小找第一个命中元素;命中后捕获从根向内、冒泡从命中元素向外,完整顺序是「父捕获 → 子捕获 → 子冒泡 → 父冒泡」。图形按几何轮廓命中,`actionStroke` 只算描边。`stopPropagation` 只停止继续传播,不阻止同元素同事件名的其它监听器。`enter`/`leave` 不走冒泡,由根维护悬停集合做差集,先 leave 后 enter。`noevent` 仍绘制但整棵子树跳过命中,事件下穿;`hidden` 连绘制一起跳过。`offsetX/Y` 是当前元素局部坐标,经过变换反算;`absoluteX/Y` 是画布坐标。
不能复述 / 缺什么:
- `MouseType`/`WheelType`/`KeyCode` 都只出现零散取值,没有完整枚举表;右键、中键、滚轮单位我复述不出。
- 同一元素多个同事件监听器的写法与顺序,只有一句「都会执行完」。
- 组件根元素在命中里的角色:根容器尺寸为 0 时点击落空只在第 14 篇一句带过;多根组件哪个是命中入口没有说。
- 触摸多指只讲了 `identifier` 用来串起按下/移动/抬起,具体事件序列与浏览器默认行为的关系没有展开。
**组件**
能复述:普通组件继承 `DefaultProps`,UI 必须同时继承 `IGameUIPropsBase` 与 `DefaultProps`,且 `props` 数组至少含 `controller`/`instance`/`state`。props 走「父写属性 → VNode props → 声明数组挑键 → setup」四环,没声明的进 `attrs`,默认透传到根元素,`inheritAttrs: false` 可关。默认值用 `??`,不要解构。事件用 `emits` 声明,`v-model:xxx` 对应 `xxx` + `onUpdate:xxx`。slot 在 TSX 里是函数,具名 slot 用对象传。拆分依据是复用、状态隔离、渲染范围、数据边界。
不能复述 / 缺什么:
- `defineComponent` / `SetupComponentOptions` / `SlotsType` 的完整类型骨架我只能照抄,不能自己从零写对。
- 「模板指令不适用」与 `v-model:`、`v-if`、`v-model:value` 的关系我复述不出统一规则。
- 普通子组件不接 `state`,但 `state.materials`、`state.hotkey` 又要用;深层组件怎么拿到这些,我复述不出标准做法。
- 内置组件的受控模型不统一:`Input` 跟外部值、`Page` 跟外部页、`List` 挂载后不跟外部选中;我复述不出一个通用判断。
- `GameUI` 只是「名字 + 组件」的容器、不注册;但「谁在什么时机调用 `open`」这一环,在 25 篇里始终没有落到一个具体入口。
#### 跨篇问题
1. **读完 25 篇仍然没有「从零跑起来」的入口。** 每篇都给代码和文档站 live,但没有一处给出:模板工程怎么拿、文件放进哪个根、用什么命令编译或预览、别名 `@motajs/*`/`@user/*` 指向哪里。作为只读 Markdown 的读者,我能写出代码,但无法开始第一次验证。这不是某一篇缺,而是连续读完才暴露的整链缺口。
2. **TSX 里到底哪些模板语法可用,跨篇没有统一答案。** 第 1 篇说「不要用单文件组件的写法,模板指令不适用」;第 8 篇把 `v-if` 列为状态丢失原因;第 12 篇用 `v-model:selected`;第 15 篇用 `v-model:value`;第 16 篇还提到 `v-model:page`。我能从上下文推断这些是 TSX 支持的写法,但无法形成一条规则去判断下一个 `v-` 前缀能不能用。
3. **`state` 的可见范围跨篇对不上。** UI 组件通过 `props.state` 拿到 ClientCore;第 13 篇明确说普通子组件不要接收 `controller`/`instance`/`state`;但第 6 篇的素材获取写成 `props.state.materials`,第 15/24 篇的按键又依赖 `props.state.hotkey`。抽成子组件后,这些能力是只能靠 prop 层层传,还是另有入口,连续读完仍不明确。
4. **「组件边界不是节点」与「`Scroll` 只认直接子元素」是两条跨篇规则,合起来会产生一个我没法验证的问题。** 第 13、14 篇反复说组件不产生额外节点、多根成为同父级子元素;第 16、23 篇又要求 `Scroll` 的子元素必须平铺、不能包容器。第 23 篇让 `ItemGrid` 返回行数组塞进 `Scroll`,但 `ItemGrid` 本身是组件;这些行算不算 `Scroll` 的直接子元素,文档没有给出可操作判定。这是连续读到示例(四)才会冒出来的问题。
5. **内置组件的「受控 / 半受控」没有统一模型。** `Input` 用 `v-model:value` 跟随外部;`Page` 说外部改 `page` 也会跟随;`List` 却说挂载后改 `selected` 绑定不会改选,只能靠用户点击。单看每一篇都能接受,连起来读我无法预测下一个内置组件属于哪一类,也找不到「如何程序化设置 `List` 选中」的出口。
6. **单位与取值表散落在多篇,没有汇总。** 旋转是弧度(第 7 篇)、`alpha` 是 0–1、`interval` 是毫秒(第 15 篇)、`scrollTo(y, time)` 的 `time` 单位没写(第 23 篇)、`padEnd` 单位没写、`MouseType`/`WheelType`/`KeyCode` 只有零散枚举。连续读完我仍拼不出一张「数值参数都什么单位」的表。
7. **静默失败是跨篇反复出现的现象,但没有一篇给出统一的诊断入口。** 属性名写成连字符不报错、`props` 数组漏键不报错、`fill` 写成颜色不生效、`emits` 声明了却忘了 `emit`、`g-rect` 写 `radius` 不生效——这些分别在第 1、3、9、12、14 篇出现。作为新手,我需要的是「先检查哪几项」的一张总表,而不是每篇各说一句。
8. **画布与面板尺寸的关系连续读完仍有两套读法。** 第 2 篇说面板 `loc` 相对 UI 容器、按 `renderer.width`/`height` 适配、控制器不会居中;第 20 篇又把 720×480 的面板放在示例站 480×320 的画布上,并说逻辑尺寸会整体缩放。我在「按画布设计尺寸设计」与「按面板自己的设计尺寸设计」之间无法确定默认应该选哪个。
9. **一批术语在多篇复用却始终没有定义。** `custom`、`container-custom`、`template`(第 7 篇缓存表)、`Tip`(第 16 篇)、`激励源`(第 10 篇)、`transitioned`/`transitionedColor`(第 25 篇)、`ITexture` 与 `Texture` 的关系(第 6 篇)。单篇里都能绕过,连续读完会发现这些词一直在挡路。
#### 第 3 轮分诊
| 编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由 | 处理 |
| --- | --- | --- | --- | --- | --- |
| R3-01 | `docs/advanced/ii/ui/ui-template.md`「一个最小 UI」 | 模板工程在哪、用什么命令跑、`satisfies` 是什么 | 是 | 缺前置:无法开始第一次验证 | 修 |
| R3-02 | `docs/advanced/ii/ui/ui-template.md`「文件放在哪里」 | 三个别名指向哪个目录、如何验证被加载 | 是 | 缺入口:别名与预览方式未给 | 修 |
| R3-03 | `docs/advanced/ii/ui/ui-template.md`「渲染树位置」 | 画布根/UI 容器谁创建、能否自己挂树、`custom` 是什么 | 否 | 架构深度;通过 `open` 已可继续 | 不修 |
| R3-04 | `docs/advanced/ii/ui/container-and-coordinates.md`「坐标从哪里来」 | 初始当前尺寸、元素层 `Container`/`Rect` 未 import | 是 | 缺 import + 默认值未说明 | 修 |
| R3-05 | `docs/advanced/ii/ui/container-and-coordinates.md`「层级」「事件路径」 | `absoluteX/Y` 未定义、`stopPropagation` 推到第 9 篇 | 否 | 后续篇已覆盖 | 不修 |
| R3-06 | `docs/advanced/ii/ui/basic-shapes.md`「填充、描边与命中」 | 示例把注释对象与 JSX 混排,照搬会语法错误 | 是 | 步骤缺失:示例不可直接使用 | 修 |
| R3-07 | `docs/advanced/ii/ui/basic-shapes.md`「图形作为界面零件」 | `g-rectr` 只给单值圆角 | 否 | 第 4 篇有完整规则 | 不修 |
| R3-08 | `docs/advanced/ii/ui/curves-and-paths.md`「路径」「圆角矩形」 | `Path2D` 编译配置、三项圆角几何 | 否 | 额外深度 | 不修 |
| R3-09 | `docs/advanced/ii/ui/text.md`「字体」 | `addFallback` 的签名 | 否 | 可选 API 的补充 | 不修 |
| R3-10 | `docs/advanced/ii/ui/text.md`「尺寸与居中」 | 测量时机、`onMounted` 与事件的选择 | 否 | 额外深度 | 不修 |
| R3-11 | `docs/advanced/ii/ui/image-and-texture.md`「从素材管理器取纹理」 | 子组件如何拿 materials、`ITexture` 能否直接给 `image` | 是 | 缺前置:`state` 可见范围未讲清 | 修 |
| R3-12 | `docs/advanced/ii/ui/image-and-texture.md`「边界与注意」 | 纹理释放方法名与时机 | 否 | 额外深度 | 不修 |
| R3-13 | `docs/advanced/ii/ui/layer-transform-performance.md`「缓存与脏更新」 | `custom` 主动更新方法、`template`/`container-custom` 定义、filter 入口 | 否 | 额外 API 索引;`custom` 由 R3-28 定义 | 不修 |
| R3-14 | `docs/advanced/ii/ui/reactivity.md`「什么时候会重渲染」 | `shallowRef` 场景、`watch` deep/immediate | 否 | 额外深度 | 不修 |
| R3-15 | `docs/advanced/ii/ui/events.md`「事件对象」 | `MouseType`/`WheelType` 枚举、`onMove` 条件 | 否 | 额外 API 表 | 不修 |
| R3-16 | `docs/advanced/ii/ui/events.md`「stopPropagation」 | 同一元素多个同事件监听器的顺序 | 否 | 边界情况 | 不修 |
| R3-17 | `docs/advanced/ii/ui/hotkey-in-ui.md`「HotkeyEmitMode」 | 「激励源」未定义、`Continuous` 无法映射 | 是 | 术语未定义 | 修 |
| R3-18 | `docs/advanced/ii/ui/hotkey-in-ui.md`「注册新指令与分组」 | `KeyCode` 完整表、三键组合 | 否 | 外部枚举;组合规则已给 | 不修 |
| R3-19 | `docs/advanced/ii/ui/conditional-and-list-rendering.md`「循环」 | 返回数组是否要 Fragment/外层容器 | 否 | 第 13 篇已覆盖 | 不修 |
| R3-20 | `docs/advanced/ii/ui/conditional-and-list-rendering.md`「key」 | `key` 加错的具体症状 | 否 | 额外深度 | 不修 |
| R3-21 | `docs/advanced/ii/ui/props.md`「组件怎么拿参数」 | 第 1 篇说模板指令不适用,这里又出现 `v-model:selected` | 是 | 明确矛盾 | 修 |
| R3-22 | `docs/advanced/ii/ui/props.md`「泛型顺序」 | 泛型不一致时的排查方法 | 否 | 类型层细节 | 不修 |
| R3-23 | `docs/advanced/ii/ui/component-tsx.md`「映射成子树」 | 多根返回数组还是 Fragment | 否 | 第 23 篇示例已给 | 不修 |
| R3-24 | `docs/advanced/ii/ui/component-tsx.md`「expose/emit」 | `ref<CardExpose>` 的泛型选择 | 否 | 额外深度 | 不修 |
| R3-25 | `docs/advanced/ii/ui/slots-and-attrs.md`「具名 slot」 | `PanelOptions` 与 `SetupComponentOptions` 兼容边界 | 否 | 额外深度 | 不修 |
| R3-26 | `docs/advanced/ii/ui/slots-and-attrs.md`「边界上的事件与属性」 | 包装组件转发骨架 | 否 | 额外深度 | 不修 |
| R3-27 | `docs/advanced/ii/ui/builtin-text-and-input.md`「InputBox」 | `void 0` 占位、`props?`、Promise 兜底 | 否 | 示例可照抄 | 不修 |
| R3-28 | `docs/advanced/ii/ui/builtin-text-and-input.md`「事件与渲染树」 | `custom` 元素全文未定义 | 是 | 术语未定义(核心元素类型) | 修 |
| R3-29 | `docs/advanced/ii/ui/builtin-list-and-containers.md`「List」 | 父级如何主动改选中 | 否 | 文档明确的组件限制(设计取舍) | 不修 |
| R3-30 | `docs/advanced/ii/ui/builtin-list-and-containers.md`「弹窗与一次性提示」 | `Tip` 未介绍、`getChoice` 取消分支 | 否 | 额外 API | 不修 |
| R3-31 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「场景 UI 与主 UI」 | `mainUIController.render()` 放在主场景哪里 | 是 | 缺入口:主场景接入未落到文件 | 修 |
| R3-32 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「事件归属与生命周期」 | UI 作者是否要调用 `setPropsBaseCreator` | 否 | 高级配置 | 不修 |
| R3-33 | `docs/advanced/ii/ui/replace-builtin-ui.md`「替换步骤」 | `loc` 由 vBind 还是控制器传 | 是 | 缺前置:注入范围未讲清 | 修 |
| R3-34 | `docs/advanced/ii/ui/replace-builtin-ui.md`「最小替换示例」 | 内置指令该 `implement` 还是 `addCommand` | 是 | 缺步骤:写法未区分 | 修 |
| R3-35 | `docs/advanced/ii/ui/ui-performance.md`「观测与验证」 | 临时计数写法与帧时间阈值 | 否 | 额外深度 | 不修 |
| R3-36 | `docs/advanced/ii/ui/inventory-example-1-skeleton.md`「骨架代码」 | 编译/预览步骤、720×480 溢出适配 | 是 | 缺前置 + 适配分工不清 | 修 |
| R3-37 | `docs/advanced/ii/ui/inventory-example-1-skeleton.md`「组件与文件怎么分」 | 类型接口是否包含回调 | 否 | 父级用法已明确 | 不修 |
| R3-38 | `docs/advanced/ii/ui/inventory-example-2-grid.md`「数据模型」 | `Item` 定义在哪个文件、如何 import | 是 | 缺 import/入口 | 修 |
| R3-39 | `docs/advanced/ii/ui/inventory-example-2-grid.md`「按行列排列」 | 根容器尺寸写死 | 否 | 维护性偏好 | 不修 |
| R3-40 | `docs/advanced/ii/ui/inventory-example-3-detail.md`「详情区的树结构」 | 两个 `container hidden` 未写 `loc` | 否 | 布局细节 | 不修 |
| R3-41 | `docs/advanced/ii/ui/inventory-example-3-detail.md`「空态与边界」 | 删除函数在后面才出现 | 否 | 示例顺序 | 不修 |
| R3-42 | `docs/advanced/ii/ui/inventory-example-4-scroll.md`「数据与选中态穿过滚动层」 | 组件返回的数组是否算 `Scroll` 直接子元素 | 是 | D-93 模型未讲清 | 修 |
| R3-43 | `docs/advanced/ii/ui/inventory-example-4-scroll.md`「面板里怎么接」 | `scrollTo` 的 `time`、`padEnd` 单位 | 是 | 术语未定义(单位) | 修 |
| R3-44 | `docs/advanced/ii/ui/inventory-example-5-state.md`「状态放在 InventoryPanel」 | 同道具数量变化的 watch 组合没有代码 | 否 | 文档已给思路,可按需实现 | 不修 |
| R3-45 | `docs/advanced/ii/ui/inventory-example-5-state.md`「已装备的格子」 | `ItemCellEmits` 未重复定义 | 否 | 第 2 篇已有定义 | 不修 |
| R3-46 | `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`「动画」 | rAF 可用性、`transitioned` 无入口 | 否 | 额外 API | 不修 |
| R3-47 | `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`「最终组装」 | 多一层同尺寸 `container` 是否必须、内容放哪层 | 是 | 缺前置:层级职责未说明 | 修 |
#### 跨篇问题分诊
| 编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由 | 处理 |
| --- | --- | --- | --- | --- | --- |
| R3-48 | 跨篇 1:`ui-template` / `inventory-example-1` | 25 篇没有「从零跑起来」的入口(工程、命令、别名) | 是 | 缺前置/入口 | 修 |
| R3-49 | 跨篇 2:`ui-template` / `props` | TSX 里哪些 `v-` 前缀可用没有统一规则 | 是 | 明确矛盾 | 修 |
| R3-50 | 跨篇 3:`image-and-texture` / `component-tsx` | 普通子组件不接 `state`,但素材/按键又要用 | 是 | 缺前置:可见范围未讲清 | 修 |
| R3-51 | 跨篇 4:`component-tsx` / `inventory-example-4` | 组件边界不算节点,但 `Scroll` 只认直接子元素 | 是 | D-93 模型未讲清 | 修 |
| R3-52 | 跨篇 5:`builtin-list-and-containers` | 内置组件受控/半受控模型不统一 | 否 | 各组件限制(设计取舍) | 不修 |
| R3-53 | 跨篇 6:`events` / `inventory-example-4` | 单位与枚举散落,`scrollTo`/`padEnd` 单位缺失 | 是 | 术语未定义(单位);枚举表属额外 | 修 |
| R3-54 | 跨篇 7:`ui-template` / `props` / `slots-and-attrs` 等 | 静默失败没有统一诊断入口 | 否 | 额外综合,不阻碍继续 | 不修 |
| R3-55 | 跨篇 8:`container-and-coordinates` / `inventory-example-1` | 按画布设计还是按面板设计尺寸写坐标 | 是 | 缺前置:两者分工未说清 | 修 |
| R3-56 | 跨篇 9:`layer-transform-performance` / `builtin-list-and-containers` 等 | `custom`/`template`/`Tip`/`激励源` 等术语未定义 | 否 | 单篇可绕过;`custom`/`激励源` 已由 R3-28/R3-17 修 | 不修 |
第 3 轮阻断数:22
第 3 轮非阻断数:34
概率继承:Round 1 的 178 行分节概率继续有效;本轮新增/重写章节需补该节概率。
状态:已汇总
#### 第 3 轮修订
R3-01:已修 → `docs/advanced/ii/ui/ui-template.md#工程与命令`:补仓库根目录、`pnpm install` / `pnpm dev` / `pnpm docs:dev`。
R3-02:已修 → `docs/advanced/ii/ui/ui-template.md#工程与命令`:补 `@motajs/*` → `packages/*/src`、`@user/*` → `packages-user/*/src`。
R3-04:已修 → `docs/advanced/ii/ui/container-and-coordinates.md#元素层`:补 `import { Container, Rect } from '@motajs/render'` 与默认 200×200 说明。
R3-06:已修 → `docs/advanced/ii/ui/basic-shapes.md#填充、描边与命中`:把三个示例收进同一个 `container`,去掉裸 JSX 与注释对象混排。
R3-11:已修 → `docs/advanced/ii/ui/image-and-texture.md#从素材管理器取纹理`:补「顶层取纹理、作为 prop 传给子组件」。
R3-17:已修 → `docs/advanced/ii/ui/hotkey-in-ui.md#触发方式`:补「激励源」是渲染循环的每帧时间激励,`Continuous` 按帧累计。
R3-21:已修 → `docs/advanced/ii/ui/ui-template.md#边界与注意`:澄清 `.vue` 模板指令不适用,但 TSX 里 `v-model:xxx` 是 `xxx` + `onUpdate:xxx` 的简写。
R3-28:已修 → `docs/advanced/ii/ui/layer-transform-performance.md#缓存与脏更新`:补 `custom` / `container-custom` / `template` 的定义与差别。
R3-31:已修 → `docs/advanced/ii/ui/ui-controller-and-stack.md#场景 UI 与主 UI`:补主场景根容器渲染 `props.state.mainUIController.render()`(见 `src/client/ui/main.tsx`)。
R3-33:已修 → `docs/advanced/ii/ui/replace-builtin-ui.md#替换步骤`:补 `loc` 来自打开方 vBind,控制器只注入 `controller`/`instance`/`state`。
R3-34:已修 → `docs/advanced/ii/ui/replace-builtin-ui.md#最小替换示例`:补 `@common/exit` 用 `key.implement` 覆盖,`addCommand` 只用于新 id。
R3-36:已修 → `docs/advanced/ii/ui/inventory-example-1-skeleton.md#骨架在渲染树里的位置`:补工程命令、画布与面板分工、720×480 溢出行为。
R3-38:已修 → `docs/advanced/ii/ui/inventory-example-2-grid.md#数据模型`:补 `Item` 与 `ItemGrid` 同文件导出、其它文件 `import type`。
R3-42:已修 → `docs/advanced/ii/ui/inventory-example-4-scroll.md#数据与选中态穿过滚动层`:补组件返回数组会平铺为 `Scroll` 直接子元素。
R3-43:已修 → `docs/advanced/ii/ui/inventory-example-4-scroll.md#面板里怎么接`:补 `scrollTo` 的 `time` 是毫秒、`padEnd` 是像素。
R3-47:已修 → `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md#最终组装与契约核对`:补外层画布根与内层面板根的职责、新内容加在哪层。
R3-48:已修 → 同 R3-01 / R3-02 / R3-36(工程、命令、别名)。
R3-49:已修 → 同 R3-21(TSX 的 `v-model` 规则)。
R3-50:已修 → 同 R3-11(顶层取 `state`、子组件收 prop)。
R3-51:已修 → 同 R3-42(组件边界与 `Scroll` 直接子元素)。
R3-53:已修 → 同 R3-43(`scrollTo` / `padEnd` 单位)。
R3-55:已修 → 同 R3-36(面板设计尺寸与画布尺寸的分工)。
第 3 轮修订完成:阻断 22 条,已修 22 条,未修 0 条。
读者循环:已完成(第 3 轮修订后无阻断)。
## 旧轮次作废标记(D-94)
- 旧的 Round 1(`10-49-READER-REVIEW.md`)、Round 2、Round 3 均**未按 D-94** 执行:读者没有先完整读完目标文档之外的全部文档,因此不满足 D-94 第 1/5/6 条。
- 上述三轮记录**作废,仅保留为历史**;不删除、不复制、不作为本轮结论;旧的分诊与修订数不再计入本批读者循环。
- 本文件从下面的「重跑 Round 1(D-94)」开始按 D-94 重新计数。
### 重跑 Round 1(D-94)
#### 读者
单读者(用户已把 D-91 的多读者改为单读者)。人格:刚读完中级教程、想给自己的魔塔做一套自定义界面的作者;只掌握基础 TS/JS,没写过 UI,不知道 canvas,不会 Vue 组件写法;只能看这套文档,不能看源码,也没有人可以问。
阅读范围按 D-94:先完整读非目标文档(`docs/intermediate/` 全部、`docs/advanced/index.md`、高级 I 全部、高级 II 现有数据端、高级 III 全部、`docs/poc/render-demo.md`),再按 Part 0→5 读 25 篇目标文档。原始记录见 `10-53-READER-REVIEW-ROUND1-D94.md`(83 条逐篇提问 + 10 条跨篇问题)。
#### 逐篇提问
完整逐条原问保留在 `10-53-READER-REVIEW-ROUND1-D94.md`;下表把 25 篇的目标路径归一化,并汇总每篇的提问位置。
| 篇目 | 提问位置 | 缺什么(汇总) |
| --- | --- | --- |
| `docs/advanced/ii/ui/ui-template.md` | 最小 UI / props 列表 / 运行效果 | open 写在哪个文件、`client` 从哪来、import 与 TSX 编译前提 |
| `docs/advanced/ii/ui/container-and-coordinates.md` | 坐标基准 / 渲染树 / 容器职责 | 画布设计尺寸读哪个值、UI 容器自身 loc、720×480 与 480×320 的缩放 |
| `docs/advanced/ii/ui/basic-shapes.md` | 填充描边命中 / 图形零件 / 边界 | 透明热区写法、内描边写法、渐变/贴图 |
| `docs/advanced/ii/ui/curves-and-paths.md` | 路径 / 圆角矩形 / 三次贝塞尔 | Path2D 放哪、ellipse 8 项映射、贝塞尔上的描边/命中属性 |
| `docs/advanced/ii/ui/text.md` | 字体 / 尺寸居中 / 缓存 | 自定义字体文件、测量高度的接口、高频数字成本 |
| `docs/advanced/ii/ui/image-and-texture.md` | 加载 PNG / 素材管理器 / 像素图 | 素材目录与 src、不用编辑器怎么登记别名、非整数倍放大 |
| `docs/advanced/ii/ui/layer-transform-performance.md` | 缓存 / 显示开关 / filter | 局部 nocache 选择、hidden 与 noevent 的遍历差别、filter 取值 |
| `docs/advanced/ii/ui/reactivity.md` | ref / 重渲染 / 生命周期边界 | `defineComponent` 的 props 写法、数据端迭代器怎么变 ref、`v-if` 能否用 |
| `docs/advanced/ii/ui/events.md` | 事件名 / 事件对象 / cursor | 父容器 onMove 是否覆盖子树、触摸是否同一套、自定义/隐藏光标 |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | 注册指令 / 按键与栈 / useKey | 内置指令 id 全表、Input 聚焦时 Esc 优先级、setup 对应哪一段 |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | key / hidden 与三元 / 数据更新 | key 写在哪一层、hidden 的命中成本、数据端变化怎么通知界面 |
| `docs/advanced/ii/ui/props.md` | 组件拿参数 / 基础 props / 泛型 | props 数组能否写默认值、`open` 第二参与 loc、泛型少写是否报错 |
| `docs/advanced/ii/ui/component-tsx.md` | 组件映射 / 生命周期 / expose | 多根组件的 attrs 与定位、setup/onMounted/watch 的取数时机、两种 ref 的 import |
| `docs/advanced/ii/ui/slots-and-attrs.md` | slot / attrs / 组件边界事件 | `SetupComponentOptions` 的 slots 写法、loc 数组是否自动生效、onEnter 能否透传 |
| `docs/advanced/ii/ui/builtin-text-and-input.md` | TextContent / Input / InputBox | TextContent 完整样式键、Input 聚焦时 Esc、普通子组件怎么弹输入框 |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | List / ListPage / Scroll / 弹窗 | 外部重置 List 选中、右侧 slot 谁负责滚动、动态行高、弹窗与面板的 Esc 归属 |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 场景/主 UI / 栈策略 / 背景 / 生命周期 | 组件外有没有 client、关上层后下层是否自动回来、背景四名怎么选、creator 默认值 |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 替换步骤 / 可替换项 / 包装层 / 风险 | 改 `settings.tsx` 算不算改内置、mode/validate 约定在哪、包装层怎么写、目录树 |
| `docs/advanced/ii/ui/ui-performance.md` | 定位 / 缓存 / 命中 / 观测 | 怎么录、缓存阈值、全屏 image 的点击穿透、长帧标准 |
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 树位置 / 文件拆分 / 打开 | 720×480 与画布关系、index.ts 冲突、第一下从哪触发 |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | ItemCell / ItemGrid / 数据 / 点击 | 图标层序、末行不足时的定位容器、真实背包映射、onSelect 与 emits |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 详情树 / ItemDetail / 空态 | hidden 默认 200×200 是否挡按钮、长描述怎么让位、删除时清 selectedId |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | Scroll 位置 / 数据穿层 / 滚动事件 / 为何不用 ListPage | 滚动条宽度是否固定、组件边界与直接子元素、滚轮是否冒泡、响应式分栏 |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 状态 / 使用 / 已装备 / 键盘 | 真实装备与 useItem、equippedId 是否进存档、Input 聚焦时 Esc |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 动画 / 最终组装 / 注册打开 / 验证清单 | transitioned 签名、`hidden` 变量谁设、工具栏+快捷键链路、hide 与 close 的清单差异 |
#### D-93 复述检查
- **渲染树**:能复述根 → UI 容器 → 面板根 → 区域/叶子的层级、局部坐标与变换继承、`zIndex` 兄弟排序、`hidden`/三元/`key` 的差别、容器缓存边界与脏标记上冒。复述不出的仍在「UI 容器自身 loc 与尺寸」「hidden 与 noevent 的命中成本口径」——后者已在第 7 篇补一句澄清。
- **事件**:能复述命中从根按 `zIndex` 向内、捕获父先、冒泡子先、`enter/leave` 集合差、`offset` 与 `absolute` 的坐标差、`noevent`/`actionStroke` 对命中的影响。复述不出的在「父容器 `onMove` 是否覆盖子树」与「Input 聚焦时键盘作用域谁在上」。
- **组件**:能复述组件不产生节点、props 四环与 attrs 分叉、`emits` 声明后不再透传、slot 是函数、`inheritAttrs`、UI 与普通组件的基类区别、`expose` + `ref`。复述不出的在「`SetupComponentOptions` 的 slots 字段完整写法」与「多根组件的父级定位」。
#### 跨篇问题
1. 真实数据接不进来:`iterateItems()` 的 Map 怎么变成 `Item[]`,装备/使用怎么接 `state.hero`。
2. 素材怎么登记:没有编辑器时,自己的 PNG 放哪、怎么变成 `getImageByAlias` 的别名。
3. 组件外到底有没有 `client`:第 1 篇写 `client.sceneController`,第 17 篇说没有全局 `client`。
4. `v-if` 能不能用:第 8/13 篇拿 `v-if` 举例,第 11 篇说 TSX 没有模板指令。
5. `IGameUIPropsBase` + `DefaultProps` 是硬要求吗:第 1/13 篇说必须,第 18 篇说推荐。
6. 画布尺寸该按哪个数:480×320、720×480、`renderer.width/height`、`RENDER_WIDTH` 四者关系。
7. 普通子组件拿不到 `controller`:`getInput`/`getConfirm` 需要 controller,子组件怎么办。
8. `hidden` 的成本口径:第 7/11 篇说仍被父级遍历,第 19 篇把 hidden 当性能首选。
9. 默认值处处是坑:200×200、缓存开关、Font、lineHeight 等记不住。
10. `@user/client-base` 与 `@motajs/*` 的 import 该不该写:新建文件时不知道谁「顶部已有」。
#### 第 1 轮分诊
| 编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由(D-91) | 处理 |
| --- | --- | --- | --- | --- | --- |
| R1-01 | ui-template / 组件外打开 | 组件外 `client` 从哪来、组件内是否也能写 | 阻断 | 缺前置 / 明确矛盾 | 修 |
| R1-02 | container / 渲染树 | UI 容器自身 loc 与尺寸未知 | 阻断 | D-93 渲染树模型没讲清 | 交用户 |
| R1-03 | container / 坐标基准 | 画布尺寸读哪个 | 非阻断 | 文档已答(以 `renderer.width/height` 为准) | 不修 |
| R1-04 | basic-shapes / 命中 | 透明热区怎么写 | 非阻断 | 文档已答(`alpha={0}`) | 不修 |
| R1-05 | basic-shapes / 图形零件 | 内描边写法、渐变/贴图 | 非阻断 | 额外深度 / 设计取舍 | 不修 |
| R1-06 | curves / 路径 | Path2D 放模块还是 setup | 非阻断 | 写法选择,不影响照做 | 不修 |
| R1-07 | curves / 圆角与贝塞尔 | ellipse 8 项映射、贝塞尔属性 | 非阻断 | 额外深度 | 不修 |
| R1-08 | text / 字体与尺寸 | 自定义字体、测量接口、高频数字 | 非阻断 | 额外深度 | 不修 |
| R1-09 | image / 素材 | 素材目录、别名登记 | 非阻断 | 设计取舍(正文只负责使用已登记素材) | 交用户 |
| R1-10 | layer / 显示开关 | hidden 与 noevent 的遍历口径 | 非阻断 | 文档已答(两者都跳过命中) | 不修 |
| R1-11 | layer / filter | filter/composite 取值 | 非阻断 | 明确不属入门必须内容 | 不修 |
| R1-12 | reactivity / 生命周期边界 | `v-if` 能否用 | 阻断 | 明确矛盾(TSX 无模板指令) | 修 |
| R1-13 | reactivity / 数据更新 | 数据端迭代器怎么变 ref | 阻断 | 缺前置(跨数据端) | 交用户 |
| R1-14 | events / onMove | 父容器是否持续收到子树移动 | 非阻断 | 额外边界,按需再查 | 不修 |
| R1-15 | hotkey / 按键与栈 | Input 聚焦时 Esc 优先级 | 阻断 | 步骤/优先级未定义 | 交用户 |
| R1-16 | conditional / 列表更新 | 数据端变化怎么通知界面 | 阻断 | 缺前置(同 R1-13) | 交用户 |
| R1-17 | props / 默认值 | props 数组能否写 default | 非阻断 | 文档已答(用 `props.x ?? 默认`) | 不修 |
| R1-18 | props / open 参数 | `open` 第二参与 loc | 非阻断 | 文档已答(ui-template 已说明) | 不修 |
| R1-19 | component / 多根与 ref | 多根 attrs、两种 ref import | 非阻断 | 文档已给 import 与规则 | 不修 |
| R1-20 | slots / SetupComponentOptions | slots 字段完整写法 | 非阻断 | 文档已给 `SlotsType` 与示例 | 不修 |
| R1-21 | builtin-text / InputBox | 普通子组件怎么弹输入框 | 阻断 | 缺入口(子组件无 controller) | 修 |
| R1-22 | builtin-text / Input | Input 聚焦时 Esc | 阻断 | 同 R1-15 | 交用户 |
| R1-23 | builtin-list / 弹窗 | 弹窗与面板的 Esc 归属 | 阻断 | 同 R1-15 | 交用户 |
| R1-24 | controller / 场景与主 UI | 组件外 `client` 矛盾 | 阻断 | 明确矛盾 | 修 |
| R1-25 | replace / 可替换项 | mode/validate 约定在哪 | 阻断 | 缺前置(存档语义) | 交用户 |
| R1-26 | perf / 命中 | 全屏 image 加 noevent 后点击落点 | 非阻断 | 文档已答(透明遮罩需 noevent) | 不修 |
| R1-27 | inv2 / 真实数据 | 真实背包映射、onSelect 与 emits | 阻断 | 缺前置(跨数据端) | 交用户 |
| R1-28 | inv5 / 使用与装备 | 真实 equip/useItem | 阻断 | 缺前置(跨数据端) | 交用户 |
| R1-29 | inv6 / 最终组装 | `hidden` 变量谁设 | 阻断 | 步骤缺失 | 交用户 |
| R1-30 | inv6 / 验证清单 | hide 与 close 的「再次打开」矛盾 | 阻断 | 明确矛盾 | 修 |
统计:**第 1 轮(D-94)阻断 16 条,非阻断 14 条(按篇汇总计);阻断中已修 5 条、交用户 11 条。**
概率继承:旧轮次的 178 行分节概率不再作为有效输入(旧轮次作废);本轮新增/重写章节概率由读者在 D-94 记录中标注为「高(组件外 client、真实数据接入、Input 焦点与按键优先级、素材登记)、中(UI 容器 loc、hidden 成本、过渡 API)、低(filter 取值、ellipse 映射、自定义字体)」。
状态:已汇总
#### 重跑 Round 1 修订
- R1-01:已修 → `docs/advanced/ii/ui/ui-template.md#文件放在哪里、怎么被用到`:说明 `client` 是 `src/bootstrap.ts` 已有的客户端实例、不是全局变量;组件内只能用 `props.controller` / `props.state.sceneController`。
- R1-12:已修 → `docs/advanced/ii/ui/reactivity.md#响应式与元素生命周期的边界`与`#边界与注意`:把两处 `v-if` 例子改为 TSX 的三元/`&&` 条件渲染,并明确「TSX 里不要写 `v-if`」。
- R1-21:已修 → `docs/advanced/ii/ui/builtin-text-and-input.md#特殊组件 InputBox:单次输入`:补充普通子组件弹输入/确认框的两种写法(把 `controller` 当普通 prop 传,或 emit 给顶层面板)。
- R1-24:已修 → 同 R1-01;并在 `#边界与注意` 把基类要求改写为「UI 组件用 `IGameUIPropsBase` + `DefaultProps`;普通子组件只需 `DefaultProps`」,消除与第 18 篇的措辞冲突。
- R1-30:已修 → `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md#最终验证清单`:注明清单按 `close` 写;改用 `hide` 时滚动位置保留,预期要相应改写。
- R1-10(附带澄清):已修 → `docs/advanced/ii/ui/layer-transform-performance.md#事件坐标与 noevent`:明确 `hidden`/`noevent` 子树跳过命中遍历,不增加鼠标移动成本,但仍占内存与渲染树。
- R1-02、R1-09、R1-13、R1-15、R1-16、R1-22、R1-23、R1-25、R1-27、R1-28、R1-29:交用户(涉及 UI 容器实现、素材登记流程、数据端接口、存档语义或 Input 焦点/按键实现,无法仅凭文档在本次范围内确定)。
重跑 Round 1 修订完成:阻断 16 条,已修 5 条,交用户 11 条,未修 0 条。
本轮停止点:已完成汇总、分诊与阻断修订;未开始 Round 2;未跑最终门禁(到 22:05 停止)。
### 重跑 Round 2(D-94)
#### 读者
单读者(D-91 单读者口径)。人格:刚读完中级教程、想给自己的魔塔做一套自定义界面的作者;只掌握基础 TS/JS,没写过 UI,不知道 canvas,不会 Vue 组件写法;只能看这套文档,不能看源码,也没有人可以问。
阅读范围按 D-94:
- 先完整读非目标文档:`docs/intermediate/` 全部(`code-basics.md`、`combat-overview.md`、`data-plugins.md`、`data-state-overview.md`、`data-vs-render.md`、`enemy-aura.md`、`enemy-calculator.md`、`enemy-combat-script.md`、`enemy-final.md`、`enemy-map-damage.md`、`enemy-query.md`、`enemy-specials.md`、`enemy-status-hooks.md`、`events.md`、`flags.md`、`hero-attribute.md`、`hero-equipment.md`、`hero-items.md`、`hero-location.md`、`hooks.md`、`map-structure.md`、`map-tiles.md`、`replay-commands.md`、`src-tour.md`、`tile-store.md`)、`docs/advanced/index.md`、`docs/advanced/i/` 全部、`docs/advanced/ii/` 现有数据端(排除 `ui/`)、`docs/advanced/iii/` 全部、`docs/poc/render-demo.md`。
- 再按顺序读 25 篇目标文档(见下表),单读者一次读完。
原始记录见 `10-53-READER-REVIEW-ROUND2-D94.md`(25 条逐篇提问、8 条跨篇问题)。本节编号 `R2-01…R2-33` 为**本次重跑独立编号**,与上方已作废的第 2 轮 `R2-01…R2-69` 无关。
#### 逐篇提问
| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 |
| --- | --- | --- | --- | --- |
| `docs/advanced/ii/ui/ui-template.md` | 「一个最小 UI」「打开与关闭」「边界与注意」 | UI 由 Props、props 列表、组件、`GameUI` 四部分组成;面板根 `[0,0]` 相对 UI 容器;`controller`/`instance`/`state` 必须写进 props 列表;打开时传 `GameUI` 对象 | 独立文件里没有 `props`,`bootstrap.ts` 的 `client` 又只在启动文件;缺「此刻我人在哪里、该用哪个入口」的判断 | 可能选错控制器,或拿不到 `props` 打不开 |
| `docs/advanced/ii/ui/container-and-coordinates.md` | 「渲染树」「坐标与变换」「loc 与锚点」「边界与注意」 | 画布根 → UI 容器(控制器创建)→ 面板根 → 元素;子元素相对父容器;锚点决定落点;`zIndex` 同父级比较;容器不裁剪绘制但命中受父矩形限制 | UI 容器自身在哪里、多大、是否等于画布根、是否铺满 | 面板出现在左上角;画布小于 480×320 时被裁,大时也不自动居中 |
| `docs/advanced/ii/ui/basic-shapes.md` | 「填充、描边与命中」组合表 | `g-rect`/`g-circle`/`g-ellipse`/`g-line` 几何参数;`fill`/`stroke`/`strokeAndFill` 是模式开关;颜色在 `fillStyle`/`strokeStyle`;`actionStroke` 跟 `lineWidth` | `fill={false}` 且 `stroke={false}` 仍是填充;做「不可见但可点」或「不可见且不挡事件」该用哪个组合 | 想关填充时可能仍看到填充,只能改用透明色或包一层 |
| `docs/advanced/ii/ui/curves-and-paths.md` | 「路径与曲线的坐标基准」「路径在渲染树与命中中的位置」 | 贝塞尔无 `loc`、点相对父容器;`g-path` 的 `Path2D` 是元素局部坐标;自动取包围盒;路径按几何轮廓命中;`Path2D` 不能进存档 | 数据变化时何时重建 `Path2D`;旋转/缩放围绕哪个点,未与锚点一起说明 | 动态路径可能每次渲染重建,或建一次后永不更新;旋转中心可能不符预期 |
| `docs/advanced/ii/ui/text.md` | 「尺寸与居中」「loc 与锚点」 | `text` 只画一行,宽高由测量决定;`fillStyle` 默认白色;`anchorX={1}` 右对齐;文字默认不缓存 | 示例在 `loc` 后两项写 `0.5,0.5` 又同时写 `anchorX`/`anchorY`,正文说只写一种;固定占位该包什么尺寸的容器 | 复制示例可能依赖属性处理顺序;固定占位要反复试外层容器 |
| `docs/advanced/ii/ui/image-and-texture.md` | 「纹理从哪里来」「从素材管理器取纹理」「像素图与高清缓存」 | `image` 把纹理铺满 `loc`;`Texture` 接受 canvas/ImageBitmap/Image;素材管理器返回 `ITexture \| null`;像素图用 `noanti`;`hd` 只对缓存元素生效 | `<image>` 接受 `Texture` 还是 `ITexture`、两者是否同一类型;纹理生命周期要调用什么;`ImageBitmap` 是否要 `close()` | 自己生成的纹理能画;从素材管理器取图时类型对不上,不知是否要转换 |
| `docs/advanced/ii/ui/layer-transform-performance.md` | 「变换」「缓存与脏更新」「边界与注意」 | `scale` 是 `[x,y]`、`rotate` 弧度、`alpha` 0–1;`zIndex` 同父级;`hidden` 保留状态、三元销毁;`container` 默认缓存、`nocache` 优先;`custom` 改外部数据要手动触发更新 | 整块 720×480 面板适配不同画布时,该改根 `loc` 与布局还是加根 `scale`;`custom` 主动更新的 API 名 | 单元素缩放能做;整块适配可能算错坐标或缩掉命中;`custom` 可能不重绘 |
| `docs/advanced/ii/ui/reactivity.md` | 「ref」「什么时候会重渲染」「shallowRef 与 markRaw」「nextTick」 | TSX 里 `ref` 写 `.value`;`reactive` 不能整体替换;`computed` 惰性缓存;`watch` 做副作用;`nextTick` 只保证更新处理完 | 想等「浏览器真正画完这一帧」时的具体 API;`shallowRef` 装大数组时列表 `key`、滚动位置与子组件状态是否保持 | 可能只等到 `nextTick`;大列表优化后状态可能重置 |
| `docs/advanced/ii/ui/events.md` | 「事件对象」「stopPropagation」「enter 与 leave」「命中测试」 | 命中从根开始、`zIndex` 大优先、同值后加入优先;捕获父→子、冒泡子→父;`stopPropagation` 不阻止同元素同事件其它监听器;`enter/leave` 由 hover 集合做差集;`offsetX/Y` 局部、`absoluteX/Y` 画布 | 父容器冒泡回调里想知道「最初点中的子元素」,但 `target` 是当前元素;`MouseType.Left` 的数值 | 点击换色/顺序能跑;最初目标与左键判断可能写错 |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | 「注册新指令与分组」「优先级与阻断」「默认按键」「按键与 UI 栈」 | `useKey` 必须 setup 同步调用;`implement` 接回调;`addCommand` 注册默认键;`HotkeyEmitMode` 三种;`priority`/`block` 只对抬起有效;只有栈顶作用域实现会执行 | 默认表里 `@common/exit` 与 `@ui/menu` 都默认 Escape,缺「按 Esc 到底关面板还是开菜单」的判断 | 面板可能关了又弹出菜单,或两条都执行 |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | 「hidden 与三元」「key」「列表项的事件与状态」 | `hidden` 保留实例/状态/监听,三元销毁;`.map()` 生成元素数组;`key` 同父级唯一;`ref` 数组 `push/splice` 触发,`shallowRef` 整体替换;列表项回调用闭包拿当前项 | 组件返回「行数组」时行容器与格子的 `key` 分别写哪层;`hidden` 面板里的 `Input` 与按键作用域是否仍活跃 | 组件数组的 `key` 可能放错层;隐藏面板可能仍占 Esc |
| `docs/advanced/ii/ui/props.md` | 「props 的完整管线」「默认值」「props 是响应式的」 | `props` 数组是运行时白名单,未声明进 `attrs`;默认值用 `props.x ?? 默认`;`props` 响应式、不要解构;UI 的 `controller/instance/state` 由控制器注入 | 父级改 `item.count` 时,子组件读 `props.item.count` 是否自动更新;对象型 prop 内部字段是否仍被追踪 | 简单值会更新;嵌套对象的 `count` 可能不同步 |
| `docs/advanced/ii/ui/component-tsx.md` | 「组件如何映射成一棵子树」「生命周期」 | 组件不产生节点、根元素是挂载点;多根成为同一父级多个子元素;`setup` 返回 render;`onMounted/onUnmounted` 同步调用;`expose` 只暴露必要方法 | 数组根组件(如 `ItemGrid`)被父级传 `loc`/`onClick` 时,未声明属性落到哪 | 单根组件正常;数组根组件的 `loc` 可能丢或落到第一个节点 |
| `docs/advanced/ii/ui/slots-and-attrs.md` | 「具名 slot」「slot 在渲染树里的位置」「attrs」 | TSX 里 slot 是函数;具名 slot 用对象;slot 内容在父作用域求值、插入子组件根下;未声明属性进 `attrs`;声明 `emits` 的 `onClick` 不透传 | 子组件根容器的尺寸/位置如何影响 slot 内容布局;`Field` 透传 `onClick` 与内部同名监听是否叠加 | slot 内容位置受根容器影响;事件归属可能变成内部 `text` |
| `docs/advanced/ii/ui/builtin-text-and-input.md` | 「Textbox」「Input 的受控边界」「InputBox」 | `TextContent` 的 `width` 必填、`loc` 第三项被覆盖;`autoHeight` 跟内容;`Textbox` 有标题/背景/内边距;`Input` 用 `v-model:value`;失焦只移除真实输入框;取消返回空串/`NaN` | `Textbox` 宽高来自 `width/height` 还是 `loc` 第三、四项;只写 `loc`、不写 `width` 时正文有没有排版宽度;`hidden` 容器里的 `TextContent` 是否仍测量 | 长文能折行、输入受控;`Textbox` 尺寸可能不按 `loc` 生效 |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | 「List」「Scroll」「ListPage」「Page」 | `List` 内部有自己的选中值、初值取第一项、点击发 `update:selected`;`ListPage` 左列表右详情;`Page` 页码从 0;`Scroll` 只对直接子元素虚拟滚动;弹窗一次性 | 打开面板时如何程序化选中某一项;`Scroll` 的直接子元素按渲染元素还是 VNode children 判断 | 用户点击能选中;初始选中不是第一项时高亮与详情不一致,且不知怎么用代码修正 |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 「控制器、实例与栈」「背景」「栈策略」 | `open` 返回实例、`close` 卸载、`hide/show` 只改可见性;`alwaysShow` 不被 `hide`;`keep` 防闪;`lastOnly`/`showAll`;`zIndex` 是 `i*5`;`active`/`showBack` 是引用值 | `mainUIController.render()` 要放进主场景哪个容器、该容器在画布上的 `loc` 与尺寸;面板根相对谁定位、会不会被裁 | 面板可能出现在主场景容器左上角,尺寸/位置与画布不匹配 |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 「替换步骤」第二步、「风险与边界」 | 替换点是打开处或包装层;`openSettings` 是工具栏/快捷键/插件共用入口;`loc` 由调用方在 `vBind` 传;`@common/exit` 已注册,直接 `implement` 覆盖;存档返回值语义必须保留 | 第 1 篇说要同时继承 `IGameUIPropsBase` 与 `DefaultProps`,本篇最小示例只继承前者;只读文档无法搜索所有 `openSettings` 调用方 | 基类可能少写;只改一个入口时其它入口仍开旧设置 |
| `docs/advanced/ii/ui/ui-performance.md` | 「显示开关」「UI 栈」「缓存」「症状与排查」 | 缓存适合结构复杂、内容稳定的子树;`hidden` 保留元素/状态/监听/按键作用域,三元卸载;大量列表用 `Scroll`;装饰层加 `noevent`;先测再改 | 「关闭背包」该用 `close` 卸载还是 `hide` 保留;第 17 篇说能 `hide` 就不重建,本篇说长期不用的大子树应卸载 | 用 `hide` 保留滚动位置但按键作用域与内存还在;用 `close` 又每次重建 |
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 「骨架在渲染树里的位置」「打开它」 | 最终面板 720×480;根下背景、主体、标题、关闭按钮、左右占位;关闭归 `InventoryPanel`;状态归面板;`InventoryUI` 用 `GameUI` 注册;三个打开入口 | 示例站画布 480×320,720×480 会超出;缩放由谁做、怎么居中、打开时 `loc` 传什么;第一次验证用哪个控制器 | 照抄后只看到左上角;不知该改根 `loc`、改内部布局还是加 `scale` |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | 「ItemGrid」「数据如何进入网格」 | `Item` 只在 `item-grid.tsx` 定义一次;5 列、`cellSize=66`、`gap=8`;`ItemCell` 只收 `item/selected/size`;`ItemGrid` 用 `computed` 算列数/尺寸;点击三层上报;`key=item.id` | 窗口适配、列数或格子尺寸变化时,`ItemCell` 在 setup 里读一次的 `size` 不会跟着变;缺「哪些 props 要改成 computed/render 读取」的清单 | 缩放或改 `cellSize` 后,格子容器变了而 `ItemCell` 内部仍按旧尺寸画 |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 「详情区的树结构」「空态与边界」 | `selectedId` 用 `ref<string \| null>(null)`;`selectedItem` 用 `computed` + `?? null`;提示/详情用 `hidden` 切换;`TextContent width=164`、`autoHeight`;`clear` 只上报 | 提示容器与详情容器都没写 `loc` 尺寸,默认 200×200,而详情区宽 196;内部容器是否需要尺寸、是否影响命中;隐藏的 `TextContent` 是否仍测量 | 选中/取消能切换;内部容器命中范围可能比详情区宽;隐藏文本可能撑出高度 |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 「Scroll 在渲染树里的位置」「数据与选中态如何穿过滚动层」 | `Scroll` 只对直接子元素虚拟滚动;`ItemGrid` 根从单容器改成行数组;行 `key=row`、格子 `key=item.id`;`scrollTo` 收内容像素;`getScrollLength` 是总长减视口;`padEnd` 像素 | `Scroll` 判断「直接子元素」看渲染后元素还是 VNode children;`<ItemGrid>` 是组件 VNode,会不会只看到一个组件 | 40 件道具能滚;若按 VNode children 判断,虚拟滚动可能退化成整块 |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 「状态放在 InventoryPanel」「已装备的格子」「遮罩与 noevent」 | 面板持有 `items/selectedId/equippedId/hint`;`canEquip/canUse/isEquipped` 是 `computed`;`use` 直接改 `item.count`;`watch` 只更新提示;`ActionBar` 只发 `equip/use/close`;遮罩用 `noevent` | `use` 改的是 `selectedItem.value.count`,`ItemGrid`/`ItemCell`/`ItemDetail` 收到的是对象;通过 prop 传下去的对象内部字段是否被追踪 | 数量减一、按钮变淡;若内部字段未追踪,可能提示更新了而格子/详情不刷新 |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 「动画作用在树的哪一层」「最终组装与契约核对」「注册与打开」 | 动画只改 `pulse`/`hintAlpha`,`onUnmounted` 里 `cancelAnimationFrame`;最终拆五个文件;`InventoryUI` 在面板文件导出、`index.ts` 再导出;从 `mainUIController` 打开;验证清单覆盖选中/滚动/装备/使用/关闭/再次打开 | 最终骨架有两层同尺寸 `container [0,0,720,480]`:外层放背景/遮罩、内层放内容;哪层接收 `hidden`/`zIndex` attrs、哪层是 UI 实例根 | 动画与面板能跑;根层级多一层时 `hidden`/`zIndex` 可能落到错误容器 |
#### D-93 复述检查
- **渲染树**:画布根下是控制器创建的 UI 容器,再往下是面板根容器、区域容器与叶子。组件本身不产生节点,组件的根元素才是父树的挂载点;返回多个根就是同一父级下多个子元素。容器决定子元素局部坐标系、同父级兄弟的 `zIndex` 排序与缓存边界;容器不裁剪绘制,但命中受父容器矩形限制。`hidden` 保留元素与状态,只跳过绘制和命中;`noevent` 仍绘制但整棵子树跳过命中。
- **事件捕获/冒泡**:指针落下后从根开始按 `zIndex` 从大到小命中,同值取后加入的;图形按几何轮廓命中。命中后先捕获(根 → 命中元素),再冒泡(命中元素 → 根)。`stopPropagation` 在任一阶段截断传播,但不阻止同一元素同事件的其它监听器。`onEnter/onLeave` 不走普通冒泡,由根维护的 hover 集合做差集触发。`offsetX/Y` 是当前元素局部坐标,`absoluteX/Y` 是画布坐标。
- **组件 props/slots/attrs**:父组件写的属性先进入子组件 VNode props;只有子组件 `props` 数组里列出的键才进入 `setup(props)`,没列出的进入 `attrs`。`attrs` 默认透传到根元素,`inheritAttrs: false` 可关闭自动透传后再手动 `{...attrs}`。slot 在 TSX 里是函数,子组件用 `slots.default?.()` / `slots.title?.()` 调用;具名 slot 用对象传入。UI 的 `controller/instance/state` 由控制器注入,必须写进 props 数组。
- **内置组件**:`TextContent` 负责按 `width` 折行、测量、打字机与 `showAll/retype/getHeight`;`Textbox` 在文本外加背景/标题/内边距/图标;`Input` 用真实 DOM 输入框覆盖画布,`v-model:value` 受控;`InputBox/getInput/getInputNumber` 是一次性弹窗,取消时 `getInput` 返回空串、`getInputNumber` 返回 `NaN`;`List` 管行布局、点击选中、选中光标与滚动,内部选中初值取第一项;`ListPage` 是左列表右详情;`Page` 管页码与箭头,索引从 0;`Scroll` 只对直接子元素做虚拟滚动;`ConfirmBox/Choices` 通过 `getConfirm/getChoice` 返回结果。
#### 跨篇问题(8 条原意)
1. **UI 的 Props 基类到底要不要 `DefaultProps`**:第 1 篇说 UI 必须同时继承 `IGameUIPropsBase` 与 `DefaultProps`;第 18 篇的最小示例只继承前者,并说 `DefaultProps` 只是类型提示。
2. **720×480 面板与 480×320 画布**:骨架篇和最终篇都按 720×480 写坐标,示例站画布是 480×320;文档说「先按画布调根或整体缩放」,但没说缩放由控制器、面板根还是打开处负责,也没给主 UI 容器的 `loc`。
3. **关闭背包用 `close` 还是 `hide`**:UI 栈篇说能 `hide/show` 就不重建,性能篇说长期不用的大子树应卸载;按键篇说 `hidden` 不离开按键作用域,输入篇说 `hide` 不会让输入框失焦。
4. **`Scroll` 与「组件返回行数组」**:示例(四)依赖「组件本身不是节点、返回的行会成为 `Scroll` 直接子元素」;但无法确认 `Scroll` 按渲染后元素还是 VNode children 判断「直接子元素」。
5. **`Textbox` 的尺寸来源**:文本与输入篇一处说宽高来自 `width/height` 或 `loc` 第三、四项,示例又同时写 `width` 与 `loc` 宽高;`TextContent` 则是 `width` 必填、`loc` 第三项被覆盖。
6. **`props` 传对象后内部字段的响应式**:props 篇说 props 是响应式的,响应式篇说 `ref` 数组内部是深层响应式;示例(五)通过 `items.value` 把数组传给 `ItemGrid`,再逐项传给 `ItemCell`,不确定父级改 `item.count` 时子组件是否都更新。
7. **默认按键的重叠**:按键篇的默认按键表里 `@common/exit` 和 `@ui/menu` 都是 Escape;`priority`/`block` 只对抬起触发有效,但没有给这两条默认指令的优先级。
8. **事件的最初目标**:事件篇说每个元素拿到的事件对象里 `target` 都是它自己;父容器冒泡时想判断「最初点中的是哪个子元素」该读什么,文档没有给字段或替代做法。
#### 第 2 轮(D-94)分诊
| 编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由(D-91) | 处理 |
| --- | --- | --- | --- | --- | --- |
| R2-01 | `docs/advanced/ii/ui/ui-template.md`「一个最小 UI」「打开与关闭」 | 文件放好后从哪打开、三个入口怎么选 | 否 | 文档已给三个入口与 `src/bootstrap.ts` 示例,并注明首次验证用 `sceneController` | 不修 |
| R2-02 | `docs/advanced/ii/ui/container-and-coordinates.md`「渲染树」 | UI 容器自身 loc/尺寸未知 | 是 | 缺前置 + D-93 渲染树模型;由引擎创建,文档无法给出 | 交用户 |
| R2-03 | `docs/advanced/ii/ui/basic-shapes.md`「填充、描边与命中」 | 透明热区与 `noevent` 的组合 | 否 | 文档已给 `alpha={0}` 与 `noevent` 写法 | 不修 |
| R2-04 | `docs/advanced/ii/ui/curves-and-paths.md`「路径与曲线的坐标基准」 | 动态 `Path2D` 重建时机、旋转中心 | 否 | 实现细节 / 额外深度 | 不修 |
| R2-05 | `docs/advanced/ii/ui/text.md`「尺寸与居中」 | `loc` 后两项与 `anchorX`/`anchorY` 重复 | 否 | 文档已明确「同一处只写一种」,示例仅示对应关系 | 不修 |
| R2-06 | `docs/advanced/ii/ui/image-and-texture.md`「从素材管理器取纹理」 | `Texture` 与 `ITexture` 是否同一类型 | 否 | 文档已给返回类型与「用法与上一节完全一样」 | 不修 |
| R2-07 | `docs/advanced/ii/ui/layer-transform-performance.md`「变换」「缓存」 | 整块面板缩放做法、`custom` 更新 API 名 | 否 | 额外深度;`custom` 不在示例主流程 | 不修 |
| R2-08 | `docs/advanced/ii/ui/reactivity.md`「ref」「nextTick」 | 等浏览器真正画完的 API、`shallowRef` 列表状态 | 否 | 额外深度 | 不修 |
| R2-09 | `docs/advanced/ii/ui/events.md`「事件对象」 | 父容器如何拿「最初目标」、`MouseType.Left` 数值 | 否 | 文档已给「看哪个元素回调被触发 / 用 absolute 坐标比较」;枚举值属额外 | 不修 |
| R2-10 | `docs/advanced/ii/ui/hotkey-in-ui.md`「默认按键」「按键与 UI 栈」 | `@common/exit` 与 `@ui/menu` 同为 Escape | 否 | 作用域栈已说明「只有栈顶作用域实现会执行」 | 不修 |
| R2-11 | `docs/advanced/ii/ui/conditional-and-list-rendering.md`「key」 | 行数组的 `key` 放哪层、`hidden` 里 Input/按键是否活跃 | 否 | 第 10 篇已说明 `hidden` 不离开按键作用域;`key` 属细节 | 不修 |
| R2-12 | `docs/advanced/ii/ui/props.md`「props 是响应式的,不要解构」 | 对象型 prop 的内部字段是否被追踪 | 是 | D-93 模型未讲清:只说了 props 响应式,未说内部字段的追踪条件 | 修 |
| R2-13 | `docs/advanced/ii/ui/component-tsx.md`「映射成一棵子树」 | 数组根组件的未声明属性落点 | 否 | 设计取舍;文档已说多根需自行安排 `loc`/`zIndex` | 不修 |
| R2-14 | `docs/advanced/ii/ui/slots-and-attrs.md`「slot 在渲染树里的位置」 | 子组件根尺寸对 slot 的影响、两个 `onClick` | 否 | 边界情况 | 不修 |
| R2-15 | `docs/advanced/ii/ui/builtin-text-and-input.md`「Textbox」 | `Textbox` 宽高来自 `width/height` 还是 `loc` | 是 | 明确矛盾:与 `width` 必填的实现/前文说法冲突 | 修 |
| R2-16 | `docs/advanced/ii/ui/builtin-list-and-containers.md`「List」「Scroll」 | 程序化选中、`Scroll` 直接子元素判定 | 否 | `List` 为组件限制(设计取舍);`Scroll` 已在示例(四)说明 | 不修 |
| R2-17 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「场景 UI 与主 UI」 | `mainUIController.render()` 挂到哪个容器 | 是 | 缺入口;与 R2-02 同根因,依赖引擎/主场景实现 | 交用户 |
| R2-18 | `docs/advanced/ii/ui/replace-builtin-ui.md`「替换步骤」 | `DefaultProps` 是否必须、入口清单 | 否 | 文档已澄清 `DefaultProps` 为推荐写法;入口已给搜索起点 | 不修 |
| R2-19 | `docs/advanced/ii/ui/ui-performance.md`「显示开关」 | 关闭背包用 `close` 还是 `hide` | 否 | 设计取舍(内存 vs 状态保留) | 不修 |
| R2-20 | `docs/advanced/ii/ui/inventory-example-1-skeleton.md`「骨架在渲染树里的位置」 | 720×480 与 480×320 的缩放/居中/`loc` | 是 | 缺步骤:只说两种做法,未给首次验证的具体做法 | 修 |
| R2-21 | `docs/advanced/ii/ui/inventory-example-2-grid.md`「按行列排列」 | 根尺寸写死、尺寸变化联动 | 否 | 维护性偏好;响应式部分同 R2-12 | 不修 |
| R2-22 | `docs/advanced/ii/ui/inventory-example-3-detail.md`「详情区的树结构」 | 内部容器默认 200×200、隐藏文本测量 | 否 | 布局细节;默认尺寸已写 | 不修 |
| R2-23 | `docs/advanced/ii/ui/inventory-example-4-scroll.md`「数据与选中态穿过滚动层」 | 行数组是否算 `Scroll` 直接子元素 | 否 | 示例(四)已明确行会平铺为直接子元素 | 不修 |
| R2-24 | `docs/advanced/ii/ui/inventory-example-5-state.md`「状态放在 InventoryPanel」 | 通过 prop 传对象后内部字段是否追踪 | 是 | 同 R2-12 | 修 |
| R2-25 | `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`「最终组装」 | 两层同尺寸容器谁接 `hidden`/`zIndex` | 否 | 文档已说明外层画布根/内层面板根;attrs 落根见第 12 篇 | 不修 |
| R2-26 | 跨篇 1:`ui-template` / `replace-builtin-ui` | `DefaultProps` 是否硬要求 | 否 | 与 R2-18 同,已澄清 | 不修 |
| R2-27 | 跨篇 2:`inventory-example-1` / `container-and-coordinates` | 720×480 与 480×320 的两套读法 | 是 | 同 R2-20 | 修 |
| R2-28 | 跨篇 3:`ui-controller-and-stack` / `ui-performance` | `close` 与 `hide` 的选型 | 否 | 设计取舍 | 不修 |
| R2-29 | 跨篇 4:`inventory-example-4` / `component-tsx` | `Scroll` 与组件边界 | 否 | 示例(四)已给结论 | 不修 |
| R2-30 | 跨篇 5:`builtin-text-and-input` | `Textbox` 尺寸来源 | 是 | 同 R2-15 | 修 |
| R2-31 | 跨篇 6:`props` / `reactivity` / `inventory-example-5` | props 传对象的内部字段响应式 | 是 | 同 R2-12 | 修 |
| R2-32 | 跨篇 7:`hotkey-in-ui` | 默认按键重叠 | 否 | 作用域栈已答;优先级只对同次匹配生效 | 不修 |
| R2-33 | 跨篇 8:`events` | 事件的最初目标 | 否 | 文档已给替代做法 | 不修 |
第 2 轮(D-94)阻断数:9(R2-02、R2-12、R2-15、R2-17、R2-20、R2-24、R2-27、R2-30、R2-31)。
第 2 轮(D-94)非阻断数:24。
概率继承:Round 1(D-94)的分节概率继续有效;本轮新增/重写章节需补该节概率。读者在 D-94 记录中标注的高频困惑集中在「UI 容器落点」「对象型 prop 的内部字段」「Textbox 尺寸来源」「720×480 与画布适配」。
状态:已汇总
#### 重跑 Round 2 修订
R2-12:已修 → `docs/advanced/ii/ui/props.md#props 是响应式的,不要解构`:补对象型 prop 的内部字段追踪条件(父级传 `ref`/`reactive` 中的对象则内部字段被追踪;普通对象字面量不会)。
R2-15:已修 → `docs/advanced/ii/ui/builtin-text-and-input.md#文本组件的用法与组合`:把「宽高来自 `width`/`height` 或 `loc`」改为 `width` 必填、正文宽度只取 `width`,正文区高度取 `loc` 第四项、未写按 `200` 兜底。
R2-20:已修 → `docs/advanced/ii/ui/inventory-example-1-skeleton.md#骨架在渲染树里的位置`:补示例站 480×320 的首次验证做法(面板根 `scale={[2/3,2/3]}`、`loc` 不变),并说明正式适配时改根 `loc` 与内部布局、不要同时加缩放。
R2-24:已修 → 同 R2-12;`inventory-example-5` 的 `item.count` 场景由 props 篇补齐追踪条件。
R2-27:已修 → 同 R2-20。
R2-30:已修 → 同 R2-15。
R2-31:已修 → 同 R2-12。
R2-02、R2-17:交用户(UI 容器自身 loc/尺寸与主 UI 容器挂载由引擎/主场景实现决定,仅凭文档无法给出;与 Round 1 的 R1-02 同根因)。
第 2 轮(D-94)修订统计:阻断 9 条,已修 7 条(落在 3 处正文:`props.md`、`builtin-text-and-input.md`、`inventory-example-1-skeleton.md`),交用户 2 条,未修 0 条。
### 重跑 Round 3(D-94)
#### 读者
单读者(D-91 单读者口径)。人格:刚读完中级教程、想给自己的魔塔做一套自定义界面的作者;只掌握基础 TS/JS,没写过 UI,不知道 canvas,不会 Vue 组件写法;只能看这套文档,不能看源码,也没有人可以问。
阅读范围按 D-94:先完整读完非目标文档(`docs/intermediate/` 全部、`docs/advanced/index.md`、`docs/advanced/i/` 全部、`docs/advanced/ii/` 除 `ui/` 外全部、`docs/advanced/iii/` 全部、`docs/poc/render-demo.md`),再按顺序读完 25 篇目标文档。原始记录见 `10-53-READER-REVIEW-ROUND3-D94.md`(124 条逐篇提问、14 条跨篇问题);本轮为第 3 轮,也是循环的最后一轮。
#### 逐篇提问
原始记录按篇逐条列出 124 条;下表把 25 篇的目标路径归一化为完整路径,并汇总每篇的提问位置与缺口。
| 篇目(完整路径) | 涉及位置 | 缺什么(汇总) | 条数 |
| --- | --- | --- | --- |
| `docs/advanced/ii/ui/ui-template.md` | 最小 UI / 文件放在哪里 / GameUI 对象 / open 第二参数 / 两条写法 | `defineComponent` 各段职责与能否省略;第一次 open 写在哪个已有文件;实例 `key` 的读取示例;子组件能否反写 props;元素层 `root` 由谁挂载 | 5 |
| `docs/advanced/ii/ui/container-and-coordinates.md` | loc 与锚点 / 坐标与变换 / 渲染树 / 坐标基准 / 嵌套示例 | 只写 `x`/`y` 是否合法;命中是否按变换逆算;父容器命中矩形是变换前还是后;`renderer` 实际宽高与 480×320;元素层 `root` 的挂载入口 | 5 |
| `docs/advanced/ii/ui/basic-shapes.md` | 四个图形 / 填充描边命中 / actionStroke / 图形零件 | `g-circle` 能否用 `loc`;`strokeAndFill` 与 `fill`+`stroke` 同时写的优先级;`actionStroke` 对 `g-rectr`;文字「可命中」是否等于「绑了监听」 | 5 |
| `docs/advanced/ii/ui/curves-and-paths.md` | 路径坐标基准 / 路径 / 圆角矩形 / 路径在渲染树与命中中的位置 | 自动取包围盒后 `x`/`y`/`w`/`h` 是否可读;props 变化时 `Path2D` 何时重建;`ellipse` 的 0 组是否表示直角;路径超出父容器时命中谁优先 | 4 |
| `docs/advanced/ii/ui/text.md` | 尺寸与居中 / 字体 / 一行文字 / 缓存 / 不自动换行 | `loc` 后两项与 `anchorX`/`anchorY` 重复写法;`addFallback` 的调用形式;元素层文字描边宽度;缓存键包含哪些属性;`TextContent` 的 `width` 与 `loc` 第三项 | 5 |
| `docs/advanced/ii/ui/image-and-texture.md` | 图片元素与纹理 / 纹理来源 / 加载 PNG / 素材管理器 / 像素图 | `image` 接收 `Texture` 还是 `ITexture`;`ITexture` 从哪导入;卸载后是否要取消加载;`ITexture` 的公开成员;`anti`/`noanti` 的默认值 | 5 |
| `docs/advanced/ii/ui/layer-transform-performance.md` | 遮挡 zIndex / 变换 / 缓存与脏更新 / filter 与 composite / 事件坐标与 noevent | `zIndex` 不写时的默认值;能否绕任意点变换;缓存分辨率与 `hd` 默认值;`filter`/`composite` 的可取值;父级 `noevent` 后子元素能否恢复命中 | 5 |
| `docs/advanced/ii/ui/reactivity.md` | 数据变化 / ref / reactive / shallowRef 与 markRaw / watch | 元素不重建是否代表普通变量保留;项目是否已装 vue;`toRefs` 的写法;`markRaw` 与 `shallowRef` 的组合;`watch` 默认深浅 | 5 |
| `docs/advanced/ii/ui/events.md` | 命中测试 / 事件名 / 事件对象 / MouseType / enter 与 leave | 同 `zIndex` 的稳定性;按下与抬起跨元素的 click 归属;最初命中的元素怎么取;`MouseType.Left` 能否当位掩码;`noevent` 容器的子元素是否还有 enter/leave | 5 |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | useKey / 注册指令 / 优先级与阻断 / 默认按键 / 按键与 UI 栈 | 普通子组件怎么拿 `props.state.hotkey.system`;`addCommand` 返回类型与 `setGroup` 入参;`priority`/`block` 对 Once/Continuous 是否生效;`@common/exit` 与 `@ui/menu` 同为 Esc;`useKey(false)` 的继承是复制还是引用 | 5 |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | hidden 与三元 / map / key / 数据更新 / 列表项事件 | `hidden` 能否写在组件标签上;组件根能否返回数组;组件标签上的 `key` 落点;`reactive` 数组整体替换是编译错误还是静默;删除选中项后详情如何收口 | 5 |
| `docs/advanced/ii/ui/props.md` | props 管线 / 组件拿参数 / 泛型顺序 / 默认值 / 基础 props | 运行时类型错误是否报错;`DefaultProps` 具体包含哪些键;省略第二个参数后 props 从哪来;`computed` 是否跟随对象字面量;`loc` 是否算注入 | 5 |
| `docs/advanced/ii/ui/component-tsx.md` | 组件映射 / 完整组件结构 / 生命周期 / expose / 组件与 UI 的区别 | 多根组件的 attrs 落点;`setup` 为何返回函数;`onMounted` 里普通元素 `ref` 的类型;`expose` 的类型标注;`GameUI` 是否还需额外登记 | 5 |
| `docs/advanced/ii/ui/slots-and-attrs.md` | slot / 具名 slot / 作用域 slot / attrs / 组件边界事件 | slot 返回值为什么是 `VNode`、返回数组类型不匹配怎么办;传 slot 的双层花括号是什么语法;`attrs` 是否包含 `onClick`;多根组件未关 `inheritAttrs` 时事件落点;slot 坐标按哪一层计算 | 5 |
| `docs/advanced/ii/ui/builtin-text-and-input.md` | TextContent / Textbox / 长说明 / Input / InputBox | `TextContent` 的 `width` 与 `loc` 第三项;`Textbox` 的 `loc` 第四项与 `height` 谁生效;Input 失焦与 click 的先后;`InputBox` 示例里的 `void 0`;`Textbox` 的宽高来源 | 5 |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | List / List 行结构 / ListPage / Page / 弹窗 | 列表数据整体替换后内部选中是否重置;List 的 id 能否是数字;`ListPage` 的 `closeLoc` 相对谁;`pages` 变小时 `page` 是否夹紧;`getChoice` 的 key 能否是字符串 | 6 |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 控制器实例与栈 / keep / 栈策略 / 场景 UI 与主 UI / 注入链 | `stack` 是否公开可读;`keep`「一次 close 清标记」与「close 到空栈不关背景」如何并存;`lastOnly` 从该实例起的方向;`mainUIController.render()` 返回什么、挂到哪;自定义 creator 的 `state` 从哪来 | 4 |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 替换入口 / 可替换项 / 替换步骤 / 风险与边界 | 内置入口函数的完整签名;`ElementLocator` 是否就是 `loc` 的数组类型;保留入口时原函数还做了哪些事;存档返回值的具体语义;包装组件如何转发 slots/attrs | 5 |
| `docs/advanced/ii/ui/ui-performance.md` | 定位 / 缓存 / 纹理与文字 / 观测 / UI 栈 | 浏览器性能面板怎么开;缓存「过大」的阈值;`image` 何时会有离屏缓存;长帧的判定标准;栈深成本是线性还是指数 | 5 |
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 树位置 / 骨架代码 / 打开它 / 运行效果 / 边界 | 720×480 与 UI 容器、画布的关系;骨架缺哪些 import;第一次打开放在哪个文件;live 的 720×480 与正文 480×320;没有素材时图标怎么画 | 5 |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | Item 数据模型 / ItemCell / ItemGrid / 数据进入 / 边界 | `import type` 是否造成运行时循环;`ItemCell` 的 `size` 只读一次;普通数组是否响应式;子组件改 props 对象字段;网格超出区域是否盖住详情 | 5 |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 详情状态 / 树结构 / ItemDetail / 空态 / 运行效果 | `selectedId` 为 null 时的比较;两个未写尺寸的 `hidden` 容器是否互挡;空文本是否仍创建元素;外部替换 `items` 时如何清选中;live 与正文文字不一致 | 5 |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 为什么换滚动 / Scroll 位置 / 行容器数组 / 面板接入 / 滚动与事件 | 组件返回数组根是否被支持;滚动条宽度是否就是 28;`rows` 空数组的类型推断;`getScrollLength` 为负时如何;拖动阈值是多少 | 5 |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 操作条 / 面板状态 / 状态反映 / 关闭路径 / 遮罩 | 禁用按钮早返回是否吃掉点击;改 props 对象里的 `count` 是否算改 props;`watch` 在数量相同时不触发;Esc 实现放在 setup 哪一段;遮罩在内层还是外层 | 5 |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 动画层 / 最终组装 / 注册与打开 / 验证清单 / 边界 | rAF 每帧写 `pulse` 是否重渲染整块;内层面板根为何存在、`hidden` 写哪层;打开代码的宿主;真实游戏里如何再次打开;live 失败时怎么排查 | 5 |
#### D-93 复述检查
- **渲染树**:能复述画布根 → UI 容器 → 面板根 → 区域/叶子的层级、局部坐标与变换继承、`zIndex` 兄弟排序、`hidden`/三元/`key` 的差别、容器默认缓存与脏标记上冒、组件不产生节点且多根成为同父级多个子元素。复述不出的在「组件根返回数组」「多根时 attrs 落点」「UI 容器自身尺寸」「`mainUIController.render()` 返回什么」。
- **事件**:能复述命中从根按 `zIndex` 向内、捕获父先、冒泡子先、`enter/leave` 集合差、`offset` 与 `absolute` 的坐标差、`noevent`/`actionStroke` 对命中的影响。复述不出的在「最初命中的元素怎么取」「`MouseType` 与 `buttons` 的位定义」「按下与抬起跨元素时 click 归属」「Scroll 拖动阈值」。
- **组件与内置组件**:能复述 props 四环与 attrs 分叉、`emits` 声明后不再透传、slot 是函数、`inheritAttrs`、UI 与普通组件的基类区别、`expose` + `ref`;能复述 `TextContent` 折行、`Textbox` 组成、`Input` 受控、`InputBox` 返回值、`List`/`ListPage`/`Page`/`Scroll` 的分工。复述不出的在「`DefaultProps` 具体键」「`Texture` 与 `ITexture` 的关系」「普通子组件拿按键 system」「slot 返回 `VNode` 与数组的差别」「包装组件转发 slots」。
- 结论:D-93 的三块模型(渲染树、事件、组件)都能复述主干,缺口集中在跨篇接口与少数默认值;没有出现「完全讲不出模型」的段落。
#### 跨篇问题(14 条原意)
1. **第一次 open 写在哪**:模板篇说去 `bootstrap` 或某个已有面板,但没有一篇给出「从零新建文件后,在哪个已有文件的哪一行调用 open」的完整片段。
2. **loc 的注入**:第 1 篇说只注入 `controller`、`instance`、`state`,第 18 篇说替换内置 UI 时组件必须接收 `loc` 且 `loc` 由打开方传;需要一份「UI 组件该声明哪些 props、分别由谁传」的清单。
3. **组件根能不能是数组**:第 11 篇说 map 必须放在有父容器的元素树里,第 23 篇说 `ItemGrid` 返回行数组直接作为 `Scroll` 的子元素。
4. **hidden 写在组件标签上**:第 11 篇只示范元素,第 12/14 篇说基础属性走 attrs 落到根元素;不确定给 `ItemDetail` 加 `hidden` 是否等价于给根容器加。
5. **keep 的清除语义**:第 17 篇一边说 close 到空栈不关背景,一边说一次 close 就清掉 keep 标记;不知道关旧面板那一下背景会不会闪。
6. **Texture 与 ITexture**:第 6 篇示例用 `new Texture`,素材管理器返回 `ITexture`,第 8 篇又建议 `markRaw` 纹理;不知道取到的对象能不能直接给 `image`。
7. **text.md 的居中示例**:既在 `loc` 后两项写 0.5,又写 `anchorX`/`anchorY` 为 0.5,正文却说只写一种。
8. **MouseType 与 buttons**:第 9 篇示例把 `MouseType.Left` 当位掩码和 `buttons` 做位与,但同一篇说 `MouseType` 是按键种类;不知道 `buttons` 的位定义在哪里。
9. **Scroll 的直接子元素跨组件边界**:第 16 篇说 `Scroll` 只检查直接子元素,第 23 篇说组件返回的行数组会成为直接子元素;不知道组件边界算不算一层节点。
10. **设计尺寸 480×320 与 720×480**:第 2 篇说画布设计尺寸来自 `renderer`,第 20 篇 live 用 720×480,正文又说示例站是 480×320;不知道验证时按哪个尺寸。
11. **useKey 在普通子组件**:第 10 篇说在组件 setup 里调用,示例都默认有 `props.state`;不知道子组件该由父级传 `system`,还是也能自己拿。
12. **List 的选中同步**:第 16 篇说父级初值要与第一项一致,挂载后再改 `selected` 不会改选;不知道列表数据整体替换时内部选中会不会重置。
13. **内置入口函数的完整签名**:第 18 篇表格只给 `openSettings`、`openReplay`、`saveSave` 等名字与参数轮廓,需要完整签名和返回值语义才能安全替换。
14. **image 的缓存**:第 6 篇说 `image` 默认不缓存,第 19 篇说每个元素仍可能有自己的离屏缓存;不知道什么时候会有。
#### 第 3 轮(D-94)分诊
判定口径按 D-91:只把缺前置、术语/类型未定义、步骤缺失导致无法继续、明确矛盾、缺 import/入口视为阻断;设计取舍、风格、详略、额外深度不算阻断。
本节编号 `R3-01…R3-43` 为 D-94 重跑的独立编号,与上方已作废的第 3 轮 `R3-01…R3-56` 无关。
| 编号 | 篇目/章节 | 问题摘要 | 是否阻断 | 理由(D-91) | 处理 |
| --- | --- | --- | --- | --- | --- |
| R3-01 | `docs/advanced/ii/ui/ui-template.md` | 模板各段职责、第一次 open、实例 key、子组件反写、元素层挂载 | 否 | 文档已给四段结构与 `bootstrap`/面板内两种入口;props 只读见第 12 篇;元素层示例是等价示意,挂载属控制器职责 | 不修 |
| R3-02 | `docs/advanced/ii/ui/container-and-coordinates.md`「loc 与锚点」 | loc 两两一组/只写 `[x, y]`;命中逆算、父容器矩形、画布尺寸、元素层挂载 | 是 | 明确矛盾:既说宽高可省,又说「两两一组要么都写、要么都不写」;其余项文档已答(第 9 篇/`renderer`/示例只讲嵌套) | 修 |
| R3-03 | `docs/advanced/ii/ui/basic-shapes.md` | g-circle 用 loc、描边组合、actionStroke、文字命中 | 否 | 「可命中」与「绑监听」是两件事,第 9 篇已答;其余属额外深度 | 不修 |
| R3-04 | `docs/advanced/ii/ui/curves-and-paths.md` | 包围盒后可读性、Path2D 重建、ellipse 0 组、父容器命中 | 否 | 额外深度与边界;动态 Path2D 属写法选择 | 不修 |
| R3-05 | `docs/advanced/ii/ui/text.md` | 居中重复写法、addFallback、元素层描边、缓存键、TextContent 宽度 | 否 | 正文已明确「同一处只写一种」,示例用于展示对应关系;其余属额外深度 | 不修 |
| R3-06 | `docs/advanced/ii/ui/image-and-texture.md`「从素材管理器取纹理」 | `Texture`/`ITexture` 类型与导入路径 | 是 | 缺 import + 类型未定义:按素材管理器取到的 `ITexture` 写 `ref<Texture>` 会对不上 | 修 |
| R3-07 | `docs/advanced/ii/ui/layer-transform-performance.md` | zIndex/hd/anti 默认、任意点变换、filter 取值、noevent 子元素 | 否 | 默认值可显式指定;filter 明确不在入门范围;noevent 已说整棵子树 | 不修 |
| R3-08 | `docs/advanced/ii/ui/reactivity.md` | 普通变量、vue 依赖、toRefs、markRaw 组合、watch 深浅 | 否 | 额外深度与工程前提,不影响照主流程写 | 不修 |
| R3-09 | `docs/advanced/ii/ui/events.md` | 同 zIndex、跨元素 click、最初目标、MouseType、noevent 悬停 | 否 | 同 zIndex 与 click 已答;`MouseType.Left` 确为第 0 位(1<<0),示例可照抄;最初目标属额外边界 | 不修 |
| R3-10 | `docs/advanced/ii/ui/hotkey-in-ui.md`「useKey」 | 普通子组件拿不到 `props.state.hotkey.system` | 是 | 缺入口:子组件没有 `props.state`,照示例写不出 `useKey` | 修 |
| R3-11 | `docs/advanced/ii/ui/conditional-and-list-rendering.md` | hidden 组件标签、数组根、key 落点、reactive 替换、删除选中 | 否 | 数组根由第 13/23 篇回答;hidden 走 attrs 第 14 篇;其余边界 | 不修 |
| R3-12 | `docs/advanced/ii/ui/props.md` | 运行时类型、DefaultProps 键、省略第二参数、computed、loc 注入 | 否 | 管线与「只写 Props 仍要传 propsOptions」已写明;loc 注入第 1 篇已澄清 | 不修 |
| R3-13 | `docs/advanced/ii/ui/component-tsx.md` | 多根 attrs、setup 返回函数、ref 类型、expose 类型、注册 | 否 | 多根见第 14 篇;其余属额外深度 | 不修 |
| R3-14 | `docs/advanced/ii/ui/slots-and-attrs.md` | slot 返回 VNode/数组、双括号、attrs 事件、多根、slot 坐标 | 否 | 文档已给 `SlotsType` 与单节点示例;多节点可先包容器;其余边界 | 不修 |
| R3-15 | `docs/advanced/ii/ui/builtin-text-and-input.md`「标题加正文的说明框」 | `Textbox` 的 `loc` 第四项与 `height` 谁生效 | 是 | 明确矛盾:正文说高度取 `loc` 第四项,示例又写 `height`,且 `height` 未声明为 props | 修 |
| R3-16 | `docs/advanced/ii/ui/builtin-list-and-containers.md` | List 选中重置、数字 id、ListPage closeLoc、Page 夹紧、getChoice key | 否 | 设计取舍与边界;初值约定已写明 | 不修 |
| R3-17 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「keep」 | keep 标记与「close 到空栈不关背景」的顺序 | 是 | 明确矛盾:既说一次 close 清标记,又说该次 close 不关背景;缺执行顺序 | 修 |
| R3-18 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「栈策略」 | lastOnly「从该实例起」的方向 | 否 | 同节已解释为「它之后打开的实例是否一起关闭」 | 不修 |
| R3-19 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「场景 UI 与主 UI」 | `mainUIController.render()` 返回什么、挂到哪 | 是 | 缺入口:主 UI 容器由引擎/主场景实现决定,文档无法给出 | 交用户(沿用 R2-17) |
| R3-20 | `docs/advanced/ii/ui/ui-controller-and-stack.md`「基础 props 的注入链」 | 自定义 creator 的 `state` 从哪来 | 否 | 额外深度:只有自定义控制器才需要,主流程不涉及 | 不修 |
| R3-21 | `docs/advanced/ii/ui/replace-builtin-ui.md`「替换步骤」 | `openSettings` 示例签名少了 `props` | 是 | 明确矛盾:正文要求保留签名,示例却只收两个参数 | 修 |
| R3-22 | `docs/advanced/ii/ui/replace-builtin-ui.md` | 入口全签名、loc 类型、原入口额外行为、存档语义、包装转发 | 否 | 推荐路径是保留入口函数,无需重写签名;存档返回语义 R1-25 已交用户 | 不修 |
| R3-23 | `docs/advanced/ii/ui/ui-performance.md` | 性能面板、缓存阈值、image 离屏缓存、长帧标准、栈深成本 | 否 | 文档明确先测再改、不给绝对阈值;属额外深度 | 不修 |
| R3-24 | `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 720×480 与画布、import、第一次打开、live、素材 | 否 | 第 37 行已给 480×320 的 `scale` 验证法(R2-20 已修);其余属额外 | 不修 |
| R3-25 | `docs/advanced/ii/ui/inventory-example-2-grid.md` | import type、size 只读、响应式、改 props、盖住详情 | 否 | 维护性与边界;对象字段追踪见第 12 篇(R2-12 已修) | 不修 |
| R3-26 | `docs/advanced/ii/ui/inventory-example-3-detail.md` | selectedId 比较、hidden 200×200、空文本、外部替换、live | 否 | 布局与边界细节,不影响主流程 | 不修 |
| R3-27 | `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 数组根、滚动条宽度、rows 类型、负数、拖动阈值 | 否 | 第 23 篇已答数组根;其余为数值/边界 | 不修 |
| R3-28 | `docs/advanced/ii/ui/inventory-example-5-state.md` | 禁用按钮、改 count、watch、Esc 位置、遮罩层级 | 否 | 行为与详略;count 追踪 R2-12 已修 | 不修 |
| R3-29 | `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | rAF、内层根与 hidden、打开宿主、再次打开、live 排查 | 否 | 性能与验证细节;内层根 R2-25 已答 | 不修 |
| R3-30 | 跨篇 1:`ui-template` / `inventory-example-1` | 第一次 open 的宿主 | 否 | 第 1 篇已给 `bootstrap` 与面板内两种入口 | 不修 |
| R3-31 | 跨篇 2:`ui-template` / `replace-builtin-ui` | `loc` 是否注入 | 否 | 第 1 篇第 147 行已明确只注入三个,`loc` 由打开方传 | 不修 |
| R3-32 | 跨篇 3:`conditional-and-list-rendering` / `inventory-example-4` | 组件根能否返回数组 | 否 | 第 13 篇允许多根、第 23 篇给行数组;第 11 篇讲的是元素树内 map 的父容器要求,不冲突 | 不修 |
| R3-33 | 跨篇 4:`conditional` / `slots-and-attrs` | 组件标签上的 hidden | 否 | 第 12/14 篇的 attrs 规则已覆盖 | 不修 |
| R3-34 | 跨篇 5:`ui-controller-and-stack` | keep 清除语义 | 是 | 同 R3-17(不重复计数) | 修 |
| R3-35 | 跨篇 6:`image-and-texture` / `reactivity` | Texture 与 ITexture | 是 | 同 R3-06(不重复计数) | 修 |
| R3-36 | 跨篇 7:`text` | 居中示例重复写法 | 否 | 同 R3-05 | 不修 |
| R3-37 | 跨篇 8:`events` | MouseType 与 buttons | 否 | 同 R3-09;位定义为第 0 位,示例正确 | 不修 |
| R3-38 | 跨篇 9:`builtin-list-and-containers` / `inventory-example-4` | Scroll 的直接子元素跨组件边界 | 否 | 第 23 篇第 17 行已说明行会平铺为直接子元素 | 不修 |
| R3-39 | 跨篇 10:`container` / `inventory-example-1` | 480×320 与 720×480 | 否 | 第 20 篇第 37 行已给首次验证的缩放做法 | 不修 |
| R3-40 | 跨篇 11:`hotkey-in-ui` | 普通子组件 useKey | 是 | 同 R3-10(不重复计数) | 修 |
| R3-41 | 跨篇 12:`builtin-list-and-containers` | List 选中同步 | 否 | 设计取舍/边界 | 不修 |
| R3-42 | 跨篇 13:`replace-builtin-ui` | 内置入口完整签名 | 否 | 推荐保留入口;`openSettings` 示例已按 R3-21 修正 | 不修 |
| R3-43 | 跨篇 14:`image-and-texture` / `ui-performance` | image 的离屏缓存 | 否 | 默认不缓存;显式开 `cache` 或在缓存容器内才可能有 | 不修 |
第 3 轮(D-94)阻断数:7(R3-02、R3-06、R3-10、R3-15、R3-17、R3-19、R3-21;跨篇 R3-34/35/40 为同项重复,不重复计数)。
其中已修 6 条,交用户 1 条(R3-19,沿用 R2-17),未修 0 条。
概率继承:Round 2(D-94)的分节概率继续有效。Round 3 记录只列逐篇问题、未单列每节使用概率(D-78 的分节概率以 Round 2 记录为准);本轮修改的 6 处按同章继承:`container-and-coordinates.md#loc-与锚点` 高、`image-and-texture.md#从素材管理器取纹理` 高、`hotkey-in-ui.md#usekey拿到当前组件的作用域` 高、`builtin-text-and-input.md#标题加正文的说明框` 高、`ui-controller-and-stack.md#keep切换面板时不闪背景` 中、`replace-builtin-ui.md#替换步骤` 中。
状态:已汇总
#### 重跑 Round 3 修订
修订者同时收到 D-93 摘要与本轮分诊结论;只改阻断项对应的篇目/章节,不改页面结构、不新增或删除页面、不改 demo、不改源码。
- R3-02:已修 → `docs/advanced/ii/ui/container-and-coordinates.md#loc-与锚点`:把「两两一组要么都写、要么都不写」改为「每一对要么都写、要么整对省略」,并明确只写 `[x, y]` 合法、宽高沿用默认值。
- R3-06:已修 → `docs/advanced/ii/ui/image-and-texture.md#从素材管理器取纹理`:补充 `ITexture` 与 `Texture` 都从 `@motajs/render` 导入、`Texture` 是 `ITexture` 的实现、`image` 接收 `ITexture | null`,素材管理器返回的对象可直接传给 `image`。
- R3-10:已修 → `docs/advanced/ii/ui/hotkey-in-ui.md#usekey拿到当前组件的作用域`:补充普通子组件把父级的 `props.state.hotkey.system` 当普通 prop 传下来(类型 `IHotkeySystem` 从 `@motajs/system` 导入),或把按键处理留在能拿到 `props.state` 的父级面板。
- R3-15:已修 → `docs/advanced/ii/ui/builtin-text-and-input.md#标题加正文的说明框`:明确正文高度只取 `loc` 第四项、`height` 未声明为 props(只会按 attrs 落到根容器),并删掉示例里无效的 `height={200}`。
- R3-17:已修 → `docs/advanced/ii/ui/ui-controller-and-stack.md#keep切换面板时不闪背景`:补充 `close` 先按 keep 标记判断本次是否关背景、再清除标记的顺序。
- R3-21:已修 → `docs/advanced/ii/ui/replace-builtin-ui.md#替换步骤`:`openSettings` 示例补回 `props?: MainSettingsProps` 并展开,保持与表格/正文一致的签名。
- R3-19:交用户 → `docs/advanced/ii/ui/ui-controller-and-stack.md#场景-UI-与主-UI`:`mainUIController.render()` 的返回类型与主场景挂载容器由引擎/主场景实现决定,文档无法单方面补全(沿用 R2-17)。
第 3 轮(D-94)修订统计:阻断 7 条,已修 6 条(落在 6 处正文:`container-and-coordinates.md`、`image-and-texture.md`、`hotkey-in-ui.md`、`builtin-text-and-input.md`、`ui-controller-and-stack.md`、`replace-builtin-ui.md`),交用户 1 条,未修 0 条。
循环结论:3 轮读者循环结束;第 3 轮修订后仍有 1 条交用户项(主 UI 挂载),不是文档内可解决的阻断。
@@ -0,0 +1,367 @@
---
phase: 10-docs-restructure
plan: 54
type: execute
wave: 12
depends_on:
- 10-53
files_modified:
- .planning/phases/10-docs-restructure/10-54-USER-REVIEW.md
- .planning/phases/10-docs-restructure/10-54-SUMMARY.md
- .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
- .planning/ROADMAP.md
- .planning/STATE.md
- docs/advanced/ii/index.md
- docs/advanced/index.md
- docs/.vitepress/config.ts
- docs/advanced/ii/ui/ui-template.md
- docs/advanced/ii/ui/container-and-coordinates.md
- docs/advanced/ii/ui/basic-shapes.md
- docs/advanced/ii/ui/curves-and-paths.md
- docs/advanced/ii/ui/text.md
- docs/advanced/ii/ui/image-and-texture.md
- docs/advanced/ii/ui/layer-transform-performance.md
- docs/advanced/ii/ui/reactivity.md
- docs/advanced/ii/ui/events.md
- docs/advanced/ii/ui/hotkey-in-ui.md
- docs/advanced/ii/ui/conditional-and-list-rendering.md
- docs/advanced/ii/ui/props.md
- docs/advanced/ii/ui/component-tsx.md
- docs/advanced/ii/ui/slots-and-attrs.md
- docs/advanced/ii/ui/builtin-text-and-input.md
- docs/advanced/ii/ui/builtin-list-and-containers.md
- docs/advanced/ii/ui/ui-controller-and-stack.md
- docs/advanced/ii/ui/replace-builtin-ui.md
- docs/advanced/ii/ui/ui-performance.md
- docs/advanced/ii/ui/inventory-example-1-skeleton.md
- docs/advanced/ii/ui/inventory-example-2-grid.md
- docs/advanced/ii/ui/inventory-example-3-detail.md
- docs/advanced/ii/ui/inventory-example-4-scroll.md
- docs/advanced/ii/ui/inventory-example-5-state.md
- docs/advanced/ii/ui/inventory-example-6-animation-and-register.md
autonomous: false
requirements: []
user_setup: []
estimate:
tokens: 98000
raw_tokens: 59000
tasks: 6
confidence: low
must_haves:
truths:
- "用户审阅只接收最终 25 篇文档与 live demo;不提供读者审阅记录、问题清单、分诊表或修订日志(D-92 第 1 条)"
- "用户按自己的阅读/使用体验提意见,每条由用户裁决「改 / 不改 / 改成什么」;执行器只改用户点名内容,不把读者问题转成用户裁决项(D-92 第 2–3 条)"
- "循环直到用户明确确认;用户确认前不写 SUMMARY、不改 ROADMAP / STATE、不宣称完成(D-92 第 4 条)"
- "用户确认后跑最终门禁:25 篇 / 24 demo / 25 HTML、prettier、ESLint 0/0、`docs/` 路径 0 类型错误、构建 0 dead link、全站 live(25 篇 + 24 demo + 侧边栏)"
- "导览补全:`docs/advanced/ii/index.md` 的 25 条目录表与侧边栏逐条一致、六个 Part、四条阅读路径;`docs/advanced/index.md` 的「高级 II」主题与性能边界更新;不新增顶层导航"
- "落位只记录 A/B/C/D 与理由,不在本计划内迁移分区;SUMMARY 与 ROADMAP / STATE 只做追加式记录,不 commit"
- "ROADMAP 追加 10-43..10-54 十二条与增量说明,不改 `**Plans:**` 计数行、不勾选 `10-06` / `10-11` / `10-12`、不动 `**10-42 增量说明:**`;STATE 只更新活动字段与追加记录,计数保持基线"
- "本批不产生 git commit:SUMMARY 记录 `BASE-HEAD` / `CURRENT-HEAD` / `PLAN-FILES-COMMITTED: none`,并以 `git log <基线>..HEAD -- <本批关键路径>` 为空、`git status --porcelain` 仍有输出为证"
artifacts:
- ".planning/phases/10-docs-restructure/10-54-USER-REVIEW.md(用户逐条意见与裁决、修订摘要;不含读者记录)"
- ".planning/phases/10-docs-restructure/10-54-SUMMARY.md(全批总结 + 提交状态三行)"
- ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-54 基线、用户确认、最终门禁、live、落位、停止点)"
- ".planning/ROADMAP.md、.planning/STATE.md(追加式更新)"
- "docs/advanced/ii/index.md、docs/advanced/index.md(25 篇目录表、四条阅读路径、主题与边界)"
key_links:
- "用户审阅与读者循环分离:读者记录不交用户,用户意见也不反向冒充读者结论;两者只在最终文档上汇合(D-92 第 3 条)"
- "用户确认前不动账本:提前写 SUMMARY / ROADMAP / STATE 会把未确认的文档当成完成(D-92 第 4 条)"
- "最终门禁必须在用户确认后跑:审阅中途的临时断链不是最终失败,最终状态才作数"
- "导览 25 条必须与侧边栏逐条对应,否则读者从导览点进去会 404"
- "落位与迁移分离:只记录选择,迁移另行派发,避免在收尾时改分区"
---
<scope_justification>
本计划是最终用户审阅与收尾,承接 10-53 的读者内部循环:
- 用户审阅只看最终文档,不提供读者记录(D-92 第 1 条);因此本计划不读、不引用 `10-49-READER-REVIEW.md` / `10-53-READER-REVIEW.md` 的内容,只在内部知道「读者循环已结束」这一状态。
- 六个任务对应六件不能合并的事:用户关卡、最终文档基线与审阅记录、用户逐条审阅循环、最终门禁与导览补全、全站 live 与落位、收尾记账。合并会破坏「先确认再改」「先修订再评估」「用户确认后才收尾」的顺序。
- 25 篇正文路径已在 `files_modified` 逐条列出;实际改动只限 `10-54-USER-REVIEW.md` 逐条点名的那几篇与那几段,未点名的篇目不得改。
- 本计划不改源码、不改 24 个 demo、不 commit、不在本计划内迁移分区。
- 上下文控制:Task 3 只读两份导览、侧边栏与门禁输出,不读 25 篇全文;Task 5 只读 SUMMARY 体例、ROADMAP / STATE 片段与本批记录,不重读正文。六任务规模保留,避免把收尾拆成更多跨计划依赖。
</scope_justification>
<objective>
把最终 25 篇文档交给用户,只按用户自己的阅读/使用意见逐条裁决与修订;用户明确确认后补全导览目录表、跑最终门禁与全站 live 复验,再评估落位,最后写 SUMMARY 并做 ROADMAP / STATE 的追加式记账。
Purpose: 文档正确性由写作者与用户负责(D-89);读者循环只验证「能否读下去」,不等于用户验收(D-92)。只有用户确认后的文档才是最终版,账本也只能在确认后更新。
Output: 用户审阅与修订记录、最终门禁结论、live 复验、落位选项、SUMMARY 与两处账本追加。**不提供读者记录、不改源码、不 commit、不在本计划内迁移分区。**
</objective>
<execution_context>
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
</execution_context>
<context>
@AGENTS.md
@dev.md
@.planning/STATE.md
@.planning/ROADMAP.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md
@.planning/phases/10-docs-restructure/10-42-PLAN.md
@.planning/phases/10-docs-restructure/10-42-SUMMARY.md
@docs/advanced/ii/index.md
@docs/advanced/index.md
@docs/.vitepress/config.ts
**流程约定:**
- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-53` 计划与 SUMMARY、不改 POC 文件、不改 `packages/` / `packages-user/` / `src/`、不改 24 个 demo。
- **Task 0 是硬关卡**:汇报用户审阅范围、裁决方式、最终门禁、live、落位与记账口径,等用户明确回复「可以执行」。
- 修改方式为**派发子代理执行**;正文修订与记录文件一律派发子代理,改文件前先声明。
- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit(D-90:由用户在本计划全部完成后自行提交)。
- **D-92 硬约束**:用户审阅只接收最终 25 篇文档与 live demo;不提供读者审阅记录、问题清单、分诊表、修订日志;不得把读者问题转成用户裁决项。
- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。
**本批事实(执行时以这些为准):**
- 10-43..10-48 已执行(10-48 为 pre-review 修复);10-49..10-52 已完成 25 篇深度扩写;10-53 已完成读者内部循环(结论见 NOTES,不交给用户)。
- 25 篇位于 `docs/advanced/ii/ui/`,24 个 demo 位于 `docs/.vitepress/components/demos/ui/`;侧边栏 25 条在 `docs/.vitepress/config.ts`。
- 10-43..10-47 的 live 人工验证此前记为「待最终人工审阅」,由本计划 Task 4 的全站 live 统一覆盖;不为前五批单独补标记。
- `docs/advanced/ii/index.md` 已含「自定义 UI 与渲染」子分组说明与 25 篇计数,但完整 25 条目录表、四条阅读路径尚未补全;`docs/advanced/index.md` 的「高级 II」主题单元格尚未加入「自定义 UI 与渲染」。
- ROADMAP 的 Phase 10 `**Plans:**` 计数行在 10-42 之后未再改动;本批沿用「只追加条目与增量说明、不改计数行」的约定。
- 参考哈希基线(`## 参考清单哈希基线` 与各批复核表)是写作期记录,本计划不读源码、不改源码,也不得改写这些哈希记录。
</context>
<tasks>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 0: 汇报用户审阅范围、裁决方式、最终门禁与收尾口径,等待「可以执行」</name>
<files>.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<read_first>.planning/phases/10-docs-restructure/10-CONTEXT.md(D-89、D-90、D-91、D-92、D-93)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-53 循环结论、命名总表、门禁)、.planning/ROADMAP.md(Phase 10 段落)、.planning/STATE.md:1-55、docs/advanced/ii/index.md、docs/advanced/index.md、docs/.vitepress/config.ts</read_first>
<action>向用户做四段汇报并停下等待:
**要做什么**——①把**最终 25 篇文档**(及 live demo)交给用户阅读;②用户按自己的阅读/使用体验提意见,逐条给出「改 / 不改 / 改成什么」;③执行器只按用户点名的内容修订,循环到用户明确确认;④确认后补全导览目录表、跑最终门禁与全站 live 复验;⑤评估落位并写 SUMMARY、做 ROADMAP / STATE 的追加式记账。
**为什么**——文档正确性由写作者与用户负责(D-89);读者循环只验证「目标读者能否读下去」,不是用户验收(D-91)。因此本次只给最终文档,不给读者记录(D-92);用户确认前不动账本。
**大致怎么做**——Task 1 建最终文档基线与 `10-54-USER-REVIEW.md`(不含任何读者记录);Task 2 用户逐条提意见、执行器按点名修订,循环到「确认」;Task 3 补全导览 + 跑最终门禁;Task 4 用户做全站 live 复验并选择落位(只记录不迁移);Task 5 写 SUMMARY、追加 ROADMAP / STATE,附未提交证明。
**影响范围**——新增 `10-54-USER-REVIEW.md` / `10-54-SUMMARY.md`,追加 NOTES;按用户指示修订 `docs/advanced/ii/ui/` 下的篇目;补全 `docs/advanced/ii/index.md` 与 `docs/advanced/index.md` 的目录表与阅读路径;仅在必要时动 `docs/.vitepress/config.ts`;追加 ROADMAP / STATE。不动 `packages/`、`packages-user/`、`src/`、前序计划文件、POC 文件、24 个 demo、既有 JSDoc/注释。
**D-92 硬约束(请用户确认):**
- 用户审阅只接收最终 25 篇文档与 live;**不提供**读者审阅记录、问题清单、分诊表、修订日志。
- 用户按自己的体验提意见;每条由用户裁决「改 / 不改 / 改成什么」;执行器只改用户点名内容。
- 不把读者问题转成用户待裁决项,也不用读者问题替代用户审阅。
- 用户明确确认前不写 SUMMARY、不改 ROADMAP / STATE、不宣称完成。
**请用户确认:**
1. 审阅范围:`docs/advanced/ii/ui/` 下最终 25 篇 + 24 个 live demo;不提供读者记录。
2. 裁决方式:用户逐条给「改 / 不改 / 改成什么」;用户说「设计如此」的不改并记录原话;用户可随时说「审阅结束」。
3. 最终门禁:prettier `--check`、ESLint 0/0、`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错、`pnpm docs:build` green + 0 dead link、25 篇 HTML、24 个 demo、静态断言。
4. 全站 live:25 篇 + 24 个 demo + 侧边栏;本次同时覆盖 10-43..10-47 此前记为「待最终人工审阅」的 live。
5. 落位选项:A 保留在高级 II 子分组(推荐);B 拆成独立顶层分区;C 合并进高级 III;D 先保留、下个里程碑再议。本计划只记录,不执行迁移。
6. **ROADMAP 计数行**:沿用 10-42 约定——只追加 10-43..10-54 十二条与一句增量说明,不改 `**Plans:**` 计数行,不勾选 `10-06` / `10-11` / `10-12`,不新增/删除 `10-33`..`10-41` 的收口条目;STATE 只更新活动字段与追加记录,`total_plans` / `completed_plans` 保持原值。
7. **不 commit**:本计划不执行任何 commit;如需提交,请在本计划**全部完成之后**自行提交(D-90)。
8. 本次修改方式为**派发子代理执行**;不改既有注释;不调用 `opencode` 命令。
**未确认前不得修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。</action>
<what-built>尚无产物;本任务只汇报用户审阅范围、D-92 约束、裁决机制、最终门禁、live、落位与记账口径。</what-built>
<how-to-verify>确认:①只给最终 25 篇 + live、不提供读者记录;②用户逐条裁决、设计如此不改;③最终门禁清单;④live 覆盖前序 deferred;⑤落位四选项只记录不迁移;⑥ROADMAP / STATE 记账口径;⑦不 commit。</how-to-verify>
<resume-signal>回复「可以执行」以继续(可同时给出落位偏好);其它回复视为未批准。</resume-signal>
<acceptance_criteria>用户已回复「可以执行」,且审阅范围、D-92 约束、裁决方式、最终门禁、live 范围、落位选项、记账口径、不 commit 八项已确定。用户未回复前不得创建或修改任何文件。</acceptance_criteria>
<verify>
<human-check>用户已回复「可以执行」,且审阅范围、D-92 约束、裁决方式、最终门禁、live 范围、落位选项、记账口径、不 commit 均已确认。</human-check>
</verify>
<done>用户回复「可以执行」且八项待定项已定。</done>
</task>
<task type="auto">
<name>Task 1: 最终文档基线 + 用户审阅记录骨架(不含读者记录)</name>
<files>.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>10-53 已写入 `停止点:10-53 读者循环结束` 与 `读者循环结论`;25 篇已完成扩写;用户已在 Task 0 回复「可以执行」。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-53 循环结论、命名总表、门禁)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/index.md、docs/advanced/index.md、docs/.vitepress/config.ts、docs/advanced/ii/ui/ 下 25 篇文件名</read_first>
<action>**本任务只建基线与审阅记录骨架,绝对不改 `docs/` 正文、不引用任何读者记录内容。**
**(1)向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-54 用户审阅与收尾`**,写入:
1. `审阅范围:` 最终 25 篇 `docs/advanced/ii/ui/*.md` + 24 个 live demo;**不提供**读者审阅记录、问题清单、分诊表、修订日志(D-92)。
2. `用户裁决方式:` 逐条「改 / 不改 / 改成什么」;判「设计如此」的不改并记录原话;用户可随时说「审阅结束」。
3. `基线 HEAD(10-54 用户审阅):` + `git rev-parse HEAD` 完整 sha。
4. `审阅前 docs 快照哈希:` + 对 25 篇 + 两份导览取聚合 SHA-256(算法与 10-49 Task 1 相同)。
5. `审阅前 demo 快照哈希:` + 对 24 个 `.tsx` demo 取聚合 SHA-256(按 `docs/.vitepress/components/demos/ui/...` 相对路径排序,逐文件取 SHA-256,拼 `相对路径:hash` 后 LF 连接,再 SHA-256)。
6. `ROADMAP 基线 Plans 行:` + `.planning/ROADMAP.md` 中 Phase 10 的 `**Plans:**` 整行原文(逐字抄录,不裁剪)。
7. `STATE 基线 total_plans:` / `STATE 基线 completed_plans:` + 当前值。
8. `ROADMAP 受保护行哈希:` + 对 `- [ ] 10-06-PLAN.md` / `- [ ] 10-11-PLAN.md` / `- [ ] 10-12-PLAN.md` 三行与 `**10-42 增量说明:**` 起首行取 SHA-256(小写 hex,64 位)。算法必须与 Task 5 相同:用 `[IO.File]::ReadAllText('.planning/ROADMAP.md', [Text.Encoding]::UTF8)` 读取并按 CRLF/LF 切分;按文件顺序筛出上述三行与 `^\*\*10-42 增量说明:` 起首行,必须恰好 4 行;去掉行尾,按 LF(`n)连接后取 UTF-8 SHA-256。这是 10-54 自己的四行基线,不沿用 10-49 的三行值。
9. `停止点:10-54 只做用户审阅与收尾;不在本计划内迁移分区;不 commit。`
**(2)核对审阅前 docs 状态**:重算 docs 快照哈希,与 NOTES 的 `循环后 docs 快照哈希:`(10-53 写入)比较;不一致说明 10-53 之后正文被改动,**停止并报告**,等用户确认来源后再继续。
**(3)新建 `.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md`**(CRLF、UTF-8、只追加):
1. 标题 `# 10-54 用户审阅记录`。
2. 一句说明:「本文件只记录用户对最终 25 篇文档的阅读意见与裁决;不包含任何读者侧记录(D-92)。」
3. `## 审阅轮次` 标题。
4. 末尾一句:「裁决与改动以用户原话为准;未点名的篇目与段落不得改动。」
**本任务不得修改任何 `docs/` 文件、不得改 ROADMAP / STATE / demo、不得把读者记录写进任何文件。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-54 用户审阅与收尾\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '停止点:10-53 读者循环结束'){ Write-Error 'NO-1053-STOP' }; foreach($k in @('## 10-54 用户审阅与收尾','审阅范围:','用户裁决方式:','基线 HEAD(10-54 用户审阅):','审阅前 docs 快照哈希:','审阅前 demo 快照哈希:','ROADMAP 基线 Plans 行:','STATE 基线 total_plans:','STATE 基线 completed_plans:','ROADMAP 受保护行哈希:','停止点:10-54 只做')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-54 用户审阅):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('审阅前 docs 快照哈希','审阅前 demo 快照哈希','ROADMAP 受保护行哈希')){ if($sec -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; if($sec -notmatch '(?m)^STATE 基线 total_plans:\s*\d+'){ Write-Error 'NO-BASE-TOTAL' }; if($sec -notmatch '(?m)^STATE 基线 completed_plans:\s*\d+'){ Write-Error 'NO-BASE-COMPLETED' }; $roadLines=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md'),[Text.Encoding]::UTF8) -split "\r?\n"; $protLines=@($roadLines | Where-Object { $_ -match '^\s*-\s\[[ x]\]\s+10-(06|11|12)-PLAN\.md' -or $_ -match '^\*\*10-42 增量说明:' }); if($protLines.Count -ne 4){ Write-Error 'PROTECTED-LINE-COUNT' }; $u='.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md'; if(-not(Test-Path -LiteralPath $u)){ Write-Error 'MISSING-USER-REVIEW' }; $up=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $u)); foreach($k in @('# 10-54 用户审阅记录','## 审阅轮次','不包含任何读者侧记录','裁决与改动以用户原话为准')){ if($up.IndexOf($k) -lt 0){ Write-Error "REVIEW-MISSING $k" } }; if($up -match "(?<!\r)\n"){ Write-Error 'REVIEW-LF-ONLY' }; foreach($bad in @('10-49-READER-REVIEW','10-53-READER-REVIEW','读者派发方式:')){ if($up.IndexOf($bad) -ge 0){ Write-Error "READER-DATA-LEAK $bad" } }; if($up -match '(?m)^\| R[23]-\d{2} '){ Write-Error 'READER-DATA-LEAK R-ROWS' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; 'T1-OK'</automated>
<fails_when>non-zero exit, or output contains "NO-1053-STOP", "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NO-BASE-TOTAL", "NO-BASE-COMPLETED", "PROTECTED-LINE-COUNT", "MISSING-USER-REVIEW", "REVIEW-MISSING", "REVIEW-LF-ONLY", "READER-DATA-LEAK", "MD-COUNT", "DEMO-COUNT"; or output lacks "T1-OK"</fails_when>
</verify>
<acceptance_criteria>NOTES 有 `## 10-54 用户审阅与收尾` 与九项固定行;`基线 HEAD` 可解析,三个哈希为 64 位小写 hex,STATE 两个计数为数字;`10-54-USER-REVIEW.md` 存在、CRLF、含标题、`## 审阅轮次`、明确「不包含任何读者侧记录」、且不含 `10-49-READER-REVIEW` / `10-53-READER-REVIEW` / `读者派发方式:` / `R2-` 或 `R3-` 行;25 篇 / 24 demo 不变;未改任何 `docs/` 正文、ROADMAP / STATE / demo。</acceptance_criteria>
<done>最终文档基线与用户审阅记录骨架已就绪,正文未动、无读者数据。</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 2: 用户逐条审阅与修订(循环,直到用户明确确认)</name>
<files>.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md, docs/advanced/ii/ui/*.md</files>
<precondition>Task 1 已创建 `10-54-USER-REVIEW.md` 的 `## 审阅轮次` 与基线;用户已收到「只给最终 25 篇 + live、不提供读者记录」的说明;docs 仍为 25 篇 / 24 demo。</precondition>
<read_first>docs/advanced/ii/ui/ 下 25 篇(按用户点名顺序)、.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md(审阅轮次)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-54 基线、命名总表)</read_first>
<action>**本任务由用户主导;执行器只按用户原话修订,不引入读者记录、不替用户裁决。**
1. **把最终文档交给用户阅读**:只给 `docs/advanced/ii/ui/` 的 25 篇与 live demo(`cmd /c "pnpm docs:dev"` 或 `docs:preview`);**不附**任何读者记录、问题清单、分诊表、修订日志;不主动把读者问题转述成「有人提出」。
2. **收集意见**:用户按自己的阅读/使用体验提意见;每条分配 `U-01`、`U-02`…,在 `10-54-USER-REVIEW.md` 的 `## 审阅轮次` 下新增 `### 第 N 轮`(N 从 1 递增),逐条记录。**若用户本轮没有意见,写 `U-00:无意见`,并记 `用户裁决:不改`**,保留轮次标题,不跳过该轮。
- `U-XX:` + 用户原话(逐字);
- `用户裁决:` 改 / 不改 / 改成什么;
- `实际改动:` 改了什么(文件 + 段落);未改的写 `未改 — <用户原话>`。
3. **修订规则**:
- 用户说改的,**只改用户点名的部分**;不改同篇其它内容、不改未点名篇目、不改既有注释、不改 24 个 demo。
- 用户说「设计如此 / 不改」的,一律不改,记录原话与依据;不争辩、不改成折中方案。
- 用户要求涉及命名或侧边栏时,先更新 NOTES 命名总表与 `docs/.vitepress/config.ts`,再改正文;不新增页面。
- **不得**把读者记录中的问题当成用户意见;不得用「读者说」推动用户裁决。
4. **每轮回报**:本轮编号、改了哪些文件与段落、哪些判为不改、当前 prettier / 构建结果。
5. **每轮门禁**:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后 `--check`;`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 确认无 dead link。若用户点名改动引入断链/类型错误,先按用户指示修到 green 再回报;无法在点名范围内修好时停止并说明。
6. **循环直到用户明确确认**:只有用户明确说「审阅结束」/「确认」才写 `用户审阅:已完成` 与独占一行 `用户确认(10-54):可以执行`,下一行 `用户原文:` 写用户原话;在此之前不得进入 Task 3、不得写 SUMMARY / ROADMAP / STATE。
7. 历史轮次逐字保留,不得覆盖、合并或改写。</action>
<what-built>按用户意见修订后的最终正文与逐条审阅记录。</what-built>
<how-to-verify>请用户确认:①每条意见是否都有裁决记录;②判「设计如此」的是否确实未改;③改动是否只落在点名篇目与段落;④每轮 prettier 与构建是否 green;⑤是否只看了最终文档、没有被提供读者记录。</how-to-verify>
<resume-signal>逐条给出意见与裁决;全部结束后回复「审阅结束」或「确认」。</resume-signal>
<acceptance_criteria>`10-54-USER-REVIEW.md` 在 `## 审阅轮次` 下按 `### 第 1 轮`、`### 第 2 轮`… 逐轮追加,逐条记录 `U-01` 起的用户原话、裁决与改动摘要;判「设计如此」的内容未被改动;NOTES 有 `用户审阅:已完成`、`用户确认(10-54):可以执行` 与 `用户原文:`;prettier 与构建在当前状态通过;未改未点名的篇目、demo、既有注释;未提供读者记录。</acceptance_criteria>
<verify>
<human-check>用户已明确确认,且每条意见都有裁决记录;NOTES 已写入用户确认标记与用户原文;未向用户提供读者记录。</human-check>
</verify>
<done>用户确认最终文档,审阅与修订记录完整。</done>
</task>
<task type="auto">
<name>Task 3: 最终门禁 + 导览目录表补全</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md, docs/advanced/ii/index.md, docs/advanced/index.md, docs/.vitepress/config.ts</files>
<precondition>NOTES 含 `用户审阅:已完成` 与 `用户确认(10-54):可以执行`;当前正文为确认后的最终状态。</precondition>
<read_first>docs/advanced/ii/index.md(现有「本层包含什么」表、阅读路径、边界节)、docs/advanced/index.md(三层结构表、边界与注意)、docs/.vitepress/config.ts(25 条侧边栏与 6 个 Part 的实际顺序)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表与门禁记录)</read_first>
<action>**(1)补全导览目录表**:
- `docs/advanced/ii/index.md`:在「本层包含什么」表格之后新增 `## 自定义 UI 与渲染` 一节,给出 25 篇完整目录表。目录表必须使用六个三级标题:`### Part 0 起步`、`### Part 1 元素与布局`、`### Part 2 交互与数据`、`### Part 3 组件化`、`### Part 4 内置组件与 UI 系统`、`### Part 5 完整示例`;表头三列为「篇目 / 能让你做什么 / 前置」(prettier 会补宽,交付态用空白容忍断言,不要求单空格字面量);每条链接必须是 `./ui/<slug>.md`;本节除目录表的 25 条链接外不再写其它 `./ui/` 链接。
- 阅读路径:页面开头与「阅读路径」段的路径总数「三条」统一改为「四条」;把「三条路径都建议先读」改为「数据端三条路径都建议先读」(后面的「自定义范围对象」链接保留);补一条「界面定制」路径,并单独写入口句「界面定制从 UI 通用模板开始,不需要先读数据端」(路径:模板 → 容器与图形 → 响应式与事件 → 组件化 → 内置组件 → 完整示例,用纯文本,不写成链接);旧的「三条阅读路径」「三条路径」(除「数据端三条路径」外)不得残留。
- 把「本层一共十篇(这一页导览 + 九篇数据端正文)」改为「本层数据端共十篇(这一页导览 + 九篇数据端正文)」,与新增 UI 小节并列。
- 把「本层不覆盖什么」里的渲染端表述改为「编辑器属性项、状态栏展示、怪物图鉴」,并保留性能边界句「引擎级性能仍属高级 III」。
- **目录表 25 条必须与侧边栏 25 条一一对应**。
- `docs/advanced/index.md`:只在「三层结构」表里「高级 II · 深入定制」那一行的「主要主题」单元格补上「自定义 UI 与渲染」(定向修改,不改其它行);删除该页中与当前事实不符的旧渲染端表述(按 verify 的 `TOP-STILL-UNFINISHED` 断言);保留「高级 II 的性能篇讲 UI 系统缓存与显示策略,引擎级性能属高级 III」。
- **不改** nav 顶层结构、不改高级 I / III 篇目、不新增页面。
**(2)最终门禁**(顺序不可颠倒):`prettier --write` → `--check`(`docs/advanced/ii docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/index.md`)→ `eslint docs/.vitepress/components/demos/ui`(0/0)→ `vue-tsc --noEmit -p docs/tsconfig.json`(`docs/` 路径 0 报错)→ 静态断言(25 篇单 H1 / 边界节 / 无被禁写法 / 侧边栏 25 条各一次 / 导览目录表 25 条与侧边栏对齐 / demo 24 个默认导出且无 DOM 属性)→ `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`(green、`build complete`、0 dead link)→ 产物:`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。
**(3)向 NOTES 追加 `### 10-54 最终门禁`**:六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、25 篇与 24 个 demo 清单、导览目录表与侧边栏对齐结论。
**(4)把「全站 live 复验清单」写进 NOTES**:25 篇逐页、24 个 demo 逐个、侧边栏 25 条逐个、「从导览点进去不 404」。</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-54 用户审阅与收尾\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '(?m)^用户确认(10-54):可以执行\s*$'){ Write-Error 'NO-USER-CONFIRM' }; if($np -notmatch '用户审阅:已完成'){ Write-Error 'NO-USER-DONE' }; $u='.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md'; $up=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $u)); if($up -notmatch 'U-\d{2}'){ Write-Error 'NO-U-ROWS' }; if($up -notmatch '### 第 1 轮'){ Write-Error 'NO-ROUND-1' }; if($up -match '10-49-READER-REVIEW|10-53-READER-REVIEW|读者派发方式:'){ Write-Error 'READER-DATA-LEAK' }; if($up -match '(?m)^\| R[23]-\d{2} '){ Write-Error 'READER-DATA-LEAK R-ROWS' }; $idx=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); foreach($k in @('## 自定义 UI 与渲染','### Part 0 起步','### Part 1 元素与布局','### Part 2 交互与数据','### Part 3 组件化','### Part 4 内置组件与 UI 系统','### Part 5 完整示例','四条阅读路径','四条路径','数据端三条路径都建议先读','界面定制','界面定制从','不需要先读数据端','本层数据端共十篇')){ if($idx.IndexOf($k) -lt 0){ Write-Error "INDEX-MISSING $k" } }; if($idx -notmatch '(?m)^\|\s*篇目\s*\|\s*能让你做什么\s*\|\s*前置\s*\|\s*$'){ Write-Error 'INDEX-MISSING HEADER' }; if($idx -match '三条阅读路径|按目标不同,可以走三条路径|(?<!数据端)三条路径'){ Write-Error 'INDEX-OLD-PATH-COUNT' }; $uiLinks=[regex]::Matches($idx,'\./ui/[a-z0-9-]+\.md') | ForEach-Object { $_.Value } | Sort-Object -Unique; if($uiLinks.Count -ne 25){ Write-Error ('INDEX-UI-LINKS:'+$uiLinks.Count) }; $cfg=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); $cfgLinks=[regex]::Matches($cfg,"'/advanced/ii/ui/([a-z0-9-]+)'") | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique; if($cfgLinks.Count -ne 25){ Write-Error ('CFG-COUNT:'+$cfgLinks.Count) }; foreach($l in $uiLinks){ $slug=$l -replace '^\./ui/','' -replace '\.md$',''; if($cfgLinks -notcontains $slug){ Write-Error "INDEX-CFG-MISMATCH $slug" } }; $top=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/index.md')); if($top.IndexOf('自定义 UI 与渲染') -lt 0){ Write-Error 'TOP-NO-ENTRY' }; if($top.IndexOf('引擎级性能仍属高级 III') -lt 0){ Write-Error 'TOP-NO-PERF-BOUNDARY' }; if($top -match '渲染端尚未完工|渲染端.*未完工'){ Write-Error 'TOP-STILL-UNFINISHED' }; if($top -cmatch '(^|\s)(class|style)\s*=\s*["'']'){ Write-Error 'TOP-DOM-ATTR' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; foreach($p in $md){ $t=[IO.File]::ReadAllText($p.FullName); $h1=@([regex]::Matches($t,'(?m)^# ')); if($h1.Count -ne 1){ Write-Error ("H1-COUNT "+$p.Name) }; if($t.IndexOf('## 边界与注意') -lt 0){ Write-Error ("NO-BOUNDARY "+$p.Name) }; if($t -match 'custom-container|createRendererFor|registerElement|IUIPropsBase|onUpdate:|GameUI\.get\('){ Write-Error ("FORBIDDEN "+$p.Name) }; if($t -match "(?<!\r)\n"){ Write-Error ("LF-ONLY "+$p.Name) } }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($d in $demo){ $t=[IO.File]::ReadAllText($d.FullName); if($t -notmatch 'export\s+default'){ Write-Error ("DEMO-NO-DEFAULT "+$d.Name) }; if($t -cmatch '(^|\s)(class|style)\s*=\s*["'']'){ Write-Error ("DEMO-DOM "+$d.Name) } }; $paths='docs/advanced/ii docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/index.md'; $pw=cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr=@($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $built=@(Get-ChildItem -LiteralPath 'public/_docs/advanced/ii/ui' -Filter *.html -File -ErrorAction SilentlyContinue); if($built.Count -ne 25){ Write-Error ('PAGE-NOT-Line truncated
<fails_when>non-zero exit, or output contains "NO-USER-CONFIRM", "NO-USER-DONE", "NO-U-ROWS", "NO-ROUND-1", "READER-DATA-LEAK", "INDEX-MISSING", "INDEX-MISSING HEADER", "INDEX-OLD-PATH-COUNT", "INDEX-UI-LINKS", "CFG-COUNT", "INDEX-CFG-MISMATCH", "TOP-NO-ENTRY", "TOP-NO-PERF-BOUNDARY", "TOP-STILL-UNFINISHED", "TOP-DOM-ATTR", "MD-COUNT", "H1-COUNT", "NO-BOUNDARY", "FORBIDDEN", "LF-ONLY", "DEMO-COUNT", "DEMO-NO-DEFAULT", "DEMO-DOM", "PRETTIER-", "ESLINT-", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "NOTES-MISSING"; or output lacks "T3-OK"</fails_when>
</verify>
<acceptance_criteria>导览补全:`docs/advanced/ii/index.md` 有 `## 自定义 UI 与渲染` 与 25 条目录表(每条 `./ui/xxx.md`)、六个 `### Part N`、表头三列(篇目 / 能让你做什么 / 前置,空白容忍,prettier 补宽后仍通过)、页面开头为「四条阅读路径」且阅读路径段为「四条路径」、数据端句为「数据端三条路径都建议先读」、含「界面定制」且入口句为「界面定制从 UI 通用模板开始,不需要先读数据端」、旧的「三条阅读路径 / 三条路径」表述不残留(「数据端三条路径」除外)、边界含「编辑器属性项 / 状态栏展示 / 引擎级性能」;`docs/advanced/index.md` 的「高级 II」主题含「自定义 UI 与渲染」、不再出现「渲染端尚未完工」、保留性能边界;25 条导览链接与侧边栏逐条一致;最终门禁全绿(prettier / ESLint 0/0 / `docs/` 路径 0 类型错误 / 25 篇单 H1 + 边界节 + 无被禁写法 + CRLF / 24 demo 合规 / 构建 green + 0 dead link / 25 HTML);NOTES 有 `### 10-54 最终门禁` 与 `全站 live 复验清单`;用户审阅记录有 U 编号与第 1 轮且无读者数据。</acceptance_criteria>
<done>导览与侧边栏完全对齐,最终门禁全绿并有记录。</done>
</task>
<task type="checkpoint:human-verify" gate="blocking-human">
<name>Task 4: 全站 live 复验 + 落位评估</name>
<files>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>Task 3 通过(最终门禁全绿、导览与侧边栏对齐、构建产物已生成);用户已确认最终文档。</precondition>
<read_first>.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(全站 live 复验清单、命名总表)、docs/advanced/ii/index.md(25 条目录表)、docs/.vitepress/config.ts(25 条侧边栏)</read_first>
<action>请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)做一次全站复验:
1. 从高级 II 导览点进「自定义 UI 与渲染」的 25 条目录,不 404;
2. 侧边栏 25 条逐条可点开,6 个 Part 顺序与导览一致;
3. 24 个 live 逐页可见且可交互(按键篇按设计不配 live;第 15 / 16 篇使用等价元素演示的,按正文说明记录,不算缺陷);
4. 反复切换路由后 live 无残留、控制台无报错。
**本次复验同时覆盖 10-43..10-47 此前记为「待最终人工审阅」的 live;通过后不再为前五批单独补标记。** 通过时在 NOTES 追加独占一行 `用户人工验证(10-54):通过` + 下一行 `用户原文:` 写用户原话。
然后请用户就**落位**给出选择(A / B / C / D):
- A 保留在高级 II 子分组(推荐:与「深入定制」的难度标签一致,且不打断现有三层结构);
- B 拆成独立顶层分区(适合后续继续扩写,但会新增一层导航);
- C 合并进高级 III(只适合把它当原理篇章,与「照着写界面」的定位不符);
- D 先保留、下个里程碑再议。
把选择与理由追加到 NOTES 的 `## 落位评估` 小节(含四选项、推荐理由、用户选择、以及「本计划不执行迁移」的说明)。**只有用户明确选择后才可进入 Task 5。**</action>
<what-built>完整的 25 篇文档子分组、导览目录表与构建产物。</what-built>
<how-to-verify>按①–④全站复验(含前序 deferred 的 live);然后就落位给出 A / B / C / D 选择与理由。</how-to-verify>
<resume-signal>复验通过回复「通过」;并给出落位选择(A / B / C / D)。</resume-signal>
<acceptance_criteria>用户明确回复全站复验通过(含 10-43..10-47 的 live),并已给出落位选择;NOTES 有 `用户人工验证(10-54):通过` + `用户原文:`,以及 `## 落位评估` 小节含四选项、推荐理由与用户选择。</acceptance_criteria>
<verify>
<human-check>用户已确认 25 篇与 24 个 live 全站可用(含前序 deferred 项),并已给出落位选择;NOTES 已记录两项。</human-check>
</verify>
<done>全站复验与落位评估结论已记录。</done>
</task>
<task type="auto">
<name>Task 5: 收尾:SUMMARY + ROADMAP / STATE 追加 + 未提交证明</name>
<files>.planning/phases/10-docs-restructure/10-54-SUMMARY.md, .planning/ROADMAP.md, .planning/STATE.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md</files>
<precondition>NOTES 含 `用户人工验证(10-54):通过` 与 `## 落位评估` 的用户选择;无 `状态:待处理`。</precondition>
<read_first>.planning/ROADMAP.md(Phase 10 段落的 Goal / `**Plans:**` 原文 / Plans 列表 / 增量说明)、.planning/STATE.md:1-55 与 `### Roadmap Evolution`、.planning/phases/10-docs-restructure/10-42-PLAN.md(Task 7 的追加体例)、.planning/phases/10-docs-restructure/10-42-SUMMARY.md(SUMMARY 与 HEAD 三行体例)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(10-54 基线、全批记录)</read_first>
<action>**(1)写 `.planning/phases/10-docs-restructure/10-54-SUMMARY.md`**(CRLF):一句话概述本批;解决什么问题;25 篇与 24 个 demo 清单(按六个 Part);12 个计划的分工(10-43..10-48 写作与 pre-review、10-49..10-52 深度扩写、10-53 读者内部循环、10-54 用户审阅与收尾);D-93 的落地(渲染树/事件/组件/示例解释);读者循环结论(轮次、阻断数、是否收敛;**不列问题清单**);用户审阅结论(意见条数、改了几条、判「设计如此」几条);最终门禁结论;落位评估与用户选择;**未做事项**(不迁移分区、不改源码/demo、不 commit、不进 nav 顶层、不改 `**Plans:**` 计数行);**计数口径**(Phase 10 的计数收口仍归 `10-41`,另行派发/记录,本批只追加 10-43..10-54 条目与增量说明);以及「HEAD 与提交状态」三行 ASCII 标记(各自独占一行):`BASE-HEAD: <Task 1 的 基线 HEAD(10-54 用户审阅)完整 sha>`、`CURRENT-HEAD: <写 SUMMARY 时的 git rev-parse HEAD>`、`PLAN-FILES-COMMITTED: none`,随后说明判定口径(HEAD 允许因用户并发提交前移,只看本批文件是否被 commit 带入)。
**(2)用 `Edit` 在 `.planning/ROADMAP.md` 的 Phase 10 `Plans:` 列表末尾追加十二行**(`- [x] 10-43-PLAN.md — …` 到 `- [x] 10-54-PLAN.md — …`,每条一句范围):10-43..10-47 为分批写作,10-48 为 pre-review 修复,10-49..10-52 为 Part 0–1 / 2–3 / 4 / 5 深度扩写,10-53 为独立读者循环(第 2/3 轮),10-54 为用户审阅 + 最终门禁 + 落位评估 + 收尾。并在该列表之后追加一句增量说明,**该句必须以字面量 `10-43 增量说明:` 开头**,内容为:本批十二条单独追加,Phase 10 的 `**Plans:**` 计数行不因本批改动(计数收口另行处理),`10-33`..`10-41` 的收口仍归 `10-41`,`10-06` / `10-11` / `10-12` 仍未勾选。
**不得**改 Goal、**不得**改 `**Plans:**` 计数行、不得改其它 Phase、不得给 `10-33`..`10-41` 增删条目、不得整文件重写。**不得触碰受保护行**:`- [ ] 10-06-PLAN.md` / `- [ ] 10-11-PLAN.md` / `- [ ] 10-12-PLAN.md` 三行必须保持未勾选原文,`**10-42 增量说明:**` 那一行必须逐字不变;Task 1 已记录这些行的哈希(`ROADMAP 受保护行哈希:`),本任务自动比对。
**(3)用 `Edit` 更新 `.planning/STATE.md`**:①frontmatter 只改 `last_updated` / `last_activity` / `last_activity_desc`;`progress.total_plans` 与 `progress.completed_plans` 保持 Task 1 基线;②`Current Position` 的 `Plan:` 与 `Last activity:` 各追加一句本批已完成;③`Progress:` 行追加「(另:高级 II 自定义 UI 与渲染子分组 25 篇 + 24 个 live 已完成深度扩写、读者循环与用户审阅)」;④`### Roadmap Evolution` 末尾追加一条本批记录(范围、12 个计划、D-93、读者循环结论、用户审阅结论、落位选择、未做事项)。**不得**改既有 Decisions / Deferred Items / Blockers / Quick Tasks。
**(4)基线比对与未提交证明**(追加到 NOTES 与 SUMMARY):Task 1 已写进 NOTES 的五项基线(ROADMAP `**Plans:**` 原行、STATE 两个计数、`基线 HEAD(10-54 用户审阅)`、`ROADMAP 受保护行哈希`);本任务自动断言 ROADMAP `**Plans:**` 原行与 STATE 两个计数仍在、`基线 HEAD` 可解析、`ROADMAP 受保护行哈希` 重算一致、SUMMARY 的 `BASE-HEAD:` 与 NOTES 基线逐字相同;再用 `git log --oneline <基线 HEAD(10-54 用户审阅)>..HEAD -- <本批关键路径>` 输出为空、`git status --porcelain -- <本批关键路径>` 仍有输出来证明本批未产生 commit(关键路径含 `docs/advanced/ii`、`docs/.vitepress/components/demos/ui`、`docs/.vitepress/config.ts`、`docs/advanced/index.md`、`ROADMAP`、`STATE` 与 10-53 / 10-54 记录文件)。**不得**为凑「HEAD 未变」要求用户回退并发提交。
**(5)不做任何 `git commit` / `git push`。**</action>
<verify>
<automated>$ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $s='.planning/phases/10-docs-restructure/10-54-SUMMARY.md'; if(-not(Test-Path -LiteralPath $n)){ Write-Error 'MISSING-NOTES' }; if(-not(Test-Path -LiteralPath $s)){ Write-Error 'MISSING-SUMMARY' }; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-54 用户审阅与收尾\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '(?m)^用户人工验证(10-54):通过\s*$'){ Write-Error 'NO-HUMAN-10-54' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-HUMAN-QUOTE' }; if($np -match '(?m)^\s*(?:[-*]\s*)?状态:待处理\s*$'){ Write-Error 'PENDING-ITEMS' }; if($np -notmatch '(?m)^## 落位评估'){ Write-Error 'NO-PLACEMENT-SECTION' }; if($sec -notmatch '(?m)^ROADMAP 基线 Plans 行:\S'){ Write-Error 'NO-BASE-PLANS' }; if($sec -notmatch '(?m)^STATE 基线 total_plans:\s*\d+'){ Write-Error 'NO-BASE-TOTAL' }; if($sec -notmatch '(?m)^STATE 基线 completed_plans:\s*\d+'){ Write-Error 'NO-BASE-COMPLETED' }; if($sec -notmatch '(?m)^基线 HEAD(10-54 用户审阅):[0-9a-f]{7,40}'){ Write-Error 'NO-BASE-HEAD' }; $sp=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $s)); foreach($k in @('25 篇','24','D-93','读者循环','用户审阅','落位','未做','BASE-HEAD:','CURRENT-HEAD:','PLAN-FILES-COMMITTED: none','构建','10-54')){ if($sp.IndexOf($k) -lt 0){ Write-Error "SUMMARY-MISSING $k" } }; if($sp -match "(?<!\r)\n"){ Write-Error 'SUMMARY-LF-ONLY' }; $road=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md')); foreach($p in @('10-43-PLAN.md','10-44-PLAN.md','10-45-PLAN.md','10-46-PLAN.md','10-47-PLAN.md','10-48-PLAN.md','10-49-PLAN.md','10-50-PLAN.md','10-51-PLAN.md','10-52-PLAN.md','10-53-PLAN.md','10-54-PLAN.md','10-06-PLAN.md','10-11-PLAN.md','10-12-PLAN.md')){ if($road.IndexOf($p) -lt 0){ Write-Error "ROADMAP-MISSING $p" } }; if($road -notmatch '10-43 增量说明'){ Write-Error 'ROADMAP-NO-NOTE' }; if($road -notmatch '(?m)^- \[ \] 10-06-PLAN\.md'){ Write-Error 'ROADMAP-UNCHECKED-MISSING' }; $m=[regex]::Match($sec,'(?m)^ROADMAP 基线 Plans 行:(.+)$'); if(-not $m.Success){ Write-Error 'NO-BASE-PLANS-TEXT' }; $bp=$m.Groups[1].Value.Trim(); if(-not $road.Contains($bp)){ Write-Error 'ROADMAP-PLANS-CHANGED' }; $st=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); if($st -notmatch '10-54'){ Write-Error 'STATE-NO-BATCH' }; $demoPaths=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File | ForEach-Object { 'docs/.vitepress/components/demos/ui/' + $_.Name } | Sort-Object); $demoJoined=($demoPaths | ForEach-Object { $_ + ':' + ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $_)))).Replace('-','').ToLower()) }) -join "`n"; $demoH=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($demoJoined))).Replace('-','').ToLower(); $mdemo=[regex]::Match($sec,'(?m)^审阅前 demo 快照哈希:([0-9a-f]{64})'); if(-not $mdemo.Success -or $mdemo.Groups[1].Value -ne $demoH){ Write-Error 'DEMO-MODIFIED' }; $mt=[regex]::Match($sec,'(?m)^STATE 基线 total_plans:\s*(\d+)'); $mc=[regex]::Match($sec,'(?m)^STATE 基线 completed_plans:\s*(\d+)'); if($mt.Success -and $st -notmatch ('(?m)^\s*total_plans:\s*'+$mt.Groups[1].Value+'\s*$')){ Write-Error 'STATE-TOTAL-CHANGED' }; if($mc.Success -and $st -notmatch ('(?m)^\s*completed_plans:\s*'+$mc.Groups[1].Value+'\s*$')){ Write-Error 'STATE-COMPLETED-CHANGED' }; $roadLines=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md'),[Text.Encoding]::UTF8) -split "\r?\n"; $protLines=@($roadLines | Where-Object { $_ -match '^\s*-\s\[[ x]\]\s+10-(06|11|12)-PLAN\.md' -or $_ -match '^\*\*10-42 增量说明:' }); if($protLines.Count -ne 4){ Write-Error 'PROTECTED-LINE-COUNT' }; $prot=$protLines -join "`n"; $protHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($prot))).Replace('-','').ToLower(); $mp=[regex]::Match($sec,'(?m)^ROADMAP 受保护行哈希:([0-9a-f]{64})'); if(-not $mp.Success){ Write-Error 'NO-PROTECTED-HASH' } elseif($mp.Groups[1].Value -ne $protHash){ Write-Error 'ROADMAP-PROTECTED-CHANGED' }; $baseHead=[regex]::Match($sec,'(?m)^基线 HEAD(10-54 用户审阅):([0-9a-f]{7,40})').Groups[1].Value; $sb=[regex]::Match($sp,'(?m)^BASE-HEAD: ([0-9a-f]{7,40})'); if(-not $sb.Success){ Write-Error 'SUMMARY-NO-BASE-HEAD' } elseif($sb.Groups[1].Value -ne $baseHead){ Write-Error 'BASE-HEAD-MISMATCH' }; $paths=@('docs/advanced/ii','docs/.vitepress/components/demos/ui','docs/.vitepress/config.ts','docs/advanced/index.md','.planning/ROADMAP.md','.planning/STATE.md','.planning/phases/10-docs-restructure/10-53-READER-REVIEW.md','.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md','.planning/phases/Line truncated
if($LASTEXITCODE -ne 0){ $log | Write-Output; Write-Error 'GIT-LOG-FAIL' }; if(($log | Out-String).Trim().Length -gt 0){ $log | Write-Output; Write-Error 'PLAN-FILES-COMMITTED' }; $status=cmd /c "git status --porcelain -- $($paths -join ' ')" 2>&1
if($LASTEXITCODE -ne 0){ $status | Write-Output; Write-Error 'GIT-STATUS-FAIL' }; if(($status | Out-String).Trim().Length -eq 0){ Write-Error 'PLAN-FILE-CLEAN' }; 'CLOSEOUT-OK'</automated>
<fails_when>non-zero exit, or output contains "MISSING-", "NO-HUMAN", "PENDING-ITEMS", "NO-PLACEMENT-SECTION", "NO-BASE-", "PROTECTED-LINE-COUNT", "SUMMARY-MISSING", "SUMMARY-LF-ONLY", "SUMMARY-NO-BASE-HEAD", "BASE-HEAD-MISMATCH", "ROADMAP-MISSING", "ROADMAP-NO-NOTE", "ROADMAP-PLANS-CHANGED", "ROADMAP-UNCHECKED-MISSING", "ROADMAP-PROTECTED-CHANGED", "STATE-NO-BATCH", "STATE-TOTAL-CHANGED", "STATE-COMPLETED-CHANGED", "DEMO-MODIFIED", "GIT-LOG-FAIL", "GIT-STATUS-FAIL", "PLAN-FILES-COMMITTED", "PLAN-FILE-CLEAN"; or output lacks "CLOSEOUT-OK"</fails_when>
</verify>
<acceptance_criteria>SUMMARY 完整(25 篇 / 24 demo、12 个计划、D-93、读者循环结论(不列问题清单)、用户审阅结论、落位选择、未做事项、计数口径(收口仍归 10-41、另行派发)、`BASE-HEAD` / `CURRENT-HEAD` / `PLAN-FILES-COMMITTED: none`);ROADMAP 追加 10-43..10-54 十二条与「10-43 增量说明」,`**Plans:**` 计数行与基线逐字一致,`10-06` / `10-11` / `10-12` 保持未勾选,未新增/删除 `10-33`..`10-41`;STATE 追加本批记录且计数与基线一致;NOTES 有用户确认、live 通过、落位评估、基线原文,无 `状态:待处理`;SUMMARY 的 `BASE-HEAD:` 与 NOTES 基线逐字相同;受保护行(三行未勾选 + `10-42 增量说明` 行,共四行)UTF-8 哈希一致;`git log <基线>..HEAD -- <本批关键路径>` 为空且 `git status --porcelain` 仍有输出(未 commit)。</acceptance_criteria>
<done>SUMMARY 与两处账本追加完成,基线与未提交状态可复查。</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| 读者循环 → 用户审阅 | 用户只看最终文档;读者记录不交给用户 |
| 用户意见 → 文档修订 | 只改用户点名内容;判「设计如此」的不改 |
| 用户确认 → 最终门禁 | 用户确认后才跑最终门禁与更新账本 |
| 落位评估 → 分区迁移 | 只记录选项与用户选择;迁移另行派发 |
| 修订 → 记账 | 只追加记录,不提交 |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-10-201 | Information Disclosure | 把读者记录交给用户 | high | mitigate | Task 0/1/2 明确不提供;Task 1 断言审阅文件不含读者记录路径;Task 3 复检 |
| T-10-202 | Tampering | 把读者问题转成用户裁决项 | high | mitigate | Task 2 只记录用户原话;禁止「读者说」推动裁决 |
| T-10-203 | Tampering | 改动超出用户点名范围 | high | mitigate | Task 2 只按 U 编号点名改;每轮回报文件与段落 |
| T-10-204 | Tampering | 把「设计如此」的内容改掉 | high | mitigate | 用户原话写入记录;判「设计如此」的不得出现在改动摘要 |
| T-10-205 | Tampering | ROADMAP / STATE 误改其它批次 | high | mitigate | 自动断言 `10-06` / `10-11` / `10-12` 仍在、`**Plans:**` 基线未变、计数保持、受保护行(三行未勾选 + `10-42 增量说明` 行,共四行)UTF-8 哈希一致 |
| T-10-206 | Denial of Service(构建不可用) | 修订引入死链或类型错误 | high | mitigate | 每轮修订后 prettier + 构建;最终门禁要求 0 dead link、`docs/` 路径 0 类型错误、25 HTML |
| T-10-207 | Repudiation | 未提交证明缺失或伪造 | medium | mitigate | SUMMARY 三行 + NOTES 基线 + `git log <基线>..HEAD` 为空 + `git status --porcelain` 非空 |
| T-10-208 | Elevation of Privilege | 落位评估变成实际迁移 | medium | mitigate | Task 4 只记录 A/B/C/D 与理由;明确「不执行迁移」 |
| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 |
</threat_model>
<verification>
- 关卡门禁:Task 0 已获「可以执行」;Task 2 用户明确确认;NOTES 含 `用户确认(10-54):可以执行`、`用户审阅:已完成`、`用户人工验证(10-54):通过`,无 `状态:待处理`。
- D-92 门禁:用户审阅记录不含读者记录路径 / 问题清单 / 分诊表 / 修订日志;Task 0/2 未向用户提供读者记录。
- 审阅门禁:`10-54-USER-REVIEW.md` 从 `U-01` 起逐条记录用户原话、裁决与改动;判「设计如此」的内容未被改动;每轮 prettier / 构建有结果。
- 导览门禁:`docs/advanced/ii/index.md` 25 条链接与侧边栏逐条对齐,目录表含六个 `### Part N` 与表头三列(篇目 / 能让你做什么 / 前置,空白容忍),页面开头为「四条阅读路径」、阅读路径段为「四条路径」、数据端句为「数据端三条路径都建议先读」、含「界面定制」且入口句为「界面定制从 UI 通用模板开始,不需要先读数据端」;`docs/advanced/index.md` 的「高级 II」主题含「自定义 UI 与渲染」且有性能边界;两页不含旧渲染端表述。
- 最终门禁:prettier `--check`、ESLint 0/0、`docs/` 路径 0 类型错误、25 篇结构断言、24 demo 断言、侧边栏各一次、构建 green + 0 dead link、25 个 HTML。
- live 门禁:用户完成 25 篇 + 24 demo + 侧边栏复验(含前序 deferred),NOTES 记录 `用户人工验证(10-54):通过`。
- 落位门禁:NOTES 有 `## 落位评估`,含四选项、推荐理由、用户选择与「不执行迁移」说明。
- 记账门禁:ROADMAP 追加十二条 + 增量说明且计数行未变;三行未勾选计划仍在、受保护行哈希不变;STATE 追加本批记录且计数保持基线;SUMMARY 的 `BASE-HEAD:` 与 NOTES 基线逐字相同;`git log <基线>..HEAD` 对本批路径为空、`git status --porcelain` 仍有输出。
- 越界门禁:未改 `packages/` / `packages-user/` / `src/`、24 个 demo、`10-01`..`10-53` 计划与 POC 文件;未 commit。
</verification>
<success_criteria>
- 用户只依据最终 25 篇与 live 完成审阅,逐条裁决并明确确认;未向用户提供读者记录。
- 导览、侧边栏、正文三者一致;全站构建 green、0 dead link、`docs/` 路径 0 类型错误、25 个 HTML 与 24 个 demo 合规。
- 全站 live 复验通过(含前序 deferred 项);落位评估有结论与用户选择,但未在本计划内迁移。
- SUMMARY 与 ROADMAP / STATE 追加完成,基线未被篡改,本批未产生 commit。
</success_criteria>
<output>
Create `.planning/phases/10-docs-restructure/10-54-SUMMARY.md` when done
</output>
@@ -0,0 +1,36 @@
# 10-54 Summary:用户审阅与文档收尾
## 结果
- 非示例 UI 文档审阅完成;6 篇示例文档保留现状,标记为待审阅。
- 文档审阅计划标记为完成(带待审阅项),但不宣称 25 篇 UI 文档全部完成审阅。
- 本轮未改源码、demo、配置或其它正文;未 commit。
## 范围
- 目标目录:`docs/advanced/ii/ui/`,共 25 篇。
- 已审阅:19 篇非示例文档。
- 待审阅:
- `inventory-example-1-skeleton.md`
- `inventory-example-2-grid.md`
- `inventory-example-3-detail.md`
- `inventory-example-4-scroll.md`
- `inventory-example-5-state.md`
- `inventory-example-6-animation-and-register.md`
## 审阅与修订记录
- 用户审阅轮次、意见与裁决见 `10-54-USER-REVIEW.md`,历史轮次 append-only。
- 非示例文档已按用户意见修订;`ui-performance.md` 最终按历史 `docs/guide/ui/perf.md` 的“日常优化习惯”方向重写。
- 示例文档未进入本轮审阅,不作为已完成项。
## 验证
- 最近一次相关文档构建:`build complete`,0 dead link。
- 未执行 commit;当前 HEAD:`e25ef3948141a241834c271040981c29dea3fb3e`。
- `PLAN-FILES-COMMITTED: none`。
## 后续
- 示例部分 1-6 待审阅;后续单独进入审阅流程。
- Phase 10 的计数收口仍按既有约定由后续收尾计划处理。
File diff suppressed because it is too large. Load diff
@@ -225,6 +225,62 @@
- **D-88(详略与长度):** 篇幅由内容决定。原理与架构层必须讲透设计理由、对象职责和数据流;不能为了「精简」删掉核心模型,也不能为了凑长度堆接口表和边角。只写常见、容易触发或容易误解的边界,其余交给引擎告警/日志。
- **D-89(正确性责任与审阅):** 文档正确性由写作者和用户负责。独立读者只读文档、按前置顺序阅读,只提出「读完后仍无法从文档得到答案」的问题;不读源码、不判断对错、不提修改方案。审阅记录只追加、不覆盖。
- **D-90(提交节奏):** 文档修订循环中**不逐轮提交**;由用户明确确认后,再统一提交一次。
- **D-91(独立读者人格审阅是内部循环,记录不交用户):** 读者审阅只用于验证目标读者能否只靠文档完成 UI 编写,属于内部质量环节,不是用户审阅。
1. **读者**:与写作者不共享上下文;只读 Markdown,不读源码,不做 live;只提出「读完后仍无法从文档得到答案」的问题,不判断对错、不提修改方案。
2. **派发**:由 orchestrator 分别派发多个独立读者(按 Part/篇目分组),**不得由一个子代理包办全部篇目**;每轮复审使用新上下文,不复用上一轮问题清单。
3. **循环上限 3 轮**:每轮汇总后只修**阻断性问题**——缺前置、术语未定义、步骤缺失导致无法继续、明确矛盾、缺 import/入口等。设计取舍、风格、详略、是否补充内容不属于阻断问题,不当作缺陷。
4. **复审与停止**:每轮修订后重新派读者复审;连续一轮无阻断问题即结束。3 轮后仍有阻断问题,停止并只报告受影响的页面/章节,**不向用户展示读者问题清单**。
5. **记录**:每轮问题、分诊、修订、复审结论写入内部记录,append-only,带 `### 第 N 轮` 标题;不写入 docs 正文,不交给用户。
6. **验收**:最终一轮无阻断问题;docs 通过构建/类型/lint;读者记录完整;未把读者问题当作用户裁决项。
- **D-92(用户审阅只看最终文档):** 用户审阅与读者人格审阅相互独立;用户只审阅修订完成的最终文档。
1. **输入**:只把最终 25 篇文档(及 live demo)交给用户阅读;**不提供**读者审阅记录、问题清单、分诊表、修订日志。
2. **意见**:用户按自己的阅读/使用体验提出意见;每条由用户裁决「改 / 不改 / 改成什么」;执行器只改用户点名内容。
3. **独立性**:不得把读者问题转成用户待裁决项,也不得用读者问题替代用户审阅。
4. **收尾**:循环直到用户明确确认;用户确认前不写 SUMMARY、不改 ROADMAP/STATE、不宣称完成。
5. **验收**:用户确认原文 + 独占标记;最终门禁通过;文档为最终版。
- **D-93(文档深度:讲清模型、事件与组件,禁止只给“能干啥/参数表”):** 本批 UI 文档必须让读者能自己写出 UI,而不是照抄;只列能力和参数不算讲清楚。
1. **渲染树模型**:必须讲清根/容器/子元素的树结构、坐标与变换如何沿树传递、`zIndex` 与绘制/命中顺序、元素生命周期、缓存/脏更新与渲染树的关系,以及组件如何映射成渲染树。
2. **事件模型**:必须讲清命中测试、捕获与冒泡的顺序、enter/leave 的特殊处理、`noevent` / `actionStroke` 对命中的影响、事件对象与嵌套容器中的传播;不能只列事件名。
3. **元素与组件用法**:每个元素与内置组件都要讲具体使用方式、重要功能、典型组合与场景、注意事项和“为什么这样设计”,不能只写“能做什么 / 参数有什么”。
4. **示例与解释并重**:示例要服务于机制理解;每次给出代码后解释它在渲染树 / 事件 / 组件模型中的位置与理由,不能只给可复制代码。
5. **修订传递**:10-49 读者循环与 10-50 用户修订的修订者,除了审阅结论,还必须收到本条要求;修订与复审时同时检查“是否讲清模型、事件与组件用法”,不能只修列出的问题。
6. **验收**:读者能复述渲染树、捕获/冒泡、组件拆分与 props/slots/attrs 的作用;能独立改写示例,而不是只能照抄。
- **D-94(读者审阅的标准阅读范围与顺序):** 读者审阅必须**先完整读完目标文档之外的全部文档**,再读目标文档;不得读任何其他内容。
1. **先读非目标文档**:按文档站的前置顺序读完目标之外的全部文档(本批为中级 → 高级 I → 高级 II 现有数据端 → 高级 III,以及其它非目标文档),目的是知道哪些概念、入口、约定已经在别处讲过。
2. **再读目标文档**:本批目标为 `docs/advanced/ii/ui/` 下的 25 篇,按 Part 0→5 顺序读。
3. **只对目标提问**:问题只针对目标文档;可以引用非目标文档说明「这里已经讲过 / 与前文冲突 / 前置不足」,但不得把非目标文档本身当成审阅对象。
4. **不得读其他内容**:不读源码、不读计划、不读旧文档、不读上一轮审阅记录、不读无关文档;避免用代码或实现污染读者上下文。
5. **每轮适用**:Round 1/2/3 的每个新读者都必须执行本顺序;不得只读目标文档或只看导览。
6. **验收**:读者记录必须列出「读过的非目标文档 + 目标文档」;未读非目标文档的审阅记录无效,需要重跑。
- **D-95(结构/流程必须配 mermaid 图):** CONTEXT D-01 已允许 mermaid(`vitepress-plugin-mermaid` 已安装);本批 UI 文档必须实际使用,不能只用段落描述结构或流程。
1. **必须用图的场景**:渲染树/元素树、坐标与变换/`zIndex`/命中顺序、事件捕获/冒泡、UI 栈与打开关闭、组件数据流与 props/slots/attrs、完整示例的步骤与组件拆分、缓存/脏更新流程。
2. **位置与篇幅**:图放在对应机制小节开头或示例前,配 1–3 句说明;图与正文不重复废话。
3. **格式**:使用 VitePress 的 ` ```mermaid ` 代码块;不引入新依赖。
4. **复审口径**:该有图的地方没有图,视为 D-93 深度缺口;不得用文字堆代替图。
- **D-96(整屏 UI 用 `FULL_LOC`,480×320 只是预览):** 整屏 UI 的顶层容器必须使用引擎的 `FULL_LOC`(`src/client/uiConstant.ts`),不得写死 480×320。
1. **标准写法**:整屏 UI 的顶层 `container` 写 `loc={FULL_LOC}`;`FULL_LOC` 由引擎按实际画布计算,不能假设画布是 480×320。
2. **预览尺寸**:文档站 live 可用任意预览尺寸(如 480×320),但**正文不写预览尺寸说明**;live 只负责展示效果,不要求与真实画布一一对应。
3. **独立面板**:可以有自己的设计尺寸,但必须说明它不是游戏画布尺寸;不要把它和 `FULL_LOC` 混用。
4. **修复节奏**:已经审阅/修改过的文档立即改为 `FULL_LOC`;尚未审阅的文档在后续审阅到该页时再改,不做全批批量替换。
- **D-97(文档不写修复说明/元叙述):** 文档正文只写给读者看的内容;不写「之前讲过 / 已经改好 / 不要这样做 / 我修复了 X / 文档站没有环境所以这里不画图 / 不要现场 new Texture」这类修复过程、问题复盘或元叙述。用户反馈只用于修改文档,不把反馈或修复结论抄进正文。
- **D-98(容器裁剪与 `nocache`):** 默认情况下,容器外的内容**不可见**;`nocache` 可能让超出容器的内容显示,但这是渲染实现的特性,后续可能变动,文档不得依赖或推荐。不得写「容器不裁剪 / 超出容器仍然可见 / 0×0 容器看得见但点不到」这类说法。
- **D-99(默认给混合方案):** 用户说「也可以 X / 不要只给 Y」时,默认保留 Y 并加入 X,给出混合示例(如 `fill` / `stroke` / `fill + stroke` 三种),不要把 Y 全量替换成 X;只有用户明确说「全部换成 X」才全量替换。
- **D-100(文字页与后续不写元素层 TS):** 文字页先讲 `Font` 字体类,再讲 `<text>` 用法;不再写独立的元素层 TypeScript 示例(`new Text()`、元素层导入、`Font` 静态调用代码块等)。需要构造 `Font` 时用 TSX 内联表达式或文字说明;后续文档同样只写 TSX 用法、live 与说明。文字属性要覆盖 `text`、`font`、`fillStyle`、`strokeStyle`、`strokeWidth`,并说明测量尺寸、锚点、对齐与不换行。
- **D-101(文字坐标/锚点与通用属性组织):** 文字页统一用 `loc={[x, y]}` + `anc={[ax, ay]}` 的简写形式;讲清 `FontWeight` 枚举(`Light = 300`、`Normal = 400`、`Bold = 700`)。`alpha`、`zIndex`、`hidden`、`noevent`、`rotate`、`scale`、`cache`/`nocache` 等通用属性不在元素页展开,统一留到后面集中讲;已从文字页与基础图形页移除。
- **D-102(live 必须就近放置):** 文档的 live 要放在对应知识点旁边,不能只在文末放一个综合 live。讲解法、字体、属性、锚点等每个需要看效果的小节,各自配一个 live;后续所有文档同样适用。
- **D-103(图片页只讲贴图管理器):** 图片与纹理页只讲从 `props.state.materials` 取已登记贴图(`getImageByAlias`,必要时提 `getImage`),再交给 `<image>`;不讲 `new Texture`、手动加载、画布、URL 等其他来源。`hd` / `anti` / `noanti` / `noevent` / `alpha` 等通用属性留到后面集中讲,不在图片页展开。
- **D-104(文档修订前必须读源码):** 每次派发文档修订子代理前,任务必须要求其先读相关 `props.ts`、元素/组件实现、管理器接口与现有用法,逐条核对可空性、默认值、属性行为;旧文档只作素材,不能当事实来源。执行器交付时附源码依据(文件:行号),主代理抽查;构建通过不等于语义正确。
- **D-105(应用场景必须有内在原因):** 可以写应用场景,但必须能从属性语义、限制或代价推导出原因;不能假设“常用于/只用于”某场景。禁止没有逻辑链路的扩展(如为 `image` 造 `Icon` 子组件)。元素页仍不主动扩展工程封装等超范围内容。
- **D-106(层级/变换页范围):** 通用参数页已覆盖 `zIndex`/`hidden`/`alpha`/`filter`;层级、变换与性能页只讲 `scale`/`rotate`/`transform`、`cache`/`nocache`、`composite` 与性能取舍,不讲 `noevent`/`type`/`fall`。`alpha`/`filter` 不是继承属性,但缓存父级会作用在整张缓存结果上,因此子元素会被一起影响;未缓存的父级不会把这两个属性传给子元素。
- **D-107(提问先回答,不直接改):** 用户以提问语气询问原因、机制、现象或“是不是……”时,先解释/回答,不得直接修改文件或派发执行;只有用户明确要求修改后才动手。即使已经判断出可修项,也先说明并等待用户决定。
- **D-108(标题统一用名词短语):** 文档 H2/H3 标题一律用名词短语,不用句子、祈使句或问句;例如「指令与分组」「数据到渲染」,不写「指令与分组定义在……」「数据变化如何走到……」。后续文档同样适用。已审阅的渲染系统文档统一扫描修正;用户尚未审阅的文档先不改。
- **D-109(按读者需求取舍内容):** 写文档先想读者需要知道什么,而不是把知道的细节全写进去。重点是「怎么用、怎么运行、怎么写能运行、常见错误怎么处理」;不要堆砌罕见边界、极少遇到的异常处理、底层原理和无关细节。内容过多会让文档失去可读性,宁可少写、写清楚。
- **D-110(UI 示例必须遵循标准模板):** 文档里的 UI 代码示例必须使用 `ui-template.md` 的标准结构。完整示例包含 imports、`MyPanelProps`、`myPanelProps`、`GameUI`、`FULL_LOC`;后续简化示例只能用 `// setup` + `// 组件内容` 的形式,不能写成 `export default defineComponent(() => ...)` 这类项目模板之外的 demo 包装。live 组件由文档渲染器挂载,不受此限;但文档正文不能把 live 包装当成 UI 入口写法。
- **D-111(value 双向绑定统一用 `v-model:value`):** 任何组件的 `value` 双向绑定一律写 `v-model:value={...}`,不要写裸 `v-model`,也不要手写 `onUpdate:value`。其它 prop 的双向绑定写 `v-model:prop`(如 `v-model:page`、`v-model:selected`)。
- **D-112(渲染端指南的后续重构):** 渲染端 UI 文档内容多且集中,不拆到不同阶段。当前审阅结束后另开计划:新增“渲染端指南”专页,内部分为渲染基础、渲染进阶、渲染底层,按不同深度组织;普通中级/高级教程仍穿插渲染端内容,但只讲主要逻辑,不细讲原理和 UI 代码为什么这么写。每篇文档增加“前置知识”部分,列出必须先读的文档。当前先记录,不移动文档。
- **D-113(接口必须先说明是什么):** 文档里出现任何接口、成员或类型时,必须先说明它的名称、类型/形态和用途,再讲它能做什么;不能只列接口名并假设读者已经知道。不要把引擎内部接口、内部成员写进用户文档;用户常用接口按使用频率放在主要位置,不要塞进“其他接口”。
- **D-114(excitation 执行顺序与 transition 端点判断):** excitation 执行不同激励对象的顺序不保证;在 `onExcitedFunc` 中用“当前值是否等于 min/max 端点”来决定下一目标,可能在起始帧设置目标后、Transition 尚未推进时,下一帧又因当前值仍在端点而重复设置同一目标,导致动画永远停在起点。`Selection` 的 alpha 来回切换就是典型案例。这是系统“设置当帧不改变值”的既定行为,不是系统 bug,只能在实现层规避:不要用当前值等于端点作为切换条件,改用独立状态、方向变量或事件驱动;后续文档涉及 `Selection`、`Transition`、`onExcitedFunc` 动画时需专门提醒。
- **D-115(文档修改前的全量阅读,强制,不得再遗漏):** **任何文档修改子代理在动手前,必须先按文档站阅读顺序完整读完目标文档之外的全部现有文档**:中级 → 高级 I → 高级 II 现有数据端/其他已存在篇目 → 高级 III → 其他非目标文档;读完后才能读目标文档和相关源码。**未完成全量阅读不得修改,不得以“只读了相关源码/目标页”代替。** 每次派发任务必须把本要求原文写入任务,并**明确说明阅读目的**:一是了解项目整体结构、已讲概念与文档分工,避免写出与现有内容脱节的说明;二是对齐文档的写作风格、详略、示例、标题、术语与表格形式,避免只读目标页造成风格偏差。**不得只列阅读清单而不说明目的,也不得把“读文档”本身当成任务。** 要求子代理在回报中列出已读文档范围及对结构与风格的实际判断;未列出、未读全或未说明目的的改动一律视为不合格,必须重做。此条与 D-94 的读者全量阅读要求并列,适用于所有文档修改子代理,**不得以时间、并行、上下文限制或任务简单为由跳过**。
</decisions>
@@ -0,0 +1,969 @@
# 10-43..10-54 记录:高级 II 子分组「自定义 UI 与渲染」
本文件记录 10-43..10-54 的命名、参考清单哈希、门禁与人工验证,只追加不改写(计划顺延与重排说明见文末;10-49..10-54 为 2026-11-01 重排后新增或替换)。
## 命名总表
| 项 | 最终值 |
|----|--------|
| 子分组名 | 自定义 UI 与渲染 |
| 目录 | `docs/advanced/ii/ui/` |
| 分组 1 | 起步(Part 0) |
| 分组 2 | 元素与布局(Part 1) |
| 分组 3 | 交互与数据(Part 2) |
| 分组 4 | 组件化(Part 3) |
| 分组 5 | 内置组件与 UI 系统(Part 4) |
| 分组 6 | 完整示例(Part 5) |
| demo 目录 | `docs/.vitepress/components/demos/ui/` |
| 侧边栏层级 | 高级 II → 子分组「自定义 UI 与渲染」→ 6 个 Part 分组 → 篇目(两层嵌套) |
| 落点 | 先全部写进高级 II 的新子分组;合并 / 拆分评估留到 10-50 |
| 导览更新时机 | 本计划只做措辞修正 + 子分组入口;完整目录表留到 10-50 收尾 |
### 27 篇文件名与侧边栏显示名
| 序 | 文件名 | 侧边栏显示名 | live | demo 文件 |
|----|--------|--------------|------|-----------|
| 1 | `ui-template.md` | UI 通用模板(TSX) | 是 | `template-demo.tsx` |
| 2 | `ui-template-ts.md` | 同一 UI 的 TS 元素层写法 | 是(复用 template-demo) | `template-demo.tsx` |
| 3 | `container-and-coordinates.md` | 容器与坐标 | 是 | `container-demo.tsx` |
| 4 | `basic-shapes.md` | 基础图形 | 是 | `shapes-demo.tsx` |
| 5 | `curves-and-paths.md` | 曲线与路径 | 是 | `curves-demo.tsx` |
| 6 | `text.md` | 文字 | 是 | `text-demo.tsx` |
| 7 | `image-and-texture.md` | 图片与最小纹理 | 是(10-44) | 待 10-44 建 |
| 8 | `layer-transform-performance.md` | 层级、变换与性能 | 是(10-44) | 待 10-44 建 |
| 9 | `reactivity.md` | 响应式 | 是(10-44) | 待 10-44 建 |
| 10 | `events.md` | 事件与交互 | 是(10-44) | 待 10-44 建 |
| 11 | `hotkey-in-ui.md` | 按键与快捷键 | 否(10-44 按需) | — |
| 12 | `conditional-and-list-rendering.md` | 条件渲染与循环渲染 | 是(10-44) | 待 10-44 建 |
| 13 | `props.md` | props | 是(10-45) | 待 10-45 建 |
| 14 | `component-tsx.md` | 组件(TSX) | 是(10-45) | 待 10-45 建 |
| 15 | `component-ts.md` | 组件(TS 直调) | 是(10-45) | 待 10-45 建 |
| 16 | `slots-and-attrs.md` | slots 与 attrs | 是(10-45) | 待 10-45 建 |
| 17 | `builtin-text-and-input.md` | 内置组件:文本与输入 | 按需(10-46) | 待 10-46 建 |
| 18 | `builtin-list-and-containers.md` | 内置组件:列表与容器 | 按需(10-46) | 待 10-46 建 |
| 19 | `ui-controller-and-stack.md` | UIController 与 UI 栈 | 是(10-46) | 待 10-46 建 |
| 20 | `replace-builtin-ui.md` | 修改 / 替换内置 UI | 是(10-46) | 待 10-46 建 |
| 21 | `ui-performance.md` | UI 系统性能与注意事项 | 是(10-46) | 待 10-46 建 |
| 22 | `inventory-example-1-skeleton.md` | 示例(一)目标与骨架 | 是(10-47) | 待 10-47 建 |
| 23 | `inventory-example-2-grid.md` | 示例(二)道具网格 | 是(10-47) | 待 10-47 建 |
| 24 | `inventory-example-3-detail.md` | 示例(三)详情区 | 是(10-47) | 待 10-47 建 |
| 25 | `inventory-example-4-scroll.md` | 示例(四)滚动与列表 | 是(10-47) | 待 10-47 建 |
| 26 | `inventory-example-5-state.md` | 示例(五)交互与状态 | 是(10-47) | 待 10-47 建 |
| 27 | `inventory-example-6-animation-and-register.md` | 示例(六)动画、拆分与注册 | 是(10-47) | 待 10-47 建 |
### 本计划(10-43)五个 demo
| 文件 | 组件名 |
|------|--------|
| `template-demo.tsx` | `TemplateDemo` |
| `container-demo.tsx` | `ContainerDemo` |
| `shapes-demo.tsx` | `ShapesDemo` |
| `curves-demo.tsx` | `CurvesDemo` |
| `text-demo.tsx` | `TextDemo` |
用户确认(10-43):可以执行
用户原文:可以执行(批准执行 10-43..10-47;10-48 读者/用户审阅前停下)
基线 HEAD:b94b4c3b41da8184312bc9f264654dc9a54adf69
## 参考清单哈希基线
哈希为 `git hash-object -- <path>` 实测值;Manifest 列取自 `10-CUSTOM-UI-RESEARCH.md` 的 `## Reference Manifest`(基线 `b94b4c3`)。
| 路径 | Manifest 哈希(HEAD) | 写作前实测 | 是否一致 |
|------|-----------------------|------------|----------|
| `packages/render/src/core/item.ts` | `1acd9193d1b0e3121af1dd74ccef25f3dcc7124f` | `1acd9193d1b0e3121af1dd74ccef25f3dcc7124f` | 是 |
| `packages/render/src/core/types.ts` | `31d9120f43d34757aa5936731bc16ebb0ff39cd3` | `31d9120f43d34757aa5936731bc16ebb0ff39cd3` | 是 |
| `packages/render/src/core/graphics.ts` | `eebc2f659f2fda05e60cb48e6473ef05f134a5da` | `eebc2f659f2fda05e60cb48e6473ef05f134a5da` | 是 |
| `packages/render/src/core/misc.ts` | `3c19fd4d464df04a562a2951120df72ec6adbd2a` | `3c19fd4d464df04a562a2951120df72ec6adbd2a` | 是 |
| `packages/render/src/core/transform.ts` | `c3f38c52843027ff49373da20c707fcf0091f25f` | `c3f38c52843027ff49373da20c707fcf0091f25f` | 是 |
| `packages/render/src/core/canvas2d.ts` | `a9c80670c03866b95689413eaf7ed40781176c1d` | `a9c80670c03866b95689413eaf7ed40781176c1d` | 是 |
| `packages/render/src/style/font.ts` | `0e4541e22555140dd4afcf34fb88fbd91f2edb37` | `0e4541e22555140dd4afcf34fb88fbd91f2edb37` | 是 |
| `packages/render/src/assets/texture.ts` | `545e2ca46494a99f2c93e33b4d0c1c84d5b4d8fa` | `545e2ca46494a99f2c93e33b4d0c1c84d5b4d8fa` | 是 |
| `packages/render-vue/src/props.ts` | `27e0f9f3bb2fa63bf2d9d358af87078eebe56053` | `27e0f9f3bb2fa63bf2d9d358af87078eebe56053` | 是 |
| `packages/render-vue/src/elements.ts` | `39e0c20c93f3c0b84ad7148688eceac4ed89813b` | `39e0c20c93f3c0b84ad7148688eceac4ed89813b` | 是 |
| `packages/render-vue/src/tag.ts` | `7b0265a276dcbdc36c01eac709e4a35cbc7a13f0` | `7b0265a276dcbdc36c01eac709e4a35cbc7a13f0` | 是 |
| `packages/render-vue/src/types.ts` | `a90549e8c3bf07e5069107c414086edde65270b0` | `a90549e8c3bf07e5069107c414086edde65270b0` | 是 |
| `packages/render-vue/src/use.ts` | `b23674c3b3c143c22cfb6683ff9d2c47fff7ee2b` | `b23674c3b3c143c22cfb6683ff9d2c47fff7ee2b` | 是 |
| `packages/system/src/ui/controller.ts` | `25c3ea6f2bb3877989c65f25d3fc6dc3288ead7a` | `25c3ea6f2bb3877989c65f25d3fc6dc3288ead7a` | 是 |
| `packages/system/src/ui/types.ts` | `2a24550a6a3f8dade44524f7be2564f7d7957551` | `2a24550a6a3f8dade44524f7be2564f7d7957551` | 是 |
| `packages/system/src/ui/instance.ts` | `11a6ce881e5f1de32f232fd07c7bbc09a9e56203` | `11a6ce881e5f1de32f232fd07c7bbc09a9e56203` | 是 |
| `packages/system/src/ui/container.tsx` | `8eeddcad33bb5e3e70e4c66ad33b41dbece83e3d` | `8eeddcad33bb5e3e70e4c66ad33b41dbece83e3d` | 是 |
| `packages/system/src/ui/ui.ts` | `04b98c0ce7ce04c24c97906f5dd7261b1f53907a` | `04b98c0ce7ce04c24c97906f5dd7261b1f53907a` | 是 |
| `packages-user/client-base/src/types.ts` | `cdf7224dc39118665b00a9697c31e6f5ae7c4f84` | `cdf7224dc39118665b00a9697c31e6f5ae7c4f84` | 是 |
| `packages-user/client-modules/src/client.ts` | `3156c76b4a6fc6262f353259955bd06b6220da60` | `3156c76b4a6fc6262f353259955bd06b6220da60` | 是 |
| `packages-user/client-modules/src/ui/func.ts` | `bd7386412bc5e1c40e2cc06325a8f26809ad76` | `bd7386412bc5e1c40e2cc06325a8f26809ad76` | 是 |
| `src/bootstrap.ts` | `e0f678e8103ccdbf0e02b071af18f000d6f64214` | `e0f678e8103ccdbf0e02b071af18f000d6f64214` | 是 |
| `src/client/ui/main.tsx` | `3dc4f096cd1750707ba5bf56ea5597903235da11` | `3dc4f096cd1750707ba5bf56ea5597903235da11` | 是 |
| `src/client/ui/inputBox.tsx` | `3eb246200ae3300f9f221a8e0e9142e5a612a696` | `3eb246200ae3300f9f221a8e0e9142e5a612a696` | 是 |
| `src/client/ui/title.tsx` | `9658447b77dc4c0a1bbd13a4266402f3a2d2b773` | `9658447b77dc4c0a1bbd13a4266402f3a2d2b773` | 是 |
| `src/client/ui/load.tsx` | `b41ec3ddc145beae79424234f51198d2d78b7fd8` | `b41ec3ddc145beae79424234f51198d2d78b7fd8` | 是 |
| `docs/.vitepress/components/renderDemo.vue` | `8ed38a889ceb66ac06f2742f185e176adc010f35` | `8ed38a889ceb66ac06f2742f185e176adc010f35` | 是 |
| `docs/.vitepress/components/demos/basicRender.vue` | `1577085892cf6d6d4c77a0b45fe35bb5b612381e` | `1577085892cf6d6d4c77a0b45fe35bb5b612381e` | 是 |
| `docs/.vitepress/components/demos/uiSystem.vue` | `6cf03bcd72e100d28e43622ee0a1a1724cfd7639` | `6cf03bcd72e100d28e43622ee0a1a1724cfd7639` | 是 |
| `docs/.vitepress/config.ts` | `4d66cfc87aee8cea8e7e2a9f523fbc677d5fce37` | `4d66cfc87aee8cea8e7e2a9f523fbc677d5fce37` | 是(本计划会修改,属例外) |
| `docs/advanced/ii/index.md` | `df5bdfd3f228d7a5ea5380a9556f75d9c5b81871` | `df5bdfd3f228d7a5ea5380a9556f75d9c5b81871` | 是(本计划会修改措辞) |
| `docs/advanced/index.md` | `13a29d69669acba40a3cdf9b248d02ce7e1f35d4` | `13a29d69669acba40a3cdf9b248d02ce7e1f35d4` | 是(本计划会修改措辞) |
| `docs/tsconfig.json` | `07705ee1ccb588ca4c9b355b9981b0a929caeb35` | `07705ee1ccb588ca4c9b355b9981b0a929caeb35` | 是(本计划会修改 include,属例外) |
| `src/client/ui/choices.tsx`(HEAD) | `1fbd21d16a0e30f0c10d0a94132268ee08f1ad76` | `1fbd21d16a0e30f0c10d0a94132268ee08f1ad76`(`git rev-parse HEAD:`) | 是 |
| `src/client/ui/choices.tsx`(工作树) | Manifest I 记录为 `d6f13d798e89b15079497194bdb459505b5834ea` | `d6f13d798e89b15079497194bdb459505b5834ea` | 是(与 HEAD 不同,只允许接口参考) |
规则:任一文件实测哈希与 Manifest 不一致、或 `git status --porcelain -- <path>` 非空(`docs/.vitepress/config.ts`、`docs/tsconfig.json`、两份导览本计划自己要改,除外),立即停下向用户报告,不得按旧内容继续写作。
### 10-44 参考哈希复核(2026-10-31)
`git hash-object -- <path>` 实测结果:
| 路径 | 实测 | 与 Manifest | `git status` |
|------|------|-------------|--------------|
| `packages/render/src/core/misc.ts` | `3c19fd4d464df04a562a2951120df72ec6adbd2a` | 一致 | 干净 |
| `packages/render/src/core/item.ts` | `1acd9193d1b0e3121af1dd74ccef25f3dcc7124f` | 一致 | 干净 |
| `packages/render/src/core/canvas2d.ts` | `a9c80670c03866b95689413eaf7ed40781176c1d` | 一致 | 干净 |
| `packages/render/src/core/transform.ts` | `c3f38c52843027ff49373da20c707fcf0091f25f` | 一致 | 干净 |
| `packages/render/src/assets/texture.ts` | `545e2ca46494a99f2c93e33b4d0c1c84d5b4d8fa` | 一致 | 干净 |
| `packages/render/src/core/event.ts` | `6a0999e6f4b7f3bf3084195a97411d87c884d98f` | 一致 | 干净 |
| `packages/render/src/core/container.ts` | `e01b5122fc2d3685648c28db6932919c554c98d6` | 一致 | 干净 |
| `packages/system/src/hotkey/types.ts` | `600432021f3f253730d3421fd1a5fb80fafd92e1` | 一致 | 干净 |
| `packages/system/src/hotkey/command.ts` | `8d99e6a364943f34c962e7b6461a97f6d23e75ca` | 一致 | 干净 |
| `packages/system/src/hotkey/system.ts` | `da87e18a7e6c8ae951f73bfaf7daf22a7a53e0c5` | 一致 | 干净 |
| `packages-user/client-base/src/hotkey/hotkey.ts` | `9344fabb5d902ad18482ede6277513998c5db2b1` | 一致 | 干净 |
| `packages-user/client-base/src/use/hotkey.ts` | `75e7f716a7655301d969285e22388414db1eb3c3` | 一致 | 干净 |
结论:本计划涉及的全部参考文件与 Manifest 基线一致,工作树对本批参考路径无改动,可按现有内容写作。
## 写作硬规则
1. 目标读者完全没写过 UI;只讲写 UI 必需的 Vue 概念,不讲初始化。
2. 示例一律 TSX;条件写 `hidden` 或三元,循环写 `.map()`;`key` 只用于会重排/增删且需要保留身份的场景。
3. `hidden` = 不显示、不交互,保留元素与状态;三元会创建/销毁并重置状态。
4. 属性名一律 camelCase;容器自定义标签全批只写 `container-custom`。
5. UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`,`props` 数组至少含 `controller` / `instance` / `state`。
6. `update:xxx` 只作为 `v-model:xxx` 的使用说明出现,不教手动监听事件属性。
7. 组件内按键用 `useKey(props.state.hotkey.system)!`,不加多余类型守卫。
8. 正文不出现渲染器类名、渲染器初始化、标签注册,也不出现以 core 开头的命名空间。
9. 不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位。
10. 不写源码实现叙述与仓库行号;目标页已存在才写 `./xxx.md#标题`,后续批次才创建的页只写纯文本。
11. 代码块是完整、结构正确的文件 / 类 / 函数级片段,注释尽量写;编辑器产物不手写。
12. 单 `#` H1,按「问题 → 系统模型 → 机制 → 接口 → 示例 → 边界」组织,末尾 `## 边界与注意`;文件 CRLF,写完跑 prettier。
## 门禁记录
### 10-43 门禁
- 首次全量构建:green。命令 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`;输出 `build complete in 14.91s.`,无 dead link,仅有既有 chunk 体积警告。
- `docs/` 路径类型报错 0(`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`);既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条),既有、非本轮引入、不得修。
#### 10-43 六类门禁(Task 5)
| 门禁 | 命令 | 结论 |
|------|------|------|
| prettier `--write` | `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md"` | exit 0 |
| prettier `--check` | 同上路径 `--check` | `All matched files use Prettier code style!` |
| ESLint | `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"` | exit 0,0 error / 0 warning;渲染属性保持 camelCase |
| docs 类型 | `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` | `docs/` 路径类型报错 0;既有引擎报错 11 条(既有、非本轮引入、不得修) |
| 静态断言 | 6 篇正文 + 5 个 demo + 侧边栏 + `custom` 数组 + 兄弟分组 | `STATIC-OK` |
| 全量构建 | `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` | green,`build complete in 15.25s.`,无 dead link |
docs/ 路径类型报错 0;既有引擎报错 11 条(既有、非本轮引入、不得修)。
静态断言明细:6 篇均为单 H1、含 `## 边界与注意`、无被禁写法、`<ClientOnly>` + 动态 loader、CRLF;5 个 demo 默认导出、无 DOM 属性、CRLF;4 个 demo 零引擎 import,`text-demo` 仅允许 `@motajs/render` 的 `Font` 且为位置参数 `new Font('Verdana', 32, 'px', 700)`、无 `Font.defaults`;侧边栏 6 条链接齐全;`custom` 数组同时含 `container-custom` 与 `custom-container`;高级 II 既有条目与高级 III 分组未丢。
#### 本批清单(6 篇 + 5 个 demo)
| 页面 | live | demo |
|------|------|------|
| `docs/advanced/ii/ui/ui-template.md` | 是 | `docs/.vitepress/components/demos/ui/template-demo.tsx` |
| `docs/advanced/ii/ui/ui-template-ts.md` | 是(复用) | `docs/.vitepress/components/demos/ui/template-demo.tsx` |
| `docs/advanced/ii/ui/container-and-coordinates.md` | 是 | `docs/.vitepress/components/demos/ui/container-demo.tsx` |
| `docs/advanced/ii/ui/basic-shapes.md` | 是 | `docs/.vitepress/components/demos/ui/shapes-demo.tsx` |
| `docs/advanced/ii/ui/curves-and-paths.md` | 是 | `docs/.vitepress/components/demos/ui/curves-demo.tsx` |
| `docs/advanced/ii/ui/text.md` | 是 | `docs/.vitepress/components/demos/ui/text-demo.tsx` |
### 10-44 门禁
| 门禁 | 命令 | 结论 |
|------|------|------|
| prettier `--write` | `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"` | exit 0 |
| prettier `--check` | 同上路径 `--check` | `All matched files use Prettier code style!` |
| ESLint | `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"` | exit 0,0 error / 0 warning |
| docs 类型 | `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` | `docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条,既有、非本轮引入、不得修) |
| 静态断言 | 6 篇正文 + 5 个 demo + 侧边栏 + 回填链接 + 兄弟分组 | `STATIC-OK` |
| 全量构建 | `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` | green,`build complete in 15.35s.`,无 dead link |
docs/ 路径类型报错 0;既有引擎报错 11 条(与本轮无关,保持不动)。
静态断言明细:6 篇均为单 H1、含 `## 边界与注意`、无被禁写法、CRLF;五篇 live 有 `<ClientOnly>` + 动态 loader,按键篇无 live;5 个 demo 默认导出、无 DOM 属性;4 个 demo 零引擎 import,`texture-demo` 仅 import `@motajs/render` 的 `Texture`;侧边栏 12 条链接齐全(本批 6 条 + 10-43 的 6 条),`custom-range` 与高级 III 分组未丢;第 3 篇 `./layer-transform-performance.md` 与第 4 篇 `./events.md` 的回填链接均已生效。
交叉一致性:第 8 篇与第 12 篇对 `hidden` 的表述一致,均为「不显示、不交互」+「保留元素与状态」+「跳过绘制与命中」;第 6 篇对第 17 篇、第 9 篇对第 13 篇仍是纯文本前瞻引用,本批未引入任何指向未创建页面的链接。
#### 本批清单(6 篇 + 5 个 demo)
| 页面 | live | demo |
|------|------|------|
| `docs/advanced/ii/ui/image-and-texture.md` | 是 | `docs/.vitepress/components/demos/ui/texture-demo.tsx` |
| `docs/advanced/ii/ui/layer-transform-performance.md` | 是 | `docs/.vitepress/components/demos/ui/layer-demo.tsx` |
| `docs/advanced/ii/ui/reactivity.md` | 是 | `docs/.vitepress/components/demos/ui/reactivity-demo.tsx` |
| `docs/advanced/ii/ui/events.md` | 是 | `docs/.vitepress/components/demos/ui/events-demo.tsx` |
| `docs/advanced/ii/ui/hotkey-in-ui.md` | 否(文档站无游戏按键系统) | — |
| `docs/advanced/ii/ui/conditional-and-list-rendering.md` | 是 | `docs/.vitepress/components/demos/ui/conditional-demo.tsx` |
## 人工验证记录
(由 Task 6 追加;本轮在 10-48 独立读者审阅与 10-49 用户修订前停下,live 人工验证待最终人工审阅。
live 人工验证(10-43):待最终人工审阅。本轮未写「用户人工验证:通过」,也未把 live 关卡标记为完成。)
## 10-44 命名确认
用户确认(10-44):可以执行
用户原文:可以执行(批准执行 10-43..10-47;10-48 的读者/用户审阅前停下)
- 纹理方案:用 `document.createElement('canvas')` 画一个棋盘,再包成 `Texture`(Task 0 推荐方案,用户已随全局批准一并确认)。
- 按键篇 live:不配 live。文档站没有游戏的按键系统,配一个仅监听浏览器键盘的示例会误导读者;正文用一句话说明原因。
- 6 篇文件名与侧边栏显示名(沿用命名总表):`image-and-texture.md`「图片与最小纹理」、`layer-transform-performance.md`「层级、变换与性能」、`reactivity.md`「响应式」、`events.md`「事件与交互」、`hotkey-in-ui.md`「按键与快捷键」、`conditional-and-list-rendering.md`「条件渲染与循环渲染」。
- 5 个 demo:`texture-demo.tsx`(`TextureDemo`)、`layer-demo.tsx`(`LayerDemo`)、`events-demo.tsx`(`EventsDemo`)、`reactivity-demo.tsx`(`ReactivityDemo`)、`conditional-demo.tsx`(`ConditionalDemo`)。
- 基线:HEAD `b94b4c3b41da8184312bc9f264654dc9a54adf69`;参考清单哈希复核见上节「10-44 参考哈希复核」。
live 人工验证(10-44):待最终人工审阅。本轮未写「用户人工验证:通过」,也未把 live 关卡标记为完成。
## 10-45 命名确认
用户确认(10-45):可以执行
用户原文:可以执行(批准执行 10-43..10-47;10-48 的读者/用户审阅前停下)
- 四篇文件名与侧边栏显示名(沿用命名总表):`props.md`「props」、`component-tsx.md`「组件(TSX)」、`component-ts.md`「组件(TS 直调)」、`slots-and-attrs.md`「slots 与 attrs」。
- 第 14 篇示例组件选型:带选中态的道具格子(`ItemCell`),与第 23 篇完整示例复用同一概念。
- 两条界线都单独设小节:第 14 篇「组件与 UI 的区别」、第 15 篇「组件 vs 元素层类」,各控制在半页内。
- 4 个 demo:`props-demo.tsx`(`PropsDemo`)、`component-demo.tsx`(`ComponentDemo`)、`ts-component-demo.tsx`(`TsComponentDemo`)、`slots-demo.tsx`(`SlotsDemo`)。
- 基线:HEAD `b94b4c3b41da8184312bc9f264654dc9a54adf69`。
### 10-45 参考哈希复核(2026-10-31)
`git hash-object -- <path>` 实测结果:
| 路径 | 实测 | 与 Manifest | `git status` |
|------|------|-------------|--------------|
| `packages/render-vue/src/types.ts` | `a90549e8c3bf07e5069107c414086edde65270b0` | 一致 | 干净 |
| `packages/render-vue/src/props.ts` | `27e0f9f3bb2fa63bf2d9d358af87078eebe56053` | 一致 | 干净 |
| `packages/render/src/core/item.ts` | `1acd9193d1b0e3121af1dd74ccef25f3dcc7124f` | 一致 | 干净 |
| `packages/render/src/core/container.ts` | `e01b5122fc2d3685648c28db6932919c554c98d6` | 一致 | 干净 |
| `packages/render/src/core/custom.ts` | `440163608dec8818f0e2320d0b415a62e2061242` | 未列入基线 | 干净 |
| `packages/render/src/core/canvas2d.ts` | `a9c80670c03866b95689413eaf7ed40781176c1d` | 一致 | 干净 |
| `packages-user/client-base/src/types.ts` | `cdf7224dc39118665b00a9697c31e6f5ae7c4f84` | 一致 | 干净 |
| `packages-user/client-base/src/components/input.tsx` | `bfe65b06b9600f80a4d74f6ef222e55d13d09134` | 未列入基线 | 干净 |
| `packages-user/client-base/src/components/textbox.tsx` | `5b58de65007189314553be0aca48209bd9e25981` | 未列入基线 | 干净 |
| `docs/.vitepress/config.ts` | 本计划要改 | 属例外 | 已修改(前批) |
| `docs/advanced/ii/ui/reactivity.md` | 10-44 新建 | 未列入基线 | 未跟踪 |
结论:本计划涉及的参考文件与基线一致,工作树对本批参考路径无越界改动,可按现有内容写作。
### 10-45 门禁
| 门禁 | 命令 | 结论 |
|------|------|------|
| prettier `--write` | `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"` | exit 0 |
| prettier `--check` | 同上路径 `--check` | `All matched files use Prettier code style!` |
| ESLint | `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"` | exit 0,0 error / 0 warning |
| docs 类型 | `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` | `docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条,既有、非本轮引入、不得修) |
| 静态断言 | 4 篇正文 + 4 个 demo + 侧边栏 16 条 + 回填链接 + 兄弟分组 | `STATIC-OK` |
| 全量构建 | `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` | green,`build complete in 15.76s.`,无 dead link |
`docs/` 路径类型报错 0;既有引擎报错 11 条(与本轮无关,保持不动)。
静态断言明细:4 篇均为单 H1、含 `## 边界与注意`、无被禁写法、`<ClientOnly>` + 动态 loader、CRLF;4 个 demo 默认导出、无 DOM 属性、零引擎 import;侧边栏「组件化」4 条齐全(本批 4 条 + 前三批 12 条,共 16 条),`custom-range` 与高级 III 分组未丢;第 9 篇 `reactivity.md` 对第 13 篇的引用已回填为 `./props.md` 链接。
交叉一致性:第 13 篇的 `props` 声明(`props` 数组 + `satisfies SetupComponentOptions`)与第 14 篇的组件实现使用同一套写法;第 1 篇与第 14 篇的 UI 判定三要素表述一致,均为 Props 同时继承 `IGameUIPropsBase` 与 `DefaultProps`、`props` 数组包含 `controller` / `instance` / `state`、被 `GameUI` 注册。
#### 本批清单(4 篇 + 4 个 demo)
| 页面 | live | demo |
|------|------|------|
| `docs/advanced/ii/ui/props.md` | 是 | `docs/.vitepress/components/demos/ui/props-demo.tsx` |
| `docs/advanced/ii/ui/component-tsx.md` | 是 | `docs/.vitepress/components/demos/ui/component-demo.tsx` |
| `docs/advanced/ii/ui/component-ts.md` | 是 | `docs/.vitepress/components/demos/ui/ts-component-demo.tsx` |
| `docs/advanced/ii/ui/slots-and-attrs.md` | 是 | `docs/.vitepress/components/demos/ui/slots-demo.tsx` |
live 人工验证(10-45):待最终人工审阅。本轮未写「用户人工验证:通过」,也未把 live 关卡标记为完成。
## 10-46 命名确认
用户确认(10-46):可以执行
用户原文:可以执行(批准执行 10-43..10-47;10-48 的读者/用户审阅前停下)
- 五篇文件名与侧边栏显示名(沿用命名总表):`builtin-text-and-input.md`「内置组件:文本与输入」、`builtin-list-and-containers.md`「内置组件:列表与容器」、`ui-controller-and-stack.md`「UIController 与 UI 栈」、`replace-builtin-ui.md`「修改 / 替换内置 UI」、`ui-performance.md`「UI 系统性能与注意事项」。
- 契约取舍:示例为主 + 常用项表;`TextContent` 的 `width` 必填、`autoHeight`、`Input` 的 `v-model:value`、`List` 的 `v-model:selected`、`Scroll` 只对直接子元素生效这几条写全(Task 0 推荐方案,用户已随全局批准一并确认)。
- 第 20 篇力度:只讲「打开处替换 / 包装组件 / 显示策略与背景」三种改法,不复制源码(研究 Q5 推荐方案,随全局批准确认)。
- `Choices` 命名:正文标题用 `Choices(选项框)`,并注明「用户习惯叫 `ChoicesBox`,源码导出名是 `Choices` / `ChoicesUI`」(研究 Q6 推荐方案,随全局批准确认)。
- 5 个 demo:`builtin-text-demo.tsx`(`BuiltinTextDemo`)、`builtin-list-demo.tsx`(`BuiltinListDemo`)、`controller-demo.tsx`(`ControllerDemo`)、`strategy-demo.tsx`(`StrategyDemo`)、`perf-demo.tsx`(`PerfDemo`)。
- 落点:`docs/advanced/ii/ui/` 五篇;侧边栏「内置组件与 UI 系统」分组 5 条;demo 在 `docs/.vitepress/components/demos/ui/`。
- 修改方式:正文 / demo / 文档由 GSD 执行器(子代理)执行,未内联改动源码;未调用 `opencode` 命令;不 commit。
- 基线:HEAD `b94b4c3b41da8184312bc9f264654dc9a54adf69`;参考哈希复核见下节。
### 10-46 参考哈希复核(2026-10-31)
`git hash-object -- <path>` 实测结果:
| 路径 | 实测 | 与 Manifest | `git status` |
|------|------|-------------|--------------|
| `packages-user/client-base/src/components/textbox.tsx` | `5b58de65007189314553be0aca48209bd9e25981` | 一致 | 干净 |
| `packages-user/client-base/src/components/list.tsx` | `a6723454788b8fff22389bc5d19883c90a4eb5b5` | 一致 | 干净 |
| `packages-user/client-base/src/components/page.tsx` | `b18520460dd335385be901e535f222eedcb9941e` | 一致 | 干净 |
| `packages-user/client-base/src/components/scroll.tsx` | `809af86b816bdad643292afce85e106886dd5a99` | 一致 | 干净 |
| `packages-user/client-base/src/components/input.tsx` | `bfe65b06b9600f80a4d74f6ef222e55d13d09134` | 一致 | 干净 |
| `packages-user/client-base/src/components/misc.tsx` | `365e826610678276599e71f4f69ff42e30daef7f` | 一致 | 干净 |
| `packages/system/src/ui/controller.ts` | `25c3ea6f2bb3877989c65f25d3fc6dc3288ead7a` | 一致 | 干净 |
| `packages/system/src/ui/ui.ts` | `04b98c0ce7ce04c24c97906f5dd7261b1f53907a` | 一致 | 干净 |
| `packages/system/src/ui/instance.ts` | `11a6ce881e5f1de32f232fd07c7bbc09a9e56203` | 一致 | 干净 |
| `packages/system/src/ui/container.tsx` | `8eeddcad33bb5e3e70e4c66ad33b41dbece83e3d` | 一致 | 干净 |
| `packages/system/src/ui/types.ts` | `2a24550a6a3f8dade44524f7be2564f7d7957551` | 一致 | 干净 |
| `packages-user/client-modules/src/ui/func.ts` | `bd7386412bc5e1c40e2cc06325a8f26809ad76` | 一致 | 干净 |
| `packages-user/client-modules/src/client.ts` | `3156c76b4a6fc6262f353259955bd06b6220da60` | 一致 | 干净 |
| `src/client/ui/inputBox.tsx` | `3eb246200ae3300f9f221a8e0e9142e5a612a696` | 一致 | 干净 |
| `src/client/ui/choices.tsx`(HEAD) | `1fbd21d16a0e30f0c10d0a94132268ee08f1ad76` | 一致 | — |
| `src/client/ui/choices.tsx`(工作树,仅接口参考) | `d6f13d798e89b15079497194bdb459505b5834ea` | 与 Manifest I 一致 | `M`(既有改动,未碰) |
结论:本计划涉及的全部参考文件与 Manifest / NOTES 基线一致;`choices.tsx` 工作树哈希仍为 `d6f13d7…`,未再变化,只读 props / emits / 函数签名。可按现有内容写作。
### 10-46 门禁
| 门禁 | 命令 | 结论 |
|------|------|------|
| prettier `--write` | `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"` | exit 0 |
| prettier `--check` | 同上路径 `--check` | `All matched files use Prettier code style!` |
| ESLint | `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"` | exit 0,0 error / 0 warning |
| docs 类型 | `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` | `docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条,既有、非本轮引入、不得修) |
| 静态断言 | 5 篇正文 + 5 个 demo + 侧边栏 21 条 + 回填链接 + 兄弟分组 | `STATIC-OK` |
| 全量构建 | `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` | green,`build complete in 21.10s.`,无 dead link |
`docs/` 路径类型报错 0;既有引擎报错 11 条(与本轮无关,保持不动)。
静态断言明细:5 篇均为单 H1、含 `## 边界与注意`、无被禁写法、`<ClientOnly>` + 动态 loader、CRLF;5 个 demo 默认导出、无 DOM 属性、无引擎 / 用户包 import;侧边栏「内置组件与 UI 系统」5 条齐全(本批 5 条 + 前三批 16 条,共 21 条),`custom-range` 与高级 III 分组未丢;第 6 篇 `text.md` 与第 16 篇 `slots-and-attrs.md` 对第 17 篇的引用已回填为 `./builtin-text-and-input.md` 链接;第 8、12、21 篇的 `hidden` 表述都含「不显示、不交互」。
交叉一致性:第 19 篇「没有全局注册 / 覆盖入口」与第 20 篇「没有全局替换接口」表述一致;第 17 篇 `v-model:value`、第 18 篇 `v-model:selected` 与第 13 篇的 `v-model:xxx` 口径一致。
#### 本批清单(5 篇 + 5 个 demo)
| 页面 | live | demo |
|------|------|------|
| `docs/advanced/ii/ui/builtin-text-and-input.md` | 是(等价元素演示) | `docs/.vitepress/components/demos/ui/builtin-text-demo.tsx` |
| `docs/advanced/ii/ui/builtin-list-and-containers.md` | 是(等价元素演示) | `docs/.vitepress/components/demos/ui/builtin-list-demo.tsx` |
| `docs/advanced/ii/ui/ui-controller-and-stack.md` | 是 | `docs/.vitepress/components/demos/ui/controller-demo.tsx` |
| `docs/advanced/ii/ui/replace-builtin-ui.md` | 是 | `docs/.vitepress/components/demos/ui/strategy-demo.tsx` |
| `docs/advanced/ii/ui/ui-performance.md` | 是 | `docs/.vitepress/components/demos/ui/perf-demo.tsx` |
#### 已知限制(10-46)
- `packages-user/client-base/src/renderer` 在当前工作树不存在(`elements/index.ts` 与 `components/misc.tsx` 的 `../renderer` 引用未解析;属既有中间态,非本轮引入)。因此文档站无法静态 import `@user/client-base` 的内置组件(会触发 `Could not resolve "../renderer"`),任何内置组件 import 都会使 `pnpm docs:build` 失败。
- 处理:两篇内置组件正文保留真实代码块;`builtin-text-demo.tsx` / `builtin-list-demo.tsx` 用等价渲染元素演示交互,并在正文「运行效果」写明「文档站缺少完整客户端环境,示例用等价元素演示」。
- 未改 `packages/` / `packages-user/` / `src/`,未绕过断言。
live 人工验证(10-46):待最终人工审阅。本轮未写「用户人工验证:通过」,也未把 live 关卡标记为完成。
## 10-47 命名确认
用户确认(10-47):可以执行
用户原文:可以执行(批准执行 10-43..10-47;10-48 的读者/用户审阅前停下)
- 六篇文件名与侧边栏显示名(沿用命名总表):`inventory-example-1-skeleton.md`「示例(一)目标与骨架」、`inventory-example-2-grid.md`「示例(二)道具网格」、`inventory-example-3-detail.md`「示例(三)详情区」、`inventory-example-4-scroll.md`「示例(四)滚动与列表」、`inventory-example-5-state.md`「示例(五)交互与状态」、`inventory-example-6-animation-and-register.md`「示例(六)动画、拆分与注册」。
- 6 个 demo:`inventory-1-skeleton.tsx`(`Inventory1Skeleton`)、`inventory-2-grid.tsx`(`Inventory2Grid`)、`inventory-3-detail.tsx`(`Inventory3Detail`)、`inventory-4-scroll.tsx`(`Inventory4Scroll`)、`inventory-5-state.tsx`(`Inventory5State`)、`inventory-6-full.tsx`(`Inventory6Full`)。
- 组件拆分(第 22 篇定下,第 27 篇只回顾不改变):`InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar`。
- 面板尺寸:720×480 根容器;假数据 10 个道具,只用 `g-rect` / `g-rectr` / `text` 绘制图标与名称,不引入真实素材。
- 第 25 篇取舍:`Scroll` 平铺为主,末尾用 `ListPage` 做「左列表右详情」对比,并给 `Scroll` / `ListPage` / `Page` 判定表。
- 第 27 篇注册:`export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)`,打开处替换;不写全局注册表。
- 落点:正文 `docs/advanced/ii/ui/` 六篇;demo 在 `docs/.vitepress/components/demos/ui/`;侧边栏「完整示例」分组 6 条。
- 修改方式:正文 / demo / 文档由 GSD 执行器执行,未内联改动源码;未调用 `opencode` 命令;不 commit。
- 基线:HEAD `b94b4c3b41da8184312bc9f264654dc9a54adf69`;参考哈希复核见下节。
### 10-47 参考哈希复核(2026-10-31)
`git hash-object -- <path>` 实测结果:
| 路径 | 实测 | 与 Manifest | `git status` |
|------|------|-------------|--------------|
| `packages/render/src/core/item.ts` | `1acd9193d1b0e3121af1dd74ccef25f3dcc7124f` | 一致 | 干净 |
| `packages/render/src/core/container.ts` | `e01b5122fc2d3685648c28db6932919c554c98d6` | 一致 | 干净 |
| `packages/render-vue/src/props.ts` | `27e0f9f3bb2fa63bf2d9d358af87078eebe56053` | 一致 | 干净 |
| `packages/system/src/ui/controller.ts` | `25c3ea6f2bb3877989c65f25d3fc6dc3288ead7a` | 一致 | 干净 |
| `packages/system/src/ui/ui.ts` | `04b98c0ce7ce04c24c97906f5dd7261b1f53907a` | 一致 | 干净 |
| `packages-user/client-base/src/components/list.tsx` | `a6723454788b8fff22389bc5d19883c90a4eb5b5` | 一致 | 干净 |
| `packages-user/client-base/src/components/scroll.tsx` | `809af86b816bdad643292afce85e106886dd5a99` | 一致 | 干净 |
| `packages-user/client-base/src/components/textbox.tsx` | `5b58de65007189314553be0aca48209bd9e25981` | 一致 | 干净 |
| `packages-user/client-base/src/use/hotkey.ts` | `75e7f716a7655301d969285e22388414db1eb3c3` | 一致 | 干净 |
| `packages-user/client-modules/src/render/use.ts` | `81d764410093a9baa5ad073dc6002ff2942d2d5f` | 未列入基线 | 干净 |
结论:本计划涉及的全部参考文件与 Manifest / NOTES 基线一致,工作树对本批参考路径无改动,可按现有内容写作。
### 10-47 门禁
| 门禁 | 命令 | 结论 |
|------|------|------|
| prettier `--write` | `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"` | exit 0 |
| prettier `--check` | 同上路径 `--check` | `All matched files use Prettier code style!` |
| ESLint | `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"` | exit 0,0 error / 0 warning |
| docs 类型 | `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` | `docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条,既有、非本轮引入、不得修) |
| 静态断言 | 6 篇正文 + 6 个 demo + 侧边栏 27 条 + 兄弟分组 + 第 22/27 篇组件名 | `STATIC-OK` |
| 全量构建 | `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` | green,`build complete in 24.63s.`,无 dead link |
`docs/` 路径类型报错 0;既有引擎报错 11 条(与本轮无关,保持不动)。
静态断言明细:6 篇均为单 H1、含 `## 边界与注意`、无被禁写法、`<ClientOnly>` + 动态 loader、CRLF;6 个 demo 默认导出、无 DOM 属性、只 import vue(无其它引擎 / 用户包 import);侧边栏 27 条链接共 27 次出现、27 个唯一值、无重复,`custom-range` 与高级 III 分组未丢;第 22 与第 27 篇的五个组件名一致。
#### 本批清单(6 篇 + 6 个 demo)
| 页面 | live | demo |
|------|------|------|
| `docs/advanced/ii/ui/inventory-example-1-skeleton.md` | 是 | `docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx` |
| `docs/advanced/ii/ui/inventory-example-2-grid.md` | 是 | `docs/.vitepress/components/demos/ui/inventory-2-grid.tsx` |
| `docs/advanced/ii/ui/inventory-example-3-detail.md` | 是 | `docs/.vitepress/components/demos/ui/inventory-3-detail.tsx` |
| `docs/advanced/ii/ui/inventory-example-4-scroll.md` | 是 | `docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx` |
| `docs/advanced/ii/ui/inventory-example-5-state.md` | 是 | `docs/.vitepress/components/demos/ui/inventory-5-state.tsx` |
| `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` | 是(完整面板) | `docs/.vitepress/components/demos/ui/inventory-6-full.tsx` |
### 全批交叉核对
① 27 篇是否都在侧边栏出现且无重复:是。`config.ts` 中 `/advanced/ii/ui/` 链接共 27 次出现、27 个唯一值,无重复。
② 六个 Part 分组的顺序:是。依次为起步、元素与布局、交互与数据、组件化、内置组件与 UI 系统、完整示例,与 10-43 命名总表一致。
③ `hidden` 口径:一致。第 8 / 12 / 21 / 24 篇均为「不显示、不交互」+「保留元素与状态」+「跳过绘制与命中」。
④ `v-model:xxx` 口径:一致。第 13 篇规定 `update:xxx` 只随 `v-model:xxx` 出现;第 17 篇 `v-model:value`、第 18 篇 `v-model:selected` 均按此写。
⑤ 第 22 与第 27 篇的组件拆分:一致。均为 `InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar`。
⑥ 被禁写法:本批 6 篇静态断言未命中 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性、`GameUI.get`。
live 人工验证(10-47):待最终人工审阅。本轮未写「用户人工验证:通过」,也未把 live 关卡标记为完成。
## 10-48 / 10-49 拆分说明(2026-10-31)
原 `10-48-PLAN.md` 合并了「独立读者审阅 + 用户主导修订 + 最终门禁 + 落位评估 + 收尾」六件事。按用户要求拆成两个可独立执行的计划:
- `10-48-PLAN.md`:只做独立读者审阅(D-46 第 1 阶段 / D-89),只产出 `10-48-READER-REVIEW.md`;不改正文、不做 live 目视验证、不写 SUMMARY / ROADMAP / STATE、不 commit。审阅前后记录 docs 哈希快照,证明审阅期间正文零改动。
- `10-49-PLAN.md`:用户逐条裁决 10-48 的问题并修订,随后跑最终门禁、全站 live 复验、落位评估与收尾(`10-49-USER-REVIEW.md` / `10-49-SUMMARY.md` / ROADMAP / STATE)。
本批范围仍为 27 篇正文 + 25 个 demo;10-43..10-47 已执行完成,10-48 / 10-49 未执行。此前记录的「live 人工验证(10-4X):待最终人工审阅」统一由 10-49 Task 4 的全站 live 复验覆盖,不再为前五批单独补标记。
## 计划顺延说明(2026-10-31,pre-review 修复)
用户要求在独立审阅前先完成三项修复,计划编号顺延如下;本节只记录新编号,不改写上面的历史记录与用户原话:
- `10-48-PLAN.md`:**pre-review 修复**(新增)。删去 `ui-template-ts.md`、`component-ts.md` 与 `ts-component-demo.tsx`,内联简短 TS 元素层演示,去掉全局 `client`,给 25 篇正文与 24 个 demo 补注释;不改 ROADMAP / STATE、不写 SUMMARY、不 commit。
- `10-49-PLAN.md`:**独立读者审阅**(原 10-48)。只读修复后的 25 篇 Markdown,只提问、只记录使用概率,不改正文;产出 `10-49-READER-REVIEW.md`。
- `10-50-PLAN.md`:**用户修订 + 最终门禁 + 落位评估 + 收尾**(原 10-49)。产出 `10-50-USER-REVIEW.md` / `10-50-SUMMARY.md`,并在最终门禁中使用 25 篇 / 24 个 demo / 25 个 HTML。
修复后的计数为 **25 篇正文 + 24 个 demo**;上面的 27 篇 / 25 个 demo 记录是修复前的历史状态。历史文本中的 10-48 / 10-49 指当时的审阅 / 修订计划;自本节起,10-48 为 pre-review 修复、10-49 为独立读者审阅、10-50 为用户修订与收尾,以本节为准。
## 10-48 pre-review 修复
用户确认(10-48):可以执行
用户原文(2026-10-31):「可以执行」,批准三项修复:删除独立 TS 页并内联 TS 片段、`client` 改为 `props.state`、补注释。
修复范围:①删去 2 篇独立 TS 页与 1 个 TS demo 并内联 TS 片段;②去掉全局 client、改用 props.state;③给 25 篇正文代码块与 24 个 demo 补注释。
删除清单:docs/advanced/ii/ui/ui-template-ts.md、docs/advanced/ii/ui/component-ts.md、docs/.vitepress/components/demos/ui/ts-component-demo.tsx
基线 HEAD(10-48 记录):b94b4c3b41da8184312bc9f264654dc9a54adf69
修复前 docs 快照哈希:31439e8621b5723687d08550618f56db530c2d794531d599190820aaafcfdd59
修复前 demo 快照哈希:86611ab1ff9bd572ef7be06dc0fa1b6bc5e2f99d50b261846a5f0fccedd5b6de
ROADMAP 受保护行哈希:a9b74dcdc8be21ab1aa98a7b63fc81527c69a376ddb6e20509eeb7a792d70532
ROADMAP 全文哈希:fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a
STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591
删除完成:3 个文件
页面计数(删除后):25
demo 计数(删除后):24
Part 0-1 注释前代码哈希:9d9594b907a9a54d504a88a6136a17481394c11223838d872672c7f56dfb5a2e
Part 0-1 注释后代码哈希:9d9594b907a9a54d504a88a6136a17481394c11223838d872672c7f56dfb5a2e
Part 2-5 注释前代码哈希:dca838e1e7d86fa67dc9b1a47e57a36b6e2e43b6d87576b4fe8e29d877f5a750
Part 2-5 注释后代码哈希:dca838e1e7d86fa67dc9b1a47e57a36b6e2e43b6d87576b4fe8e29d877f5a750
修复后 docs 快照哈希:d0acf96d440f9796135455e49d4da78ba290c5bc8772f7a92d45e24e2cd13738
修复后 demo 快照哈希:faff7a51416094cf058ec666d8f12246833ca102936fd832012b395bf47bfd36
页面计数:25
demo 计数:24
构建产物:25
10-48 门禁:prettier 通过;ESLint 0/0;docs 类型 0 报错;构建 green;0 dead link;25 HTML;静态断言通过。
停止点:10-48 修复结束,未进入 10-49 独立审阅;未改 ROADMAP / STATE;未写 SUMMARY;未 commit。
## 10-48 执行偏差(2026-10-31)
- 计划内 verify 脚本 bug:T1 oreach( in @(...)) 少一个右括号,运行前补 ),断言语义不变。
- 计划内 verify 脚本 bug:T3/T4/T5 的
ode -e $js 在 PowerShell 5.1 下引号丢失,改为 $js | node -;T5 因脚本含中文改用临时 UTF-8 文件执行。
- 计划内 verify 脚本 bug:T5 聚合函数 const agg=fs=>... 参数遮蔽 s 模块,参数改名为 list。
- 计划内 verify 脚本 bug:T5 构建调用在 ErrorActionPreference=Stop 下被原生 stderr 中止,仅在构建调用前后临时设为 Continue。
- 执行中误删 events.md 一个代码围栏,已恢复;恢复后 Part 2-5 去注释聚合哈希与基线完全一致,证明非注释代码未变。
- 元素层实际 API 没有 loc() 方法(loc 只是 TSX 属性,对应 pos() + size());六处内联 s 片段统一用 pos() / size(),与 packages/render 一致。
## 10-49 独立读者审阅
用户原话(10-49,2026-11-01):「到第二天了,继续」
用户要求(10-49,2026-11-01):独立人格审阅由 orchestrator 分别派发多个子代理编排,不允许一个子代理包办。
本次执行范围(10-49):只做 Task 0 记录与 Task 1 审阅前基线;不派发读者、不执行 Task 2 / Task 3。
审阅范围:docs/advanced/ii/ui/ 下 25 篇 Markdown(Part 0→5)+ docs/advanced/ii/index.md + docs/advanced/index.md 两份导览;只读 Markdown,不读源码;不做 live 目视验证。
读者人格(逐字):你是一位刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。你完全没写过 UI,不知道 canvas 是什么,也不会 Vue 的组件写法;你只掌握了基础 TS/JS、函数、对象、数组和一点点模板语法。你手里只有这套文档,不能看源码,也没有人可以问。你的任务不是评价文档好坏,而是老老实实按顺序读,读到哪里卡住就记下:我在哪一段卡住、我从文档里已经知道什么、我还缺什么才能继续往下做。
ROADMAP 基线 Plans 行:**Plans:** 29/32 completed(第一批:中级教程 24 篇 + 站点注册 + D-09 复审修订;第二批:高级 I 7 篇 + 注册 + 读者审阅 + 用户修订循环;第三批:高级 II 10 篇 + 注册 + 读者审阅 + 用户修订循环;第四批:高级 I 补写 Mover + FaceHandler 2 篇 + 注册 + 读者/用户修订,已完成)。**未完成 3 个**(第一批遗留):`10-06`(中级全批验收)、`10-11`(中级读者审阅)、`10-12`(中级最终验收)——其范围已被后续 D-09 修订与高级 I/II 期间的最终状态覆盖,缺独立 SUMMARY,待补跑或并入后续验收。
STATE 基线 total_plans:134
STATE 基线 completed_plans:126
基线 HEAD(10-49 记录):b94b4c3b41da8184312bc9f264654dc9a54adf69
审阅前 docs 快照哈希:d0acf96d440f9796135455e49d4da78ba290c5bc8772f7a92d45e24e2cd13738
审阅前 docs 快照文件数:27(25 篇 UI 正文 + docs/advanced/ii/index.md + docs/advanced/index.md)
ROADMAP 受保护行哈希:a9b74dcdc8be21ab1aa98a7b63fc81527c69a376ddb6e20509eeb7a792d70532
ROADMAP 全文哈希:fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a
STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591
审阅停止条件:审阅结束即停止,不进入用户修订;不写 SUMMARY / ROADMAP / STATE;不改导览与侧边栏;不 commit。
读者派发方式:orchestrator 子代理
审阅后 docs 快照哈希:d0acf96d440f9796135455e49d4da78ba290c5bc8772f7a92d45e24e2cd13738
读者审阅:已完成(见 10-49-READER-REVIEW.md)
停止点:审阅结束,未进入用户修订;未写 SUMMARY / ROADMAP / STATE;未改 docs/;未 commit。
## 计划重排(2026-11-01)
用户要求把 10-49 之后的计划重排为「深度扩写 → 独立读者循环 → 用户审阅」,本节只记录编号映射与文件处置,不改写上面的历史记录:
- 旧 `10-49-PLAN.md`(独立读者审阅)→ 读者循环现为 `10-53-PLAN.md`(执行 Round 2/3;Round 1 记录保留在 `10-49-READER-REVIEW.md`,不删除、不复制、不交给用户)。
- 旧 `10-50-PLAN.md`(用户修订 + 最终门禁 + 落位 + 收尾)→ 现为 `10-54-PLAN.md`。
- 新增 `10-49-PLAN.md`:Part 0–1 深度扩写(7 篇)。
- 新增 `10-50-PLAN.md`:Part 2–3 深度扩写(7 篇)。
- 新增 `10-51-PLAN.md`:Part 4 深度扩写(5 篇)。
- 新增 `10-52-PLAN.md`:Part 5 深度扩写(6 篇)。
- `10-48` 仍是 pre-review 修复,编号不变。
- 四份扩写计划串行(wave 7→10),共享本文件与 `pnpm docs:build` 产物目录;读者循环 wave 11,用户审阅 wave 12。
- 旧 `10-49-PLAN.md` / `10-50-PLAN.md` 的正文已被新计划替换;本文件中 2026-11-01 之前的 10-49 / 10-50 记录是历史状态,按本节映射理解。
- 交叉引用:`10-43-PLAN.md`、`10-47-PLAN.md`、`10-48-PLAN.md` 末尾各追加了「编号变更(2026-11-01)」小节;`10-CUSTOM-UI-RESEARCH.md` 末尾追加了同一映射。历史正文不改写。
- 本次重排只写计划与规划记录;不改 `docs/`、代码、`ROADMAP.md`、`STATE.md`;不 commit。
## 10-49 深度扩写(Part 0–1)
用户确认(10-49):可以执行
用户原话(2026-11-01):「批准执行所有计划,在独立读者审阅循环前停下,注意 22:00 后停止」
本次执行范围(10-49):只做 Part 0–1 的 7 篇深度扩写与门禁;不进入 10-50..10-54,不进入 10-53 读者循环。
Task 0 记录:用户已随全局批准确认本计划六项(7 篇范围、D-93 四类逐页判定、体量仅记录不设门禁、Round 1 仅内部输入、扩写结束即停且不写 SUMMARY / ROADMAP / STATE / 不 commit、派发子代理执行);执行器不再重复提问。
扩写范围:`docs/advanced/ii/ui/ui-template.md`、`docs/advanced/ii/ui/container-and-coordinates.md`、`docs/advanced/ii/ui/basic-shapes.md`、`docs/advanced/ii/ui/curves-and-paths.md`、`docs/advanced/ii/ui/text.md`、`docs/advanced/ii/ui/image-and-texture.md`、`docs/advanced/ii/ui/layer-transform-performance.md`(Part 0–1)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 18 篇与两份导览。
Round 1 内部输入:`10-49-READER-REVIEW.md`(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单。
基线 HEAD(10-49 深度扩写):b94b4c3b41da8184312bc9f264654dc9a54adf69
扩写前本批页面聚合哈希:d140f3cd846c5cb616ae703380869fe54cd501f7c9e70a58b7e14dcc984c9eeb
本批外文件聚合哈希:63ec28b4cda6019ee9118473508c692405616c9a70c41704b438a88b88a77d21
ROADMAP 全文哈希:fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a
STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591
### D-93 覆盖表
| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |
| --- | --- | --- | --- | --- | --- |
| docs/advanced/ii/ui/ui-template.md | 已讲 | 已讲 | 已讲 | 已讲 | 123 |
| docs/advanced/ii/ui/container-and-coordinates.md | 已讲 | 已讲 | 已讲 | 已讲 | 114 |
| docs/advanced/ii/ui/basic-shapes.md | 已讲 | 已讲 | 已讲 | 已讲 | 159 |
| docs/advanced/ii/ui/curves-and-paths.md | 已讲 | 已讲 | 已讲 | 已讲 | 143 |
| docs/advanced/ii/ui/text.md | 已讲 | 已讲 | 已讲 | 已讲 | 118 |
| docs/advanced/ii/ui/image-and-texture.md | 已讲 | 已讲 | 已讲 | 已讲 | 96 |
| docs/advanced/ii/ui/layer-transform-performance.md | 已讲 | 已讲 | 已讲 | 已讲 | 160 |
体量参考(非门禁):7 篇当前总行数 913,平均 130.4 行。~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)。
停止点:10-49 只做 Part 0–1 深度扩写;不改 10-50..10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。
自查:docs/advanced/ii/ui/ui-template.md — 渲染树:新增「这份模板在渲染树里的位置」,讲清组件→VNode→元素树、创建/挂载/销毁、控制器栈与画布根、裸文字为什么不可用;事件:新增「事件从哪里进入」,讲清命中起点、zIndex 顺序、捕获/冒泡入口并回链事件篇;组件/元素:新增「组件、元素与打开方式」,讲清三个基础 props、open 第二参数、instance 与 close、GameUI 对象、文件放置与出口;示例解释:两段等价代码后都解释了它在树中的位置与保留/销毁关系,并新增「两条写法怎么选」比较混用边界。
已完成扩写:docs/advanced/ii/ui/ui-template.md
门禁(10-49 Task 2):prettier --check 通过;docs:build green(build complete in 19.29s),0 dead link;页面 25 篇、demo 24 个不变。
自查:docs/advanced/ii/ui/container-and-coordinates.md — 渲染树:新增「渲染树:根、容器与子元素」,讲清根→UI 容器→区域→叶子的树、父子建立方式、容器三项职责与 zIndex 同父比较;事件:新增「事件在嵌套容器中的路径」,讲清命中→捕获→冒泡、容器捕获单位、stopPropagation / noevent / hidden 与 enter/leave 的边界;组件/元素:扩展 loc/anchors 与嵌套示例,补 appendChild/removeChild/destroy 的生命周期与缓存写法;示例解释:新增父级 scale 示例与居中计算,并解释变换复合、容器不裁剪但命中受限、缓存何时该关。
自查:docs/advanced/ii/ui/basic-shapes.md — 渲染树:新增「图形在渲染树里的位置」,讲清叶子元素、绘制/命中顺序、按几何而非包围盒命中;事件:新增 actionStroke 命中宽度、填充/描边组合的命中判定与按钮命中注意;组件/元素:新增「图形作为界面零件」与「为什么矩形没有圆角」,补元素层类从 `@motajs/render` 导入;示例解释:填充/描边代码后给组合表并解释绘制顺序与命中差异。
自查:docs/advanced/ii/ui/curves-and-paths.md — 渲染树:新增「路径与曲线的坐标基准」与「路径在渲染树与命中中的位置」,讲清点坐标/Path2D 局部坐标、叶子位置与命中几何;事件:补 actionStroke 只命中描边及其宽度;组件/元素:扩写圆角矩形四张映射表与左上/右下示例,补「什么时候用路径」的取舍;示例解释:曲线、路径、圆角代码后均解释坐标基准、包围盒与命中边界。
已完成扩写:docs/advanced/ii/ui/container-and-coordinates.md
已完成扩写:docs/advanced/ii/ui/basic-shapes.md
已完成扩写:docs/advanced/ii/ui/curves-and-paths.md
门禁(10-49 Task 3):prettier --write 通过;docs:build green(build complete in 18.05s),0 dead link;页面 25 篇、demo 24 个不变。
自查:docs/advanced/ii/ui/text.md — 渲染树:新增「文字元素与渲染树」,讲清叶子元素、测量尺寸与命中矩形、裸文字不可用;事件:补按钮文字与底板的命中关系(文字加 noevent 让点击落到按钮底);组件/元素:扩写 Font 构造/默认值/setDefaults、尺寸测量与锚点重复写法、四类界面零件与默认不缓存;示例解释:右对齐与按钮文字示例后说明锚点、命中与缓存代价。
自查:docs/advanced/ii/ui/image-and-texture.md — 渲染树:新增「图片元素与纹理」,讲清叶子元素、纹理拉伸、按矩形命中与透明像素;事件:补背景/图标 noevent 与按钮图标命中;组件/元素:新增 PNG 异步加载完整路径、素材管理器取纹理、像素图与 hd/noanti 的真实作用、四类界面零件;示例解释:棋盘纹理、加载组件与像素设置后均解释尺寸、异步与缓存关系。
自查:docs/advanced/ii/ui/layer-transform-performance.md — 渲染树:新增「渲染树、层级与绘制顺序」,讲清兄弟排序、绘制/命中方向、父级子树与 UI 栈两层关系;事件:新增「事件坐标与变换」,讲清 offset 局部坐标、absolute 画布坐标、缩放后命中反算;组件/元素:扩写变换继承、hidden 与无布局流、缓存与脏更新、错误示范与 noevent 子树;示例解释:缩放探针组件逐段解释局部坐标与命中。
已完成扩写:docs/advanced/ii/ui/text.md
已完成扩写:docs/advanced/ii/ui/image-and-texture.md
已完成扩写:docs/advanced/ii/ui/layer-transform-performance.md
门禁(10-49 Task 4):prettier --write 通过;docs:build green(build complete in 18.02s),0 dead link;页面 25 篇、demo 24 个不变。
扩写后本批页面聚合哈希:ea27f311d3782e84c5d564590244d5e4284716196cad675cf985bb295579174b
体量参考(扩写后):`ui-template.md` 229 行;`container-and-coordinates.md` 222 行;`basic-shapes.md` 222 行;`curves-and-paths.md` 233 行;`text.md` 192 行;`image-and-texture.md` 179 行;`layer-transform-performance.md` 247 行。7 篇总行数 1524,平均 217.7 行。仍不设 300 行门禁:低于 300 行不失败,高于 300 行也不失败;不注水、不堆接口表(D-88)。
### 10-49 门禁
- 结构:`docs/advanced/ii/ui` 25 篇 `.md`;`docs/.vitepress/components/demos/ui` 24 个 `.tsx`;7 篇正文均 CRLF、0 个 LF;覆盖表无 `待补`;每篇均有 `自查:` 与 `已完成扩写:`;7 篇均无以「模板 / 需改」命名的小节,也无「简化版 / v1 / 以后再做」表述。
- 聚合哈希:`本批外文件聚合哈希` 仍为 `63ec28b4cda6019ee9118473508c692405616c9a70c41704b438a88b88a77d21`,与基线一致;`ROADMAP 全文哈希` 仍为 `fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a`,与基线一致;`STATE 全文哈希` 仍为 `e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591`,与基线一致;`扩写后本批页面聚合哈希` 与扩写前不同。
- prettier:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后 `--check` 同路径,exit 0,`All matched files use Prettier code style!`。
- ESLint:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,exit 0,0 error / 0 warning。
- docs 类型:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,`docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条,既有、非本轮引入、不得修)。
- 构建:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,exit 0,`build complete in 17.09s.`,0 dead link;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个;页面 25 篇、demo 24 个不变。
D-93 抽查:docs/advanced/ii/ui/ui-template.md — 通过
D-93 抽查:docs/advanced/ii/ui/container-and-coordinates.md — 通过
D-93 抽查:docs/advanced/ii/ui/basic-shapes.md — 通过
D-93 抽查:docs/advanced/ii/ui/curves-and-paths.md — 通过
D-93 抽查:docs/advanced/ii/ui/text.md — 通过
D-93 抽查:docs/advanced/ii/ui/image-and-texture.md — 通过
D-93 抽查:docs/advanced/ii/ui/layer-transform-performance.md — 通过
停止点:10-49 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-50..10-54;未 commit。
## 10-50 深度扩写(Part 2–3)
用户确认(10-50):可以执行
用户原话(执行上下文转述,2026-11-01):「用户已批准执行所有计划,在独立读者审阅循环前停下;22:00 后停止。」
本次执行范围(10-50):只执行 Part 2–3 的 7 篇深度扩写与门禁;不进入 10-51..10-54,不进入 10-53 读者循环。
Task 0 记录:六项已随全局批准确定(7 篇范围、事件顺序以源码核对并改正、D-93 四类逐页判定、体量仅记录不设门禁、扩写结束即停且不写 SUMMARY / ROADMAP / STATE / 不 commit、修改方式)。执行器不再重复提问。
修改方式:由 GSD 执行器执行;本次执行环境未提供再派生子代理的工具,正文由执行器直接落盘;未调用 `opencode` 命令;不 commit。
扩写范围:`docs/advanced/ii/ui/reactivity.md`、`docs/advanced/ii/ui/events.md`、`docs/advanced/ii/ui/hotkey-in-ui.md`、`docs/advanced/ii/ui/conditional-and-list-rendering.md`、`docs/advanced/ii/ui/props.md`、`docs/advanced/ii/ui/component-tsx.md`、`docs/advanced/ii/ui/slots-and-attrs.md`(Part 2–3)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 18 篇与两份导览。
Round 1 内部输入:`10-49-READER-REVIEW.md`(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单。
基线 HEAD(10-50 深度扩写):b94b4c3b41da8184312bc9f264654dc9a54adf69
扩写前本批页面聚合哈希:6c5b764ded45d1208cef8d4c4686131607b6ceb954b62a8ce4f108591ab8b83c
本批外文件聚合哈希:b3d4305a029cfc0187eb5ec033563b83a46bf0a332b9bf45ea75d02fbeb4774d
ROADMAP 全文哈希:fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a
STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591
### D-93 覆盖表
| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |
| --- | --- | --- | --- | --- | --- |
| docs/advanced/ii/ui/reactivity.md | 已讲 | 已讲 | 已讲 | 已讲 | 165 |
| docs/advanced/ii/ui/events.md | 已讲 | 已讲 | 已讲 | 已讲 | 179 |
| docs/advanced/ii/ui/hotkey-in-ui.md | 已讲 | 已讲 | 已讲 | 已讲 | 123 |
| docs/advanced/ii/ui/conditional-and-list-rendering.md | 已讲 | 已讲 | 已讲 | 已讲 | 130 |
| docs/advanced/ii/ui/props.md | 已讲 | 已讲 | 已讲 | 已讲 | 237 |
| docs/advanced/ii/ui/component-tsx.md | 已讲 | 已讲 | 已讲 | 已讲 | 256 |
| docs/advanced/ii/ui/slots-and-attrs.md | 已讲 | 已讲 | 已讲 | 已讲 | 195 |
体量参考(非门禁):7 篇当前总行数 1285,平均 183.6 行。~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)。
停止点:10-50 只做 Part 2–3 深度扩写;不改 10-51..10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。
自查:docs/advanced/ii/ui/reactivity.md — 渲染树:新增「数据变化如何走到渲染树」,讲清数据→组件→VNode→属性 patch→绘制,并说明重渲染是组件级、patch 是元素级;事件:在生命周期边界与两种 `ref` 对照中讲清重渲染不影响元素、事件回调改 `ref` 才驱动画面;组件/元素:新增重渲染条件、批处理与 `nextTick`、`computed` 缓存、`hidden` / 三元 / `key` 的差异与四类界面状态归属;示例解释:每段代码后说明它在链上的位置与状态保留关系。
已完成扩写:docs/advanced/ii/ui/reactivity.md
自查:docs/advanced/ii/ui/events.md — 渲染树:命中测试按根→zIndex→同层顺序→几何说明,并把命中链与渲染树对应;事件:改正为「父容器先捕获、命中元素随后捕获并先冒泡、父容器最后冒泡」,补 `stopPropagation` 同元素语义、enter/leave 的 hover 集合、同一元素事件对象复用与跨层各自计算;组件/元素:补 `MouseType` / `buttons` 位运算、`identifier`、坐标与变换、`noevent` 子树、`actionStroke` 宽度、嵌套传播完整例子;示例解释:每段代码后说明命中了谁、经过了哪条链、日志为什么是这个顺序。
已完成扩写:docs/advanced/ii/ui/events.md
门禁(10-50 Task 2):prettier --write / --check 通过;docs:build green,0 dead link;页面 25 篇、demo 24 个不变。
自查:docs/advanced/ii/ui/hotkey-in-ui.md — 渲染树:把按键作用域解释为一条全局栈,并说明它不随 `hidden` 离开、只在卸载时移除;事件:新增「按键与元素事件是两条路径」,讲清按键不经命中、元素事件不自动转成按键、两者无统一先后;组件/元素:扩写指令/作用域/实现、`useKey` 的 `clearImpl`、`implement` 覆盖与未注册行为、注册与分组、注销、三种触发方式与时间参数、优先级只比较同次匹配的指令、UI 栈归属与 Esc/Enter/方向键场景;示例解释:每段代码后说明它在作用域栈与事件模型中的位置。
已完成扩写:docs/advanced/ii/ui/hotkey-in-ui.md
自查:docs/advanced/ii/ui/conditional-and-list-rendering.md — 渲染树:新增「条件渲染改的是树,不是样式」,把 `hidden`、三元卸载与坐标不参与布局流放在同一棵树上比较;事件:列表项事件用闭包拿当前项,删除时处理选中态与监听随元素销毁;组件/元素:扩写 `key` 的匹配规则与作用域、`ref` / `shallowRef` / `reactive` 数组的修改差异、`computed` 派生列表、排查「改了没动」的五步、条件/列表完整树形示例;示例解释:代码后逐段说明哪一层增删、哪些状态保留、哪些重建。
已完成扩写:docs/advanced/ii/ui/conditional-and-list-rendering.md
门禁(10-50 Task 3):prettier --write / --check 通过;docs:build green,0 dead link;页面 25 篇、demo 24 个不变。
自查:docs/advanced/ii/ui/props.md — 渲染树:新增「props 与渲染树」,讲清 prop 变化只 patch 属性、结构变化由子组件决定、`key` 变化才重建;事件:补 `v-model:xxx` 的等价属性与 `emit` / 回调的取舍;组件/元素:新增四环 props 管线与逐环排查、泛型顺序、camelCase 与 `v-model:` 例外、`??` 默认值、`computed` 与读一次的差异、UI 的 controller/instance/state 注入、props/attrs/slot 职责表;示例解释:每段代码后说明值落在哪一环、哪个写法会跟随更新。
已完成扩写:docs/advanced/ii/ui/props.md
自查:docs/advanced/ii/ui/component-tsx.md — 渲染树:新增「组件如何映射成一棵子树」,讲清组件不产生额外节点、根元素是挂载点、多根节点成为同级子元素;事件:补 `emit` 与父组件回调的取舍、父组件 `onXxx` 在组件边界上的归属;组件/元素:扩写 `defineComponent` 四个泛型与第二参数省略后的后果、生命周期对应的树操作与自动/手动清理、`expose` 与父级 `ref`、组件拆分边界、普通子组件不传 controller;示例解释:每段代码后说明它在组件树与元素树中的位置。
已完成扩写:docs/advanced/ii/ui/component-tsx.md
自查:docs/advanced/ii/ui/slots-and-attrs.md — 渲染树:新增「slot 在渲染树里的位置」与完整落点示例,讲清 slot 在父作用域求值后插入子组件位置;事件:补组件边界上的 `onClick` 归属、声明 emits 后不再透传、转发写法与「点了没反应」排查;组件/元素:扩写四个泛型与手写 options 的关系、默认/具名/作用域 slot、`attrs` 响应式与 `inheritAttrs`、UI 的 `hidden` / `zIndex` 走 attrs、slot/props/attrs 选择表;示例解释:逐段说明每块内容最终落在哪棵子树、哪个元素。
已完成扩写:docs/advanced/ii/ui/slots-and-attrs.md
门禁(10-50 Task 4):prettier --write / --check 通过;docs:build green,0 dead link;页面 25 篇、demo 24 个不变。
扩写后本批页面聚合哈希:9f70e2e66a6b140580758cfc17c40157ca0c724c2c69f1369d5e6874af2635be
体量参考(扩写后):`reactivity.md` 363 行;`events.md` 441 行;`hotkey-in-ui.md` 251 行;`conditional-and-list-rendering.md` 346 行;`props.md` 350 行;`component-tsx.md` 425 行;`slots-and-attrs.md` 382 行。7 篇总行数 2558,平均 365.4 行。仍不设 300 行门禁:低于 300 行不失败,高于 300 行也不失败;不注水、不堆接口表(D-88)。
### 10-50 门禁
- 结构:`docs/advanced/ii/ui` 25 篇 `.md`;`docs/.vitepress/components/demos/ui` 24 个 `.tsx`;7 篇正文均 CRLF、0 个 LF;覆盖表无 `待补`;每篇均有 `自查:` 与 `已完成扩写:`;7 篇均无「简化版 / v1 / 以后再做」表述,也没有新增「模板 / 需改」小节。
- 聚合哈希:`本批外文件聚合哈希(复算)` 为 b3d4305a029cfc0187eb5ec033563b83a46bf0a332b9bf45ea75d02fbeb4774d,与基线一致;`ROADMAP 全文哈希(复算)` 为 fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a,与基线一致;`STATE 全文哈希(复算)` 为 e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591,与基线一致;`扩写后本批页面聚合哈希` 与扩写前不同,且与按同一算法重算的结果一致。
- prettier:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后 `--check` 同路径,exit 0,`All matched files use Prettier code style!`。
- ESLint:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,exit 0,0 error / 0 warning。
- docs 类型:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,exit 2;`docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条,既有、非本轮引入、不得修)。
- 构建:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,exit 0,`build complete in 22.80s.`,0 dead link;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个;页面 25 篇、demo 24 个不变。
D-93 抽查:docs/advanced/ii/ui/reactivity.md — 通过
D-93 抽查:docs/advanced/ii/ui/events.md — 通过
D-93 抽查:docs/advanced/ii/ui/hotkey-in-ui.md — 通过
D-93 抽查:docs/advanced/ii/ui/conditional-and-list-rendering.md — 通过
D-93 抽查:docs/advanced/ii/ui/props.md — 通过
D-93 抽查:docs/advanced/ii/ui/component-tsx.md — 通过
D-93 抽查:docs/advanced/ii/ui/slots-and-attrs.md — 通过
事件顺序复核:events.md 不含肯定式「子元素先捕获」;已按源码核对为「父容器先捕获、命中元素随后捕获并先冒泡、父容器最后冒泡」;`stopPropagation` 只停止传播、不阻止同一元素同一事件名的其它监听器;`noevent` 为整个子树不参与命中;enter/leave 由根的 hover 集合做差集统一触发、先 leave 后 enter,不走普通冒泡。
### 10-50 执行偏差
- 修改方式:本执行环境未提供再派生子代理的工具,7 篇正文与 NOTES 由执行器直接落盘;未调用 `opencode` 命令;不 commit。
- Task 2–5 的 verify 脚本在 PowerShell 5.1 与 `$ErrorActionPreference='Stop'` 下会把 `pnpm docs:build` 的正常 stderr 当成终止错误;执行时用同名 `cmd` 包装函数把原生命令的 stderr 降为 Continue,脚本其余断言原样执行,未修改计划、断言或构建命令。
- Task 2 首次 verify 未命中 `hover` 关键词,正文补写「hover 集合」后通过;未删改断言。
停止点:10-50 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-51..10-54;未 commit。
## 10-51 深度扩写(Part 4)
用户确认(10-51):可以执行
用户原话(执行上下文转述,2026-11-01):「用户已批准执行所有计划,在独立读者审阅循环前停下;22:00 后停止。」
本次执行范围(10-51):只执行 Part 4 的 5 篇深度扩写与门禁;不进入 10-52..10-54,不进入 10-53 读者循环。
Task 0 记录:六项已随全局批准确定(5 篇范围、每个内置组件讲「替你决定了什么 / 树落点 / 事件 / 组合与不适用」、D-93 四类逐页判定、体量仅记录不设门禁、扩写结束即停且不写 SUMMARY / ROADMAP / STATE / 不 commit、修改方式)。执行器不再重复提问。
修改方式:由 GSD 执行器执行;本次执行环境未提供再派生子代理的工具,正文由执行器直接落盘;未调用 `opencode` 命令;不 commit。
扩写范围:`docs/advanced/ii/ui/builtin-text-and-input.md`、`docs/advanced/ii/ui/builtin-list-and-containers.md`、`docs/advanced/ii/ui/ui-controller-and-stack.md`、`docs/advanced/ii/ui/replace-builtin-ui.md`、`docs/advanced/ii/ui/ui-performance.md`(Part 4)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 20 篇与两份导览。
Round 1 内部输入:`10-49-READER-REVIEW.md`(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单。
基线 HEAD(10-51 深度扩写):b94b4c3b41da8184312bc9f264654dc9a54adf69
扩写前本批页面聚合哈希:e3bb3fd495f571df9905d1a47f546a53c0f97ca52cc0174a7cb9821d9456c25f
本批外文件聚合哈希:7d0970aed1d0c3f5e3a116c310b21fb97b8ddcf6b0a131e03037ce33c5dd0137
ROADMAP 全文哈希:fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a
STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591
### D-93 覆盖表
| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |
| --- | --- | --- | --- | --- | --- |
| docs/advanced/ii/ui/builtin-text-and-input.md | 已讲 | 已讲 | 已讲 | 已讲 | 284 |
| docs/advanced/ii/ui/builtin-list-and-containers.md | 已讲 | 已讲 | 已讲 | 已讲 | 309 |
| docs/advanced/ii/ui/ui-controller-and-stack.md | 已讲 | 已讲 | 已讲 | 已讲 | 180 |
| docs/advanced/ii/ui/replace-builtin-ui.md | 已讲 | 已讲 | 已讲 | 已讲 | 110 |
| docs/advanced/ii/ui/ui-performance.md | 已讲 | 已讲 | 已讲 | 已讲 | 130 |
体量参考(非门禁):5 篇当前总行数 1013,平均 202.6 行。~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)。
停止点:10-51 只做 Part 4 深度扩写;不改 10-52..10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。
自查:docs/advanced/ii/ui/builtin-text-and-input.md — 渲染树:新增「这些组件替你决定了什么」与「事件与渲染树」,讲清 TextContent 的根是 custom、排版宽度只认 width、Textbox 根容器与标题/正文的落点、Input 根容器接点击而内部文字 noevent;事件:讲清 typeEnd / typeStart / updateHeight、Input 的 update:value / input / change 时序与失焦移除、TextboxStore 的 id 键;组件/元素:补多行说明、标题加正文、可滚动长说明、多个输入字段与不适用场景;示例解释:每段代码后说明它在树中的位置、状态归属与事件路径。
已完成扩写:docs/advanced/ii/ui/builtin-text-and-input.md
自查:docs/advanced/ii/ui/builtin-list-and-containers.md — 渲染树:新增「列表、滚动、分页、弹窗各自解决什么」与「组合示例与树形解释」,讲清 List 行结构、ListPage 三层、Page 内容区与页码条、Scroll 直接子元素与 container-custom;事件:讲清选中由点击驱动并发出 update / update:selected、ListPage 的 close 只发事件、Page 的 pageChange / update:page、滚动中的命中坐标偏移;组件/元素:补选中与 v-model、key、滚动裁剪与 scrollTo 像素、弹窗层级与返回值、Page 与 ListPage 的 slot 形式差异;示例解释:每段代码后说明哪一层增删、谁收到事件、状态归谁。
已完成扩写:docs/advanced/ii/ui/builtin-list-and-containers.md
门禁(10-51 Task 2):prettier --write / --check 通过;docs:build green(build complete in 22.79s),0 dead link;页面 25 篇、demo 24 个不变。
自查:docs/advanced/ii/ui/ui-controller-and-stack.md — 渲染树:新增「控制器、实例与栈」与「事件归属与生命周期」,讲清控制器/实例/容器四层、栈顺序映射成 zIndex 与隐藏、背景在 zIndex 0、关闭卸载与隐藏保留;事件:讲清命中按渲染树、上层不自动拦截、按键走挂载作用域、hide 不摘作用域;组件/元素:补实例字段、open 第三参数 alwaysShow、背景四个名字状态表、栈策略与自定义策略最小实现、两个控制器分工与决策表、props creator 必须带回 state、主界面容器随 active 显隐;示例解释:工具栏→设置→确认逐层说明栈位置、背景变化、事件归属与关闭级联。
已完成扩写:docs/advanced/ii/ui/ui-controller-and-stack.md
自查:docs/advanced/ii/ui/replace-builtin-ui.md — 渲染树:新增「替换的是入口,不是实现」与内置 UI 的 GameUI/入口/文件对照表,讲清打开处、包装层与显示策略三层改法;事件:讲清关闭只关实例、Esc 与按键作用域随卸载移除、包装要转发 emits;组件/元素:补可替换范围与必须保留的行为、五步替换流程与验证点、存档返回值语义、最小替换示例接在主 UI 栈;示例解释:说明替换后所在栈、背景、遮挡与关闭路径,并给出回退方式。
已完成扩写:docs/advanced/ii/ui/replace-builtin-ui.md
门禁(10-51 Task 3):prettier --write / --check 通过;docs:build green,0 dead link;页面 25 篇、demo 24 个不变。
自查:docs/advanced/ii/ui/ui-performance.md — 渲染树:新增「性能问题先定位在哪一层」与「缓存」两节,把绘制、命中、重渲染、列表、纹理、栈六层放在同一棵树上说明,讲清脏标记向上冒泡与隐藏子树中断;事件:新增「命中与事件」,说明每次鼠标移动的命中遍历、noevent 剪枝、actionStroke 热区与全屏遮罩的代价;组件/元素:补缓存默认值与取舍、hidden 与卸载、Scroll 平铺与分页、key、纹理与文字、creator 名字与 state;示例解释:错误缓存示范与两种修正后说明缓存在哪一层、为什么变慢或变快。
已完成扩写:docs/advanced/ii/ui/ui-performance.md
门禁(10-51 Task 4):prettier --write / --check 通过;docs:build green,0 dead link;页面 25 篇、demo 24 个不变。
扩写后本批页面聚合哈希:b7da49c6a497219cfe56f3a71221c882a9550643e559e19d32cbd19e90a89f3a
体量参考(扩写后):`builtin-text-and-input.md` 488 行;`builtin-list-and-containers.md` 461 行;`ui-controller-and-stack.md` 318 行;`replace-builtin-ui.md` 243 行;`ui-performance.md` 234 行。5 篇总行数 1744,平均 348.8 行。仍不设 300 行门禁:低于 300 行不失败,高于 300 行也不失败;不注水、不堆接口表(D-88)。
### 10-51 门禁
- 结构:`docs/advanced/ii/ui` 25 篇 `.md`;`docs/.vitepress/components/demos/ui` 24 个 `.tsx`;5 篇正文均 CRLF、0 个 LF;覆盖表无 `待补`;每篇均有 `自查:` 与 `已完成扩写:`;5 篇均无「简化版 / v1 / 以后再做」表述,也没有新增「模板 / 需改」小节。
- 聚合哈希:`本批外文件聚合哈希(复算)` 为 7d0970aed1d0c3f5e3a116c310b21fb97b8ddcf6b0a131e03037ce33c5dd0137,与基线一致;`ROADMAP 全文哈希(复算)` 为 fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a,与基线一致;`STATE 全文哈希(复算)` 为 e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591,与基线一致;`扩写后本批页面聚合哈希` 与扩写前不同,且与按同一算法重算的结果一致。
- prettier:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui/{5 篇}"` 后 `cmd /c "pnpm exec prettier --check docs/advanced/ii/ui"`,exit 0,`All matched files use Prettier code style!`。
- ESLint:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,exit 0,0 error / 0 warning。
- docs 类型:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,exit 2;`docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 3 条、`packages/render/src/core/types.ts` 8 条,既有、非本轮引入、不得修)。
- 构建:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,exit 0,`build complete in 23.04s.`,0 dead link;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个;页面 25 篇、demo 24 个不变。
D-93 抽查:docs/advanced/ii/ui/builtin-text-and-input.md — 通过
D-93 抽查:docs/advanced/ii/ui/builtin-list-and-containers.md — 通过
D-93 抽查:docs/advanced/ii/ui/ui-controller-and-stack.md — 通过
D-93 抽查:docs/advanced/ii/ui/replace-builtin-ui.md — 通过
D-93 抽查:docs/advanced/ii/ui/ui-performance.md — 通过
### 10-51 执行偏差
- 修改方式:本执行环境未提供再派生子代理的工具,5 篇正文与 NOTES 由执行器直接落盘;未调用 `opencode` 命令;不 commit。
- Task 2–5 的 verify 脚本在 PowerShell 5.1 与 `$ErrorActionPreference='Stop'` 下会把 `pnpm docs:build` 的正常 stderr 当成终止错误;执行时用同名包装把原生命令的 stderr 降为 Continue,脚本其余断言原样执行,未修改计划、断言或构建命令。
- Task 2 首次 verify 未命中列表篇的 `渲染树` 关键词,正文补写一句「同一棵渲染树」后通过;Task 3 首次 verify 因 NOTES 追加缺少换行而未命中 `自查:`,补上换行后通过;未删改断言。
- 与源码核对时的两处口径:`TextContent` 的排版宽度只看 `width`(`loc` 第三项被覆盖);一次性弹窗以 `alwaysShow` 打开,所以 `lastOnly` 不会把它隐藏。均按方法注释与行为写入正文,未报告为缺陷。
停止点:10-51 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-52..10-54;未 commit。
## 10-52 深度扩写(Part 5)
用户确认(10-52):可以执行
用户原话(执行上下文转述,2026-11-01):「用户已批准执行所有计划,在独立读者审阅循环前停下;22:00 后停止。Task 0 不再提问;把用户原话与 10-52 确认记录写入 NOTES。」
本次执行范围(10-52):只执行 Part 5 的 6 篇深度扩写与门禁;不进入 10-53 / 10-54,不进入 10-53 读者循环。
Task 0 记录:六项已随全局批准确定(6 篇范围、系列一致性契约九条、D-93 四类逐页判定、体量仅记录不设门禁、扩写结束即停且不写 SUMMARY / ROADMAP / STATE / 不 commit、修改方式)。执行器不再重复提问。
修改方式:由 GSD 执行器执行;本次执行环境未提供再派生子代理的工具,正文由执行器直接落盘;未调用 `opencode` 命令;不 commit。
扩写范围:`docs/advanced/ii/ui/inventory-example-1-skeleton.md`、`docs/advanced/ii/ui/inventory-example-2-grid.md`、`docs/advanced/ii/ui/inventory-example-3-detail.md`、`docs/advanced/ii/ui/inventory-example-4-scroll.md`、`docs/advanced/ii/ui/inventory-example-5-state.md`、`docs/advanced/ii/ui/inventory-example-6-animation-and-register.md`(Part 5)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 19 篇、两份导览与 24 个 demo。
Round 1 内部输入:`10-49-READER-REVIEW.md`(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单。
基线 HEAD(10-52 深度扩写):b94b4c3b41da8184312bc9f264654dc9a54adf69
扩写前本批页面聚合哈希:e9565ba82aa52a3f74deeda4585bd224fe51103df5968e5a458afd6d8bac1b06
本批外文件聚合哈希:56fedcb45d7849d73a742d8afb95097eadc5a95e40423359ce9bcf9c164f4958
ROADMAP 全文哈希:fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a
STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591
demo 快照哈希:02b1d6a88d414c9ce197b7bd8f7773020d8ae1c5c18099518595a66ca1ad6a4a
### D-93 覆盖表
| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |
| --- | --- | --- | --- | --- | --- |
| docs/advanced/ii/ui/inventory-example-1-skeleton.md | 已讲 | 已讲 | 已讲 | 已讲 | 144 |
| docs/advanced/ii/ui/inventory-example-2-grid.md | 已讲 | 已讲 | 已讲 | 已讲 | 234 |
| docs/advanced/ii/ui/inventory-example-3-detail.md | 已讲 | 已讲 | 已讲 | 已讲 | 113 |
| docs/advanced/ii/ui/inventory-example-4-scroll.md | 已讲 | 已讲 | 已讲 | 已讲 | 143 |
| docs/advanced/ii/ui/inventory-example-5-state.md | 已讲 | 已讲 | 已讲 | 已讲 | 233 |
| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | 已讲 | 已讲 | 已讲 | 已讲 | 138 |
系列一致性契约
契约 1:`items` 在 `InventoryPanel` 里是 `ref<Item[]>`;子组件收到的是父级解包后的数组或明确 props,不在子组件里直接引用父级闭包变量;派生列表用 `computed`。
契约 2:`Item` 类型只定义一次,定义在示例(二)的共享类型位置;后续页面引用它,不各自重写。
契约 3:`selectedId` 是 `ref<string | null>`,初始为 `null`(显示「请选择道具」);点击有效项写 id;详情区提供「取消选择」回到未选中。
契约 4:关闭归 `InventoryPanel`:面板的关闭按钮调用 `props.controller.close(props.instance)`;子组件不直接关闭面板,需要关闭时通过回调上报。
契约 5:左侧最终方案是 `Scroll`(示例四引入);示例二/三的普通网格是阶段性实现,示例四明确替换关系,示例五/六不再回到普通网格或 `ListPage`。
契约 6:布局坐标(layout)以最终组装页为准:左侧 `[54, 100, 400, 280]`、右侧 `[470, 100, 196, 280]`、底部 `ActionBar` `[54, 392, 304, 32]`;左侧网格/滚动区与底部 `ActionBar` 不重叠;各页坐标若调整,必须在当页说明与最终页的关系。
契约 7:组件拆分为 `InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar`;`InventoryPanel` 持有 `items`、`selectedId`、`equippedId`、`hint`,`ItemGrid` 收 `items` / `selectedId` / `equippedId` 与 `onSelect`,`ItemCell` 收 `item` / `selected` / `equipped` / `size`,`ItemDetail` 收 `item` 与 `onClear`,`ActionBar` 收 `canEquip` / `canUse` / `equipped` 与三个回调;后续页面不新增未声明的隐式依赖。
契约 8:列表 key 用 `item.id`;不用下标代替会变化的身份;无状态静态列表的例外要写明。
契约 9:事件流为 `ItemCell` 点击 → 上报 `onSelect(id)` → `ItemGrid` → `InventoryPanel` 更新 `selectedId`;操作按钮 → 上报动作 → 面板决定装备 / 使用 / 关闭。
体量参考(非门禁):6 篇当前总行数 1005,平均 167.5 行。~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)。
自查:docs/advanced/ii/ui/inventory-example-1-skeleton.md — 渲染树:新增「骨架在渲染树里的位置」,画出根容器→面板主体/标题/关闭按钮/左右区域的树,讲清三个区域坐标、720×480 是逻辑尺寸、同父 zIndex 与加入顺序、关闭按钮的命中与冒泡;事件:讲清点击命中按钮容器后调用 close、子元素无监听时沿父链上报;组件/元素:新增「组件与文件怎么分」五文件职责与 props 链、GameUI 注册、打开的三处入口、关闭归 InventoryPanel;示例解释:代码后解释根容器是入口、占位容器先定尺寸、后续只替换子树不重算坐标,并说明 props 三项由 UI 栈注入。
已完成扩写:docs/advanced/ii/ui/inventory-example-1-skeleton.md
自查:docs/advanced/ii/ui/inventory-example-2-grid.md — 渲染树:新增「从占位到网格」与「网格的树结构」,讲清 ItemGrid→定位容器→ItemCell 两层树、5 列坐标来源与 362 宽总尺寸、定位容器与格子同尺寸避免默认 200×200 遮挡;事件:新增「点击如何上报」,讲清 ItemCell→ItemGrid→InventoryPanel 的 emit/onSelect 链与每层职责;组件/元素:Item 只在示例(二)定义一次、items 为 ref<Item[]>、columns/cellSize/gap 用 computed、key 用 item.id;示例解释:每段代码后说明节点挂在哪层、props 怎么流、选中值为什么在面板,并写明普通网格是阶段性实现、示例(四)换 Scroll。
已完成扩写:docs/advanced/ii/ui/inventory-example-2-grid.md
自查:docs/advanced/ii/ui/inventory-example-3-detail.md — 渲染树:新增「详情区的树结构」,画出根容器→背景/标题/提示块/详情块/取消选择按钮,讲清 hidden 两块兄弟与文字宽度 164、描述从 120 到 236 的边界;事件:讲清取消选择只 emit clear、由面板写回 null,以及点击上报与 clear 是同一状态链的两端;组件/元素:selectedId 为 ref<string | null> 初始 null、find 用 ?? null 收口、selectedItem 在面板派生、ItemDetail 收 item 与 onClear、TextContent 的 width/autoHeight;示例解释:代码后说明按钮最后加入因此在最上层、详情不重复查列表、三种空态的显示与恢复。
已完成扩写:docs/advanced/ii/ui/inventory-example-3-detail.md
门禁(10-52 Task 2):prettier --write / --check 通过;docs:build green,0 dead link;页面 25 篇、demo 24 个不变。
自查:docs/advanced/ii/ui/inventory-example-4-scroll.md — 渲染树:新增「为什么要换滚动」与「Scroll 在渲染树里的位置」,画出左侧区域→Scroll→行容器→ItemCell 的树,讲清视口 372×244、右侧 28 像素给滚动条、行距 74、Scroll 内部滚动条层级、窗口外行的逻辑裁剪;事件:新增「滚动与事件」,讲清滚轮由 Scroll 自己处理、捕获阶段补滚动偏移、拖动与点击共用按下/移动/抬起、可点击元素避开滚动条区域;组件/元素:ItemGrid 根节点改为行容器数组以成为 Scroll 直接子元素、props 链不变、ScrollExpose 的 scrollTo/getScrollLength、padEnd、滚动位置在卸载与隐藏时的差异;示例解释:代码后说明行坐标不随滚动改变、为什么 ListPage 不作为最终方案、示例(五)(六)继续用 Scroll。
已完成扩写:docs/advanced/ii/ui/inventory-example-4-scroll.md
自查:docs/advanced/ii/ui/inventory-example-5-state.md — 渲染树:新增「操作条的树与事件流」,画出底部区域→ActionBar→三个按钮,讲清坐标与左侧区域不重叠;事件:讲清 equip/use/close 三类 emit、按钮命中与早返回、三条关闭入口汇到 controller.close、Esc 作用域;组件/元素:ActionBar 的 props 与 emits、equipped 语义是当前选中是否已装备、ItemCell 与 ItemGrid 的 equipped 三处同步改动、遮罩 noevent 与绘制顺序;示例解释:代码后说明状态变化分别落到哪处树节点、为什么不改子组件内部状态、关闭前确认应走 UI 栈。
已完成扩写:docs/advanced/ii/ui/inventory-example-5-state.md
自查:docs/advanced/ii/ui/inventory-example-6-animation-and-register.md — 渲染树:新增「动画作用在树的哪一层」与最终组装树,讲清呼吸描边与提示都是面板兄弟节点、noevent 不参与命中、动画不进子组件 props 链;事件:讲清 close 的三条入口与注册后从主 UI 栈打开、GameUI 是对象不是名字查找;组件/元素:五个文件落位、src/client/ui/index.ts 统一导出、InventoryPanel 注册、坐标与 props 链最终写法;示例解释:代码后说明动画节点位置与停止时机,并新增「最终组装与契约核对」九条表与「最终验证清单」逐项路径。
已完成扩写:docs/advanced/ii/ui/inventory-example-6-animation-and-register.md
门禁(10-52 Task 3):prettier --write / --check 通过;docs:build green,0 dead link;页面 25 篇、demo 24 个不变。
### 10-52 一致性核对
契约 1:通过 — 6 篇合并检查含 `ref<Item[]>`;`items` 只在 `InventoryPanel` 持有,`ItemGrid` / `ItemCell` 只读 props;示例(二)(四)(五)的网格代码均未引用父级闭包。
契约 2:通过 — `Item` 只在示例(二)定义一次;示例(三)(四)(五)(六)直接使用该类型,没有第二份定义。
契约 3:通过 — 合并检查含 `ref<string | null>`;示例(二)(三)(五)初始值均为 `null`,未选中显示「请选择道具」,示例(三)的「取消选择」写回 `null`。
契约 4:通过 — 合并检查含 `controller.close(props.instance)`;示例(一)(五)(六)都归面板关闭,`ActionBar` 只发 `close`,没有子组件直接关闭或只改提示的写法。
契约 5:通过 — 示例(四)明确「左侧最终方案是 Scroll」并说明替换示例(二);示例(五)(六)继续用 `Scroll`,没有把 `ListPage` 写成终选。
契约 6:通过 — 六篇统一左侧 `[54, 100, 400, 280]`、右侧 `[470, 100, 196, 280]`、操作条 `[54, 392, 304, 32]`、提示 `[54, 432]`;左侧下边界 380 与操作条 392 不重叠。
契约 7:通过 — 五个组件职责与 props 链一致;示例(五)显式给出 `equipped` / `equippedId` 的接口、props 数组与渲染三处改动,后续页面没有新增未声明依赖。
契约 8:通过 — 格子 key 统一 `item.id`;示例(四)行容器 `key={row}` 并说明行只表示位置,格子身份仍按 id。
契约 9:通过 — 示例(二)(三)(五)(六)的事件流均为 `ItemCell → ItemGrid → InventoryPanel`,操作条通过 `emit` 上报、面板决定动作。
D-93 抽查:docs/advanced/ii/ui/inventory-example-1-skeleton.md — 通过
D-93 抽查:docs/advanced/ii/ui/inventory-example-2-grid.md — 通过
D-93 抽查:docs/advanced/ii/ui/inventory-example-3-detail.md — 通过
D-93 抽查:docs/advanced/ii/ui/inventory-example-4-scroll.md — 通过
D-93 抽查:docs/advanced/ii/ui/inventory-example-5-state.md — 通过
D-93 抽查:docs/advanced/ii/ui/inventory-example-6-animation-and-register.md — 通过
扩写后本批页面聚合哈希:724022a6b6eecb4ae8e49829be8a16d74f48920505505c90be5856eab43d966f
体量参考(扩写后):`inventory-example-1-skeleton.md` 202 行;`inventory-example-2-grid.md` 297 行;`inventory-example-3-detail.md` 194 行;`inventory-example-4-scroll.md` 202 行;`inventory-example-5-state.md` 362 行;`inventory-example-6-animation-and-register.md` 264 行。6 篇总行数 1521,平均 253.5 行。仍不设 300 行门禁:低于 300 行不失败,高于 300 行也不失败;不注水、不堆接口表(D-88)。
### 10-52 门禁
- 结构:`docs/advanced/ii/ui` 25 篇 `.md`;`docs/.vitepress/components/demos/ui` 24 个 `.tsx`;6 篇正文均 CRLF、0 个 LF;覆盖表无 `待补`;每篇均有 `自查:` 与 `已完成扩写:`;6 篇均无「简化版 / v1 / 以后再做」表述。
- 聚合哈希:`本批外文件聚合哈希(复算)` 为 56fedcb45d7849d73a742d8afb95097eadc5a95e40423359ce9bcf9c164f4958,与基线一致;`ROADMAP 全文哈希(复算)` 为 fecfd9b5d7cd71389d58de9345efd6188649b0c7083f5d617d9cbc72563ee04a,与基线一致;`STATE 全文哈希(复算)` 为 e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133c3591,与基线一致;`demo 快照哈希(复算)` 为 02b1d6a88d414c9ce197b7bd8f7773020d8ae1c5c18099518595a66ca1ad6a4a,与基线一致;`扩写后本批页面聚合哈希` 与扩写前不同,且与按同一算法重算的结果一致。
- prettier:`cmd /c "pnpm exec prettier --check docs/advanced/ii/ui"`,exit 0,`All matched files use Prettier code style!`。
- ESLint:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,exit 0,0 error / 0 warning。
- docs 类型:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,exit 2;`docs/` 路径类型报错 0;既有引擎报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条,既有、非本轮引入、不得修)。
- 构建:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,exit 0,`build complete in 26.86s.`,0 dead link;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个;页面 25 篇、demo 24 个不变。
- D-93 逐篇结论:6 篇均讲清渲染树落点(节点挂在哪层、坐标与裁剪)、事件路径(命中与上报链)、组件/元素用法(props、内置组件、注册)、示例后解释(为什么现在加这一步),抽查全部通过。
停止点:10-52 只做 Part 5 深度扩写;不改 10-53 / 10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。
停止点:10-52 扩写结束;25 篇扩写全部完成;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-53 / 10-54;未 commit。
### 10-52 执行偏差
- 修改方式:本执行环境未提供再派生子代理的工具,6 篇正文与 NOTES 由执行器直接落盘;未调用 `opencode` 命令;不 commit。
- Task 2–5 的 verify 脚本在 PowerShell 5.1 与 `$ErrorActionPreference='Stop'` 下会把 `pnpm docs:build` 的正常 stderr 当成终止错误;执行时用同名 `cmd` 包装把原生命令的 stderr 降为 Continue,脚本其余断言原样执行,未修改计划、断言或构建命令。
- 写作期自查修正:示例(四)初稿提前带了 `equippedId`,已改为示例(五)再引入,保持增量顺序与契约 7 一致;未删改断言。
## 10-53 独立读者循环(第 2/3 轮)
用户确认(10-53):可以执行
用户原话(2026-11-01):「先进入读者循环吧,具体的问题到后面我再一个个提」
用户确认说明:Task 0 不再重复提问;用户同意直接进入独立读者循环,读者问题后续由用户逐条提出。
循环范围:25 篇 `docs/advanced/ii/ui/*.md`;Round 1 已完成(`10-49-READER-REVIEW.md`:25 篇、116 条提问、178 行分节概率),本计划执行 Round 2 / Round 3,最多 3 轮。
读者分组:A(Part 0–1,7 篇)、B(Part 2–3,7 篇)、C(Part 4,5 篇)、D(Part 5,6 篇);每轮至少 4 个独立读者,不得由单代理包办全部篇目。
用户更正(2026-11-01):Round 2/3 改为一个读者读完全部 25 篇,不是 4 组读者;4 组临时结果作废,`10-53` 的 4 组结构已被用户覆盖,按单读者结构记录。
Round 1 输入边界:只作内部输入,不复制、不改写、不交给用户;Round 2 读者使用新上下文。
基线 HEAD(10-53 读者循环):b94b4c3b41da8184312bc9f264654dc9a54adf69
循环前 docs 快照哈希:9b10f4285ff107be1b90e2f0c6078267fd6a881eb1a3d9532855c22adecb764b
循环前 docs 快照文件数:27(25 篇 UI 正文 + docs/advanced/ii/index.md + docs/advanced/index.md)
读者派发方式:orchestrator 子代理(单读者)
Round 2 单读者输入:`C:\Users\13194\AppData\Local\Temp\opencode\round2-single.md`(25 篇、53 条提问、16 条跨篇问题;表格篇目为简称,记录时归一化为 `docs/advanced/ii/ui/<slug>.md`)。
阻断判定口径:缺前置、术语未定义、步骤缺失、明确矛盾、缺 import/入口、D-93 模型/事件/组件没讲清;设计取舍/风格/详略不修。
记录归属:仅 `.planning`,append-only、带 `### 第 N 轮`;不写入 docs 正文,不交给用户。
修改方式:Task 1 由执行器内联写基线记录(不改 docs、不派读者);读者与修订者由 orchestrator 派发子代理执行。
停止点:10-53 只做读者循环;不进入 10-54 用户审阅;不写 SUMMARY / ROADMAP / STATE;不 commit。
第 2 轮读者:单读者读完全部 25 篇(用户更正,4 组作废);53 条逐篇提问 + 16 条跨篇问题。
第 2 轮分诊:阻断 29 条、非阻断 40 条;编号 R2-01…R2-69;逐条理由与处理见 `10-53-READER-REVIEW.md`。
第 2 轮修订:阻断 29 条,已修 29 条,未修 0 条;修订者同时按 D-93 检查渲染树、事件、组件与示例后解释,不只按问题清单修。
第 2 轮门禁:prettier `--write` / `--check docs/advanced/ii/ui` exit 0;ESLint exit 0、0 error / 0 warning;`vue-tsc --noEmit -p docs/tsconfig.json` exit 2、`docs/` 路径 0 条类型错误、既有引擎报错 11 条(不得修);`docs:build` exit 0、`build complete in 33.00s.`、0 dead link;`public/_docs/advanced/ii/ui` 下 `.html` 25 个;25 篇 `.md` / 24 个 demo 不变;25 篇正文均 CRLF。
循环后 docs 快照哈希(第 2 轮修订后):18b7c3927564da58d359dbd08809defb70b19c7116aaa4aaffdabdb3c7b1fa76
停止点:第 2 轮已完成并修订;未开始 Round 3;未进入 10-54 用户审阅;未写 SUMMARY / ROADMAP / STATE;未 commit。
### 10-53 最终门禁
第 3 轮读者:单读者读完全部 25 篇(未看前两轮清单);47 条逐篇提问 + 9 条跨篇问题。
第 3 轮分诊:阻断 22 条、非阻断 34 条;逐条理由与处理见 `10-53-READER-REVIEW.md`。
第 3 轮修订:阻断 22 条,已修 22 条,未修 0 条;修订者同时按 D-93 检查模型、事件、组件与示例后解释,不只按问题清单修。
轮次完整性:Round 2(阻断 29)+ Round 3(阻断 22);加上 Round 1 共 3 轮,达到 D-91 上限;不存在第 4 轮;第 3 轮修订后无剩余阻断。
结构门禁:25 篇 `.md` / 24 个 demo / `public/_docs/advanced/ii/ui` 下 25 个 `.html`;25 篇正文均 CRLF;未新增/删除页面。
质量门禁:prettier `--check docs/advanced/ii/ui` exit 0;ESLint exit 0、0 error / 0 warning;`vue-tsc --noEmit -p docs/tsconfig.json` exit 2、`docs/` 路径 0 条类型错误、既有引擎报错 11 条(不得修);`docs:build` exit 0、`build complete in 20.34s.`、0 dead link。
循环后 docs 快照哈希:b667ff1e3e604aada8704dfb722a7363ae444ed3cb13ca07b58637ea806d278e
快照对比:循环前 `9b10f428…`、第 2 轮后 `18b7c392…`、本轮后 `b667ff1e…`;三次不同,说明修订确实落到正文。
读者循环结论:已完成
记录归属:仅 .planning,未交给用户
停止点:10-53 读者循环结束;不进入 10-54 用户审阅;不写 SUMMARY / ROADMAP / STATE;不 commit。
### 重跑 Round 1(D-94)
用户指令(2026-11-01):按 D-94 重跑读者循环;先汇总 Round 1、分诊阻断、只修阻断,不开始 Round 2;22:05 停止。
旧轮次:`10-49-READER-REVIEW.md` 的 Round 1 与 `10-53-READER-REVIEW.md` 的 Round 2/3 未读非目标文档,不满足 D-94 → 已标注作废、仅保留历史,不删除。
Round 1(D-94)输入:`10-53-READER-REVIEW-ROUND1-D94.md`(单读者;非目标文档 + 25 篇目标;83 条逐篇提问、10 条跨篇问题)。
Round 1(D-94)分诊:阻断 16 条、非阻断 14 条(按篇汇总);编号 R1-01…R1-30;逐条理由与处理见 `10-53-READER-REVIEW.md`。
Round 1(D-94)修订:阻断 16 条,已修 5 条(R1-01/12/21/24/30,另附带澄清 R1-10),交用户 11 条,未修 0 条。
修订范围:`ui-template.md`、`reactivity.md`、`builtin-text-and-input.md`、`inventory-example-6-animation-and-register.md`、`layer-transform-performance.md`;未改页面结构、未新增/删除页面、未改 demo。
停止点:Round 1(D-94)已汇总并修完可在文档内解决的阻断;未开始 Round 2;未跑最终门禁(prettier/ESLint/类型/构建);不写 SUMMARY / ROADMAP / STATE;不 commit。
## 前置去重与 mermaid(重跑前)
用户指令(2026-11-01):「先收集其他文档中已经讲过的内容,把这些内容删除,然后再重新审阅循环。」已批准执行本次去重 + 补图;**不开始读者循环**。
输入:`10-UI-DEDUP-COVERAGE.md`(主题覆盖表、明确不应写进 UI 的内容、mermaid 位置表)。范围:只改 `docs/advanced/ii/ui/*.md` 与本 NOTES;不改非目标文档、demo、侧边栏、源码、ROADMAP / STATE;不 commit。
### 删除 / 压缩项(按权威页归并)
- **工程命令与别名**:`ui-template.md` 删除 `pnpm install` / `pnpm dev` / `pnpm docs:dev` 与 `@motajs/*` / `@user/*` 路径映射整段,改为一句指向仓库根 `dev.md` 与 `src-tour.md`;`inventory-example-1-skeleton.md` 同类命令段改为一句指向 `dev.md`。`dev.md` 在 docs 根之外,VitePress 不能做相对链接,写成纯文本路径(首次构建 2 个 dead link 即来自此,已改掉)。
- **渲染树**:权威 = `container-and-coordinates.md` §渲染树。`ui-template.md` §这份模板在渲染树里的位置 删掉三层列表与 `text` 树,压成一句 + 链接;`inventory-example-1-skeleton.md` 删掉 `text` 树,保留五个区域坐标事实 + 链接;`component-tsx.md` 只保留「组件树 vs 元素树」差异(新增映射图)。
- **zIndex / 命中**:规则权威 = `layer-transform-performance.md`,命中权威 = `events.md`。`container-and-coordinates.md` 两处规则压成一句 + 链接;`basic-shapes.md` 的 zIndex 段压成一句 + 链接;`inventory-example-1-skeleton.md` 删掉命中顺序长段;`ui-controller-and-stack.md` 的 `i * 5` 段改为指向本篇前文;`ui-performance.md` §命中与事件 只留遍历成本与 `noevent` 性能建议 + 链接。
- **事件 / 捕获冒泡 / 坐标 / noevent**:权威 = `events.md`。`container-and-coordinates.md` §事件在嵌套容器中的路径 保留命中→捕获→冒泡三段,删掉 `stopPropagation` / `enter`-`leave` 细节改链接;`ui-template.md` §事件从哪里进入 整段压成一句 + 链接;`layer-transform-performance.md` 删除「事件坐标与变换」「noevent」两整节,合并为一小节 + 链接(标题保留 `## 事件坐标与 noevent`)。
- **hidden vs 三元**:权威 = `conditional-and-list-rendering.md`。`layer-transform-performance.md` §显示开关 只留 `hidden` 原则、与缓存的关系,删掉四种场景列表与三元素例,末尾重复的选型表整节删除;`ui-performance.md` §显示开关 压成一段 + 链接;`container-and-coordinates.md` 保留一句 + 链接。
- **缓存 / 脏更新**:机制权威 = `layer-transform-performance.md`;`ui-performance.md` §缓存 删除默认缓存标签列表与两段修正代码,只留「何时值得开 / 三类不适合 / 判断标准」并链接机制篇;`container-and-coordinates.md` §生命周期与缓存 删除机制段与两段缓存代码,改为一句 + 链接;`image-and-texture.md` 像素图特例保持不变(权威)。
- **GameUI 名字不参与查找**:权威 = `ui-template.md` §GameUI 是一个对象,不是名字。`ui-controller-and-stack.md` 两处、`inventory-example-6-animation-and-register.md`、`replace-builtin-ui.md` 各压成一句 + 链接。
- **泛型顺序**:权威 = `props.md` §泛型顺序。`component-tsx.md` 删除四行表格与逐位解释,压成一句 + 链接;`slots-and-attrs.md` 删除「四个泛型依次是…」的顺序复述,保留 slot 专属部分 + 链接。
- **props 不解构**:权威 = `props.md` §props 是响应式的,不要解构。`reactivity.md` 删除代码块与展开,压成两句 + 链接。
- **props 基础注入链**:权威 = `ui-controller-and-stack.md` §事件归属与生命周期。`ui-performance.md` §基础 props 删除代码与机制,只留「creator 里不要做重活」+ 链接。
- **目录扫描 / 注册**:`ui-template.md` 删除「没有目录扫描…」长段,压成一句 + `src-tour.md` 链接;保留 `src/client/ui/index.ts` 统一出口这一 UI 特有事实。
### 必须保留、未删的 UI 特有内容
渲染树三层与容器三职责、`loc` 六元组 / `anc` / 默认 200×200、命中测试五条与 `enter` / `leave` 集合差(`events.md`)、`hidden` / `noevent` / `actionStroke` / `cursor` 行为、缓存机制与 `nocache` 优先级、UI 栈四层与策略 / `keep` / 背景四名、`setPropsBaseCreator` 注入链、内置组件、纹理、按键作用域、替换内置 UI、UI 性能六层定位与观测流程。页面数量(25)、demo 数量(24)、侧边栏均未改。
### 新增 mermaid(9 张图,覆盖 8 个主图位置)
1. `container-and-coordinates.md` §渲染树:`flowchart TD`(替换原 `text` 树)——画布根 → UI 容器 → 面板根 → 区域 / 叶子。
2. `events.md` §命中测试:`flowchart TD` + 两个决策节点——zIndex 先问谁、`hidden` / `noevent` 跳过。
3. `events.md` §捕获与冒泡:`sequenceDiagram`——根 → 面板 → 按钮捕获,按钮 → 面板 → 根冒泡,`stopPropagation` 截断说明。
4. `layer-transform-performance.md` §缓存与脏更新:`flowchart TD`——变化 → 标脏 → 沿父链上冒 → 重画,`custom` 手动触发分支。
5. `ui-controller-and-stack.md` §控制器、实例与栈:`classDiagram`——`GameUI` / `UIController` / `UIInstance` / `UIContainer` 持有与创建关系。
6. `ui-controller-and-stack.md` §栈策略:`stateDiagram-v2`——`open` / `hide` / `show` / `close` 在 `lastOnly` 与 `showAll` 下的迁移。
7. `component-tsx.md` §组件如何映射成一棵子树:`flowchart TD`——组件树与元素树的对应,组件边界不可见。
8. `reactivity.md` §数据变化如何走到渲染树:`flowchart LR`——数据 → 渲染函数 → VNode → 元素属性 → 绘制。
9. `props.md` §props 的完整管线:`flowchart LR`——父属性 → VNode props → `props` 数组分叉 → setup / attrs。
均为 ` ```mermaid ` 代码块、中文标签、配 1–3 句说明;未引入新依赖。全 UI 子分组 `mermaid` 计数 9(原 0),原有 `text` 树块仅保留 inventory-6 的目录树(清单建议不替换)。
### 门禁(2026-11-01 21:27 前后)
- prettier:`cmd /c "pnpm exec prettier --check docs/advanced/ii/ui"` exit 0,`All matched files use Prettier code style!`。
- ESLint:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"` exit 0,0 error / 0 warning。
- 构建:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` exit 0,`build complete in 25.22s.`,0 dead link。
- 结构:`docs/advanced/ii/ui` 25 篇 `.md`;`docs/.vitepress/components/demos/ui` 24 个 `.tsx`;`public/_docs/advanced/ii/ui` 25 个 `.html`;25 篇正文均 CRLF、无 LF-only。
- 未改:ROADMAP / STATE / 非目标文档 / demo / 侧边栏 / 源码;未 commit、未 stash、未切换分支。
### 未完成 / 停止点
- 未开始读者循环(按用户要求先去重、重跑循环留待下一步)。
- 未做 `vue-tsc` 类型检查(本次只改 Markdown 与 mermaid,未触 TypeScript);如需与 10-53 同等门禁可补跑。
- 停止点:前置去重与 8 个主图位置已完成;不进入读者循环;不写 SUMMARY / ROADMAP / STATE;不 commit。
### 重跑 Round 2(D-94)
用户指令(2026-11-01):按 D-94 重跑 Round 2;单读者、先读非目标文档再读 25 篇;只修阻断;22:25 停止;不开始 Round 3;不 commit。
输入:`10-53-READER-REVIEW-ROUND2-D94.md`(单读者;非目标文档 + 25 篇目标文档;25 条逐篇提问、8 条跨篇问题)。
Round 2(D-94)分诊:阻断 9 条、非阻断 24 条;编号 `R2-01…R2-33`(本节独立编号,与上方已作废的第 2 轮 `R2-01…R2-69` 无关);逐条理由与处理见 `10-53-READER-REVIEW.md`。
Round 2(D-94)修订:阻断 9 条,已修 7 条(3 处正文),交用户 2 条(R2-02、R2-17,均依赖 UI 容器/主场景实现),未修 0 条。
修订范围:`docs/advanced/ii/ui/props.md`(对象型 prop 内部字段追踪)、`docs/advanced/ii/ui/builtin-text-and-input.md`(`Textbox` 尺寸来源)、`docs/advanced/ii/ui/inventory-example-1-skeleton.md`(480×320 首次验证的缩放做法);未改页面结构、未新增/删除页面、未改 demo。
门禁:prettier `--check` 三篇 exit 0;ESLint `docs/.vitepress/components/demos/ui` exit 0、0 error / 0 warning;`vue-tsc --noEmit -p docs/tsconfig.json` exit 2、`docs/` 路径 0 条类型错误、既有引擎报错 11 条(不得修);`docs:build` exit 0、`build complete in 18.38s.`(最终一次)、0 dead link;`public/_docs/advanced/ii/ui` 下 25 个 `.html`;25 篇 `.md` / 24 个 demo 不变;25 篇正文均 CRLF。
未完成项:无(7 条阻断已修,2 条交用户;Round 3 按指令未开始;最终门禁无待跑项)。
停止点:Round 2(D-94)已汇总并修完可在文档内解决的阻断;**未开始 Round 3**;未进入 10-54 用户审阅;不写 SUMMARY / ROADMAP / STATE;不 commit。
### 重跑 Round 3(D-94)
用户指令(2026-11-02):执行第 3 轮(最后一轮)D-94 读者审阅;单读者、先读非目标文档再读 25 篇;只修阻断;跑最终门禁;不开始 Round 4 / 10-54;不 commit;22:00 停止。
输入:`10-53-READER-REVIEW-ROUND3-D94.md`(单读者;非目标文档 + 25 篇目标文档;124 条逐篇提问、14 条跨篇问题)。原记录先落在临时目录,已按前两轮做法复制到计划目录,未改内容。
Round 3(D-94)分诊:阻断 7 条、非阻断 36 行;编号 `R3-01…R3-43`(跨篇 R3-34/35/40 分别与 R3-17/06/10 同项,不重复计数);逐条理由与处理见 `10-53-READER-REVIEW.md`。
Round 3(D-94)修订:阻断 7 条,已修 6 条(落在 6 处正文),交用户 1 条(R3-19,`mainUIController.render()` 的主场景挂载,沿用 R2-17),未修 0 条。
修订范围:`docs/advanced/ii/ui/container-and-coordinates.md`(`loc` 两两一组的写法)、`docs/advanced/ii/ui/image-and-texture.md`(`ITexture`/`Texture` 导入与类型)、`docs/advanced/ii/ui/hotkey-in-ui.md`(普通子组件的 `useKey` 入口)、`docs/advanced/ii/ui/builtin-text-and-input.md`(`Textbox` 高度来源)、`docs/advanced/ii/ui/ui-controller-and-stack.md`(`keep` 的 close 顺序)、`docs/advanced/ii/ui/replace-builtin-ui.md`(`openSettings` 示例签名)。未改页面结构、未新增/删除页面、未改 demo、未改源码。
最终门禁(2026-11-02 14:25 前后):
- prettier:`cmd /c "pnpm exec prettier --check docs/advanced/ii/ui"` exit 0,`All matched files use Prettier code style!`。
- ESLint:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"` exit 0,0 error / 0 warning。
- 类型:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` exit 2;`docs/` 路径 0 条类型错误;既有引擎报错 11 条(`packages/common/src/logger.ts` 3 条、`packages/render/src/core/types.ts` 8 条,不得修)。
- 构建:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` exit 0,`build complete in 18.21s.`(最后一次;补 `loc` 说明后重跑),0 dead link。
- 结构:`docs/advanced/ii/ui` 25 篇 `.md`;`docs/.vitepress/components/demos/ui` 24 个 `.tsx`;`public/_docs/advanced/ii/ui` 25 个 `.html`;25 篇正文均 CRLF、无 LF-only。
- 最终 docs 快照哈希(27 个文件:25 篇 UI 正文 + `docs/advanced/ii/index.md` + `docs/advanced/index.md`;按相对路径排序,`path:sha256(content)` 逐行拼接后再 sha256,不剥注释):`c444757333e536123ed0fa170b3faeb805930007ec773247e74ce6c802521132`。
未完成项:无(6 条阻断已修,1 条交用户;Round 4 按指令未开始;最终门禁无待跑项)。
停止点:10-53 读者循环结束;未进入 10-54;未写 SUMMARY/ROADMAP/STATE;未 commit。
## 10-54 用户审阅与收尾
用户确认(10-54):已完成(非示例)
用户原文(2026-11-15):「这部分文档算是差不多全看完了。示例部分先保留,标记为待审阅,先不审阅它。你把文档审阅计划标记为已完成,把当前计划收尾。」
审阅范围:25 篇 docs/advanced/ii/ui/*.md;其中 19 篇非示例文档已审阅完成,6 篇示例文档保留现状并标记为待审阅。
示例待审阅清单:inventory-example-1-skeleton.md、inventory-example-2-grid.md、inventory-example-3-detail.md、inventory-example-4-scroll.md、inventory-example-5-state.md、inventory-example-6-animation-and-register.md。
审阅结论:文档审阅计划已完成(带待审阅项);示例不纳入本轮完成范围。
计划状态:已完成(带待审阅项);不代表 25 篇全部审阅完成。
停止点:10-54 文档审阅收尾;示例 1-6 待审阅;未改源码/demo;未 commit。
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,226 @@
# UI 文档去重与 mermaid 覆盖清单
> 范围:`docs/advanced/ii/ui/` 下 25 篇为目标文档;本清单只做覆盖判断与图位置标记,不修改任何文档。
> 依据:D-94(先读非目标文档)、D-95(实际使用 mermaid)。本文件为只读调研产物。
## 读取范围(按 D-94 顺序,实际读过的非目标文档)
标注说明:**通读** = 逐段读完;**标题+导语+关键节** = 读完标题结构与导语,并抽读与 UI 相关的关键节(多为数据端领域细节,UI 文档不可能重复)。
### 1. `docs/intermediate/*.md`(24 篇,全部)
| 文档 | 读取程度 | 与 UI 去重相关的要点 |
| --- | --- | --- |
| `code-basics.md` | 通读 | 最小 TS/JS 语法;「示例一律省略 import」的约定(第 87–95 行) |
| `data-vs-render.md` | 通读 | 双端分工 + mermaid 示例(第 17–23 行);渲染端结构标为「高级教程」预留 |
| `src-tour.md` | 通读 | 三层包与别名(第 7–15 行)、`src/client` 目录(第 29–38 行)、常量与入口 |
| `data-state-overview.md` | 通读 | `state` 来源、常用对象表、L0–L3(第 85–107 行) |
| `hooks.md` | 通读 | 钩子族表、改内置 vs 自写、异步钩子;渲染端提示 `onTip` |
| `events.md` | 通读 | 数据端内建函数、`IBlockEventEnv`、注册流程 |
| `data-plugins.md` | 通读 | `IDataPluginDefine`、三时机、注册列表、可存档 |
| `replay-commands.md` | 通读 | 录像原则、主/被动、装饰器 |
| `map-structure.md` / `map-tiles.md` / `tile-store.md` | 通读 | 楼层/图层/图块数字、zIndex 概念(地图层) |
| `hero-location.md` / `hero-attribute.md` / `hero-items.md` / `hero-equipment.md` | 通读 | 数据端对象入口与修饰器 |
| `flags.md` | 通读 | 全局可存档变量 |
| `combat-overview.md` | 通读 | 战斗流程 + mermaid(第 65–74 行) |
| `enemy-specials.md` / `enemy-aura.md` / `enemy-query.md` / `enemy-calculator.md` / `enemy-map-damage.md` / `enemy-combat-script.md` / `enemy-final.md` / `enemy-status-hooks.md` | 标题+导语+关键节 | 战斗领域细节,与 UI 无交集;确认无需在 UI 重复 |
### 2. `docs/advanced/index.md` + `docs/advanced/i/*.md`(11 篇)
| 文档 | 读取程度 | 要点 |
| --- | --- | --- |
| `advanced/index.md` | 通读 | 三层定位;第 38–39 行明确「高级 II 已收录自定义 UI 与渲染」,且「不重复中级已讲内容」 |
| `i/index.md` | 通读 | 高级 I 九篇地图;渲染端当时「尚未完工」的表述(第 15、75 行) |
| `i/declarative-vs-imperative.md` | 通读 | 声明式/命令式、副作用、扩展点表;「录像只记入口动作」 |
| `i/plugin-system.md` | 通读 | 两端插件、目录与 `list.ts` 注册(第 24–82 行)、三时机与依赖(第 84–265 行)、错误码 76/77/78 |
| `i/hooks-in-depth.md` | 通读 | 一对象一实例、控制器、异步钩子;与 UI 无关 |
| `i/data-stores.md` | 通读 | 五个 Store 读法、运行期只读 |
| `i/saveable-content.md` | 前 80 行 + 标题 | 什么该存/不该存、`ISaveableContent` |
| `i/replay-consistency.md` | 前 60 行 + 标题 | `@shouldReplay`/`@ignoreReplay`,仅数据端 |
| `i/mover.md` | 前 60 行 + 标题 | 移动器模型;渲染端动画标为 TODO |
| `i/face-handler.md` | 前 60 行 + 标题 | 朝向模型;「渲染端读取后完成显示」 |
### 3. `docs/advanced/ii/index.md` + `docs/advanced/ii/*.md`(排除 `ui/`,9 篇)
| 文档 | 读取程度 | 要点 |
| --- | --- | --- |
| `ii/index.md` | 通读 | 第 15、52–54 行:UI 子分组 25 篇,入口 `ui/ui-template.md`,Part 0 不要求高级 I |
| `ii/point-and-tile-events.md` | 通读 | 点事件/图块事件、事件视图、存档 |
| `ii/static-vs-dynamic-tiles.md` | 通读 | 静/动态图块、`keepEvent`、告警 127/128/129 |
| `ii/pathfinding.md` | 前 70 行 + 标题 | 寻路四段 + mermaid(第 29–34 行) |
| `ii/enemy-context-and-combat.md` | 前 80 行 + 标题 | buildup 五段 + mermaid(第 61–69 行) |
| `ii/custom-range.md` | 前 50 行 + 标题 | 范围对象与宿主 |
| `ii/equipment-system.md` | 前 45 行 + 标题 | 装备实例、渲染端动画标为 TODO |
| `ii/custom-replay-command.md` | 前 40 行 + 标题 | 指令码、注册 |
| `ii/adding-hero-attribute.md` / `ii/adding-enemy-attribute.md` | 前 60/40 行 + 标题 | 属性接入链路;「显示」部分留给编辑器与渲染端 |
### 4. `docs/advanced/iii/*.md`(7 篇)
| 文档 | 读取程度 | 要点 |
| --- | --- | --- |
| `iii/index.md` | 通读 | 第 90–96 行明确「本层不覆盖渲染端的结构、动画与输入处理」 |
| `iii/core-state.md` | 通读 | 四层、构造顺序、MainDataPlugin 装配 + mermaid |
| `iii/plugin-internals.md` | 前 70 行 + 标题 | 插件表/依赖图/拓扑序/三阶段 + mermaid |
| `iii/event-system.md` | 通读 | 事件仓库、触发器 11 值、收集/执行 + mermaid |
| `iii/loading-system.md` | 通读 | 加载三阶段、配置、`addCustomContent`;第 283 行说明渲染端可复用加载器追加贴图/音频/动画/字体 |
| `iii/replay-internals.md` | 前 50 行 + 标题 | 录像存储布局 + mermaid |
| `iii/passability-and-pathfinding.md` | 前 50 行 + 标题 | 通行谓词 + mermaid |
### 5. 其它非目标文档
| 文档 | 读取程度 | 要点 |
| --- | --- | --- |
| `docs/poc/render-demo.md` | 通读 | 文档内嵌 demo 的技术验证页,不入导航 |
| `README.md` | 通读 | 仅版本更新记录 |
| `dev.md` | 通读 | 项目结构、开发/构建命令(第 12–37 行)、命名与注释规范、双端分离(第 127–160 行) |
| `AGENTS.md` | 通读 | 流程约束(不改注释、走 GSD、先确认等),不影响内容判断 |
未读:`.planning/`(除写入本文件)、任何 `.ts/.tsx/.vue/.json`、`packages*/`、`src/`、旧文档与旧审阅记录。
## 主题覆盖表
| 主题 | 已覆盖位置 | 已讲到什么 | UI 可能重复页 | 建议 |
| --- | --- | --- | --- | --- |
| 工程命令(安装/开发/文档站) | `dev.md` §开发说明(`pnpm i`、`pnpm dev`);`dev.md` §构建说明 | 依赖版本、安装与开发、构建与 lint 命令 | `ui-template.md:43`、`inventory-example-1-skeleton.md:47` | 从 UI 删除命令说明,改为「见 dev.md」。`docs:dev` 在 dev.md 中未列,先按待确认项 1 处理 |
| 包分层与别名 | `src-tour.md` §包从哪来(第 7–15 行:`src`→`packages-user`→`packages`,`@user/*`、`@motajs/*`);`dev.md` §项目结构 | 三层含义、依赖单向、示例 import 照抄 | `ui-template.md:43`(`@motajs/*`→`packages/*/src`) | 删除路径映射式解释;UI 只保留「本篇示例用到的包各自提供什么」,别名规则链接 `src-tour.md` |
| 双端分离(为什么 UI 不进录像) | `data-vs-render.md` 全篇;`declarative-vs-imperative.md` §为什么这样设计;`replay-consistency.md:57` | 数据端算、渲染端画;录像只跑数据端;装饰器仅数据端 | `ui-performance.md` 等未展开,`hotkey-in-ui.md` 也未提 | UI 侧最多一句「UI 与录像无关」,不重述双端模型 |
| 文件放哪 / 如何被加载 | `src-tour.md` §src/client(第 29–38 行);`plugin-system.md` §注册与目录(第 24–47 行) | `src/client/{entry,initialize,plugin,ui}`;插件放 `plugin/<name>/` 并加入 `list.ts`;无自动扫描 | `ui-template.md` §文件放在哪里(第 153–173 行);`inventory-example-6` §注册与打开(第 194–224 行);`replace-builtin-ui.md` §替换步骤 | UI 保留 `src/client/ui/index.ts` 统一出口这一 UI 特有事实;删除重复的「无目录扫描」长段,链接 `src-tour.md` |
| 插件三时机与依赖 | `data-plugins.md` §时机次序;`plugin-system.md` §生命周期/§状态与顺序;`plugin-internals.md` 全篇 | `awake` 同步、`initialize`/`afterLoad` 阻塞;依赖拓扑序;错误码 76/77/78 | UI 文档基本未重复(仅 `ui-template.md:41` 提到包来源) | 不写入 UI;若 UI 需要「UI 是否该做成插件」,一句链接 `plugin-system.md` |
| 数据端 `state` 与 L0–L3 | `data-state-overview.md` §state/L0–L3;`core-state.md` 全篇 | `state` 获取三途径、分层是静态类型叠加、四层构造顺序 | UI 的 `props.state` 是 `IClientCore`,与数据端 `state` 同名不同义 | 不要解释数据端 `state`;UI 必须显式声明「本组分的 `state` 指客户端核心」,避免读者混淆(见待确认项 4) |
| 数据端事件系统 | `events.md`(中级)、`event-system.md`、`point-and-tile-events.md` | 触发器、收集顺序(点事件组整体优先)、执行与折叠 | `events.md`(UI)与 `hotkey-in-ui.md` 讲指针/键盘,不涉及地图事件 | UI 不重述事件系统;仅在 `container-and-coordinates.md` 提「事件层」时用链接(现未提,保持) |
| 地图 zIndex | `map-structure.md` 第 52–53 行(图层 `zIndex` 决定遮挡) | 图层纵深概念 | UI 的 `zIndex` 是渲染树兄弟排序,不是地图图层 | 两处同名不同域,UI 侧不需引用;如需对照,一句脚注 |
| Store(tile/item/map/enemy/event) | `data-stores.md` 全篇;`tile-store.md` | 五表、读法、运行期只读、错误码 133/134/170/181 | UI 文档未涉及 | 不写入 UI |
| 数据端钩子 | `hooks.md` §常用钩子族一览/§异步钩子;`hooks-in-depth.md` | 钩子族、注册/移除、`Promise.all` | `hotkey-in-ui.md` 的「作用域」是另一套机制 | 不写入;若要对比,一句「按键作用域不是数据端钩子」 |
| 存档 / 录像 | `saveable-content.md`、`replay-commands.md`、`replay-consistency.md`、`replay-internals.md` | 存什么、怎么注册、录像格式 | UI 文档未涉及 | 不写入 UI |
| 加载系统 | `loading-system.md` 全篇(第 283 行:渲染端可复用加载器追加贴图/音频/动画/字体);`data-plugins.md` | 三阶段、`onCoreConfigLoaded`、`addCustomContent`、`getConfig` | `image-and-texture.md` §加载一张 PNG(第 59–107 行)自行 `new Image` 加载 | 保留「素材管理器取纹理」为主路径;手动加载只作为兜底,并链接 `loading-system.md`(见待确认项 7) |
| 性能(引擎级) | `advanced/index.md:39`、`ii/index.md:82`、`iii/index.md:90–96` | 引擎级性能属高级 III;本层不覆盖渲染管线 | `ui-performance.md` 第 3 行已正确链接高级 III | 保留现有边界声明,不重复引擎级内容 |
| 错误码 / 告警 | `plugin-system.md`(76–80)、`event-system.md`(136/171/172)、`data-stores.md`(133/134/170/181)、`static-vs-dynamic-tiles.md`(127–129) | 各系统的错误码语义 | UI 文档只有「告警」字样,无错误码(已检索确认) | UI 不新增错误码表;若需提示「不会报错」,沿用「静默失效」描述 |
| 调试 / 观测 | `ui-performance.md` §观测与验证(第 149–159 行)、§症状与排查(第 161–173 行) | 用浏览器性能面板录帧、做减法定位、一次只改一个开关;按症状查层 | 仅 `ui-performance.md` 自身;全站无独立调试篇 | 保留此两节即可,不新增 devtools/日志章节(与 UI 教程职责不符) |
| 渲染树 / 元素树 | 仅 UI 子分组;`advanced/iii/index.md:90–96` 明确排除渲染端 | 画布根 → UI 容器 → 面板根 → 子元素;组件树与元素树两层 | `ui-template.md` §这份模板在渲染树里的位置(第 79–103 行)、`container-and-coordinates.md` §渲染树(第 11–36 行)、`component-tsx.md` §组件如何映射成一棵子树(第 5–40 行)、`inventory-example-1` §骨架在渲染树里的位置(第 19–49 行) | **四处重复**。保留 `container-and-coordinates.md` 为权威(含职责与缓存边界),其余改为一句 + 链接;`component-tsx` 只保留「组件树 vs 元素树」差异 |
| Vue 响应式 / 组件 | 仅 UI 子分组;`code-basics.md` 只讲 TS 语法 | `ref/reactive/computed/watch/nextTick/shallowRef/markRaw`;组件结构、生命周期 | `reactivity.md` 全篇;`component-tsx.md` §生命周期(第 211–268 行);`props.md` §props 不是响应式的(第 256–279 行);`slots-and-attrs.md` 第 59–61 行(泛型顺序) | 权威分工:`reactivity.md`(响应式)、`props.md`(参数管线)、`component-tsx.md`(组件结构/生命周期)、`slots-and-attrs.md`(slot/attrs)。删除 `props.md` 与 `reactivity.md` 的「不要解构」双写、`component-tsx` 与 `slots-and-attrs` 的泛型顺序双写 |
| 事件命中 / 捕获冒泡 | `events.md`(UI);`container-and-coordinates.md` §事件在嵌套容器中的路径;`ui-template.md` §事件从哪里进入 | 命中规则 5 条、捕获/冒泡顺序、`stopPropagation`、`enter/leave` 集合差、事件对象字段、`offset` vs `absolute` | `events.md` 第 5–24、44–51、130–151、153–166 行;`container-and-coordinates.md` 第 56–68 行;`ui-template.md` 第 105–111 行;`layer-transform-performance.md` §事件坐标与变换(第 149–179 行);`ui-performance.md` §命中与事件(第 122–136 行) | 权威 = `events.md`。`container` 只留「路径三段」摘要 + 链接;`ui-template` 删除整段;`layer-transform` 删除「事件坐标」整节(与 `events.md` §事件对象/§事件坐标重复);`ui-performance` 只留「遍历成本」一句 + 链接 |
| zIndex / 层叠 | `events.md` §命中测试、`layer-transform-performance.md` §渲染树、层级与绘制顺序、`container-and-coordinates.md` §层级、`basic-shapes.md:9`、`inventory-example-1:49` | 绘制小→大、命中大→小、同值按插入顺序、只在同父级比较、父级带整棵子树比较 | 五处以上重复;另 `ui-controller-and-stack.md` §事件归属(第 222 行)说「栈内 `i*5`」 | 权威 = `layer-transform-performance.md`(规则)+ `ui-controller`(栈的 `i*5` 特例)。`basic-shapes`、`inventory-1` 删除;`container` 保留一句;`events` 保留「命中规则」角度 |
| `hidden` vs 三元 | `conditional-and-list-rendering.md` §条件渲染改的是树(第 5–41 行);`layer-transform-performance.md` §显示开关(第 72–116 行);`ui-performance.md` §显示开关(第 69–97 行);`container-and-coordinates.md` 第 91 行 | 语义差别、何时用哪个、对状态/缓存的影响 | 四页各有一份近乎相同的说明与表格(`layer-transform` 与 `ui-performance` 的「四种情况」列表基本逐字相同) | 权威 = `conditional-and-list-rendering.md`(语义与选型表);`layer-transform` 只留「与缓存的关系」;`ui-performance` 删除重复列表,改为一句 + 链接;`container` 保留一句 |
| 缓存 / 脏更新 / `hd` `anti` | `layer-transform-performance.md` §缓存与脏更新(第 118–147 行);`ui-performance.md` §缓存(第 22–67 行);`container-and-coordinates.md` §生命周期与缓存(第 70–91 行);`image-and-texture.md` §像素图与高清缓存(第 121–138 行) | 默认缓存标签、`nocache` 优先级、脏标记向上冒泡、`custom` 需手动触发、`hd` 仅对缓存生效 | 机制段在 `layer-transform` 与 `container` 重复;策略段在 `ui-performance` 与 `layer-transform` 重复 | 权威 = `layer-transform`(机制);`ui-performance` 只保留「何时值得开」与排查表;`container` 删除机制段;`image` 保留像素图特例(`noanti`/整数倍) |
| `noevent` / `actionStroke` / `cursor` | `events.md` §noevent/§cursor/§actionStroke;`layer-transform-performance.md` §noevent(第 181–206 行);`container-and-coordinates.md` 第 66 行;`ui-performance.md` §命中与事件;`inventory-example-5` §按钮的 noevent(第 303 行) | 可见但不命中、整子树生效、描边热区 = `lineWidth`、`cursor` 随命中失效 | `noevent` 在 5 页出现,`layer-transform` 整节与 `events.md` 整节重复 | 权威 = `events.md`。`layer-transform` 删除整节;`ui-performance` 保留性能视角一句;示例页保留各 1–2 行用法 |
| UI 系统(GameUI/控制器/实例/栈) | 仅 UI 子分组 | 四层对象、栈、背景四名、策略、`keep`、`active`/`showBack`、场景 vs 主 UI | 权威 `ui-controller-and-stack.md`;重复:`ui-template.md` §三个基础 props/§打开与关闭、`inventory-example-1` §打开、`inventory-example-6` §注册与打开、`replace-builtin-ui.md` 第 9–16 行 | 保留 `ui-controller` 全篇;`ui-template` 只留「三个 props 必须列全」与三入口一行;示例页各保留 3–5 行;「`GameUI` 名字不参与查找」只留一处(建议 `ui-controller` 或 `ui-template`),其余链接 |
| 图片 / 纹理 | 仅 UI 子分组;`loading-system.md` 只有渲染端素材一句话 | 纹理 = 可绘制图像源、`Texture` 构造、素材管理器、像素图清晰度、图片作为零件 | 权威 `image-and-texture.md`;`ui-performance.md` §纹理与文字(第 138–147 行)与其重复约三成 | `ui-performance` 保留「开销与释放时机」角度,删除「怎么建纹理」的复述 |
| 按键 / 快捷键 | 仅 UI 子分组 | 两条路径、指令/作用域/实现、`useKey`/`implement`、`HotkeyEmitMode`、优先级、栈关系、默认键 | 权威 `hotkey-in-ui.md`;`events.md` 与之仅概念对照 | 保留;把「按键不是元素事件」压缩为 3–5 行并链接 `events.md` |
| 替换内置 UI | 仅 UI 子分组 | 入口替换 vs 包装层、每类界面必须保留的语义 | 权威 `replace-builtin-ui.md`;`ui-template`/`inventory-6` 重复「`GameUI` 不参与查找」 | 保留;删除 `ui-template:151`、`inventory-6:222` 的重复段落,改为链接 |
| 术语(`loc`/锚点/props/attrs/slot/`state`) | `container-and-coordinates.md` §loc 与锚点;`props.md`;`slots-and-attrs.md` | `loc` 六元组、`anc`、默认 200×200、props 管线、attrs 透传 | `ui-template.md` 第 71–77 行复述 `loc` 与三种元素;`component-tsx` 复述 props 泛型;`basic-shapes`/`text` 复述「TSX 内置注册 vs 元素层 import」 | `loc` 权威在 `container`;`ui-template` 只留一句;「TSX 标签无需 import、元素层需要」只在 `ui-template` 说明一次,其余页面不再解释 |
## 明确不应写进 UI 教程的内容(含依据)
| 内容 | 出现位置 | 依据(已有覆盖) | 处理建议 |
| --- | --- | --- | --- |
| `pnpm install` / `pnpm dev` / `pnpm docs:dev` 的操作步骤 | `ui-template.md:43`、`inventory-example-1-skeleton.md:47` | `dev.md` §开发说明已给安装与开发命令;`dev.md` §构建说明给构建/lint 命令。工程命令属项目级信息,与「怎么写 UI」无关 | 删除,改为「环境准备见 dev.md」 |
| `@motajs/*`、`@user/*` 的路径映射与三层依赖解释 | `ui-template.md:43` | `src-tour.md` §包从哪来(第 7–15 行)已讲清三层、包名与单向依赖;`dev.md` §项目结构同义 | 删除路径映射;保留「本篇用到哪几个包、各提供什么」的 UI 相关映射 |
| 「渲染端尚未完工/高级 I 只写数据端」的历史叙述 | 非 UI 文档(`i/index.md:15`);UI 文档已按完工口径写 | 与 UI 现状不一致,且属层级导览信息 | 不写进 UI;若需提示范围,以 `ii/index.md` 的 UI 子分组说明为准 |
| 数据端插件三时机、依赖拓扑、注册表错误码 | 无 UI 重复;`ui-template.md:41` 仅提包名 | `plugin-system.md` §生命周期/§状态与顺序、`plugin-internals.md` 全篇 | 不写进 UI;需要时一句链接 |
| 加载阶段、`getConfig`、`addCustomContent` 的用法 | `image-and-texture.md` 未展开(仅第 117 行声明不展开) | `loading-system.md` 全篇 | 保持「不展开」;只链接 |
| Store 的运行期只读规则与错误码 | 无 | `data-stores.md` §为什么运行期只读 | 不写进 UI |
| 数据端事件触发器、收集顺序、事件 id 注册 | 无 | `event-system.md`、`point-and-tile-events.md` | 不写进 UI;`events.md`(UI)已用「元素事件」区分 |
| 存档 `saveState`/`loadState` 约束、录像一致性 | 无 | `saveable-content.md`、`replay-consistency.md` | 不写进 UI;「UI 不参与录像」一句即可 |
| 引擎级渲染管线、批处理、帧预算 | `ui-performance.md:3` 已声明不覆盖 | `advanced/index.md:39`、`iii/index.md:90–96` | 保持现有边界声明 |
| 编辑器 / 素材配置的制作流程 | `image-and-texture.md:117` 已声明不展开 | `ii/index.md:81`、`adding-hero-attribute.md:15` 均把编辑器归到对应端 | 保持;素材只讲「怎么取、怎么用」 |
| 地图图层 `zIndex` 与图块绘制 | 无 UI 重复 | `map-structure.md:52–53` | 不写进 UI;UI 的 `zIndex` 只讲渲染树兄弟 |
| 通用 TS/JS 语法与「示例省略 import」约定 | 无 UI 重复(UI 示例均带 import) | `code-basics.md` §照抄教程里的代码时 | 不写进 UI;UI 示例已自包含 import,符合其自身需要 |
## UI 层必须保留的内容(引擎层没讲、或 UI 特有)
| 必须保留 | 理由(覆盖缺口) |
| --- | --- |
| 渲染树三层:画布根 → UI 容器 → 面板根;组件树 vs 元素树 | `advanced/iii/index.md:90–96` 明确不覆盖渲染端结构;`data-vs-render.md` 只讲双端分工。这是全站唯一出处 |
| `loc` 六元组、`anc`、锚点、默认 200×200、局部坐标系与变换复合 | 无其它文档覆盖;且是 UI 报错高发点 |
| `zIndex` 仅同父级比较、父级带整棵子树参与排序、绘制与命中顺序相反 | 数据端 `zIndex`(`map-structure.md`)是图层纵深,语义不同,不能替代 |
| 命中测试规则、`hidden`/`noevent`/`actionStroke`/`cursor` 的行为差异 | 引擎层文档不涉及画布命中 |
| 捕获/冒泡、`stopPropagation` 边界、`enter`/`leave` 的悬停集合差、事件对象字段与 `offset` vs `absolute` | 数据端事件系统是脚本触发模型,与指针事件无关 |
| 缓存机制(默认缓存标签、`nocache` 优先级、脏标记上冒、`custom` 需手动触发)与性能取舍 | 仅 UI 子分组;`advanced/iii` 只讲引擎级性能 |
| TSX + Vue 在画布上的用法:`ref/reactive/computed/watch/nextTick`、`shallowRef`/`markRaw`、模板指令不适用、`v-model:xxx` 的写法 | `code-basics.md` 只讲 TS 语法,不含 Vue |
| 组件结构:`defineComponent` 泛型、`SetupComponentOptions`、`emits`/`expose`、生命周期与清理边界 | UI 特有框架约定 |
| props 管线(父属性 → VNode props → `props` 数组 → setup;未声明进 `attrs`)、默认值写法、`props` 不解构 | UI 特有;`attrs` 透传是框架行为 |
| slot(函数而非标签、具名对象形式、作用域 slot 类型)与 `inheritAttrs` | UI 特有 |
| `GameUI`/`UIController`/`UIInstance`/`UIContainer` 四层、栈与 `i*5`、背景四名、`keep`、`active`/`showBack`、`lastOnly`/`showAll`/自定义策略、场景 vs 主 UI | 全站唯一出处;`plugin-system.md` 只讲插件,不涉及 UI 栈 |
| `setPropsBaseCreator` / `createPropsBase` 与 `state` 的 `markRaw` | UI 特有注入链 |
| 内置组件:`List`/`ListPage`/`Page`/`Scroll`/`Selection`/`ConfirmBox`/`Choices`/`InputBox`、`TextContent`/`Textbox`/`Input` | 全站唯一出处 |
| 图片与纹理:`Texture` 构造、素材管理器 `getImageByAlias`/`getImage`、`noanti`/`hd`/整数倍缩放 | 全站唯一出处;`loading-system.md` 只说明渲染端可追加素材 |
| 按键作用域:`useKey`/`implement`/`registerCommand`/`HotkeyEmitMode`/优先级与栈关系/默认键 | 全站唯一出处;`hotkey-in-ui.md:243–245` 已说明无 live 示例 |
| 替换内置 UI 的两个替换点与「必须保留的结果语义」 | 全站唯一出处 |
| UI 性能六层定位、`Scroll` 平铺约束、观测流程 | UI 特有;与引擎级性能边界已在 `ui-performance.md:3` 划清 |
## mermaid 图位置表
**现状**:25 篇 UI 文档中 **0 个 mermaid 图**(已检索 `` ```mermaid ``,全站 11 处均在非 UI 文档)。UI 文档现有 **12 处 `` ```text `` 树/流程块**,是最该替换为 mermaid 的位置。
**既有风格参照**(保持一致):`data-vs-render.md:17–23`(`graph LR`)、`combat-overview.md:65–74`(`graph TD` + 决策边标签)、`pathfinding.md:29–34`(`flowchart LR`)、`enemy-context-and-combat.md:61–69`(`graph TD`)、`iii/event-system.md:17–26`(`flowchart TD` + `{决策}` + `<br/>`)、`iii/loading-system.md:21–27、96–103`(`flowchart TD`)、`iii/plugin-internals.md:17–25`、`iii/core-state.md:16–21`、`iii/replay-internals.md:19–31`、`iii/passability-and-pathfinding.md:18–30`。
| UI 页面 | 小节 | 建议图类型 | 图要回答的问题 |
| --- | --- | --- | --- |
| `ui-template.md` | §这份模板在渲染树里的位置(现 `` ```text ``,第 87–93 行) | `flowchart TD` | 一个面板从画布根到 `g-rect`/`text` 到底挂在哪几层;哪层由控制器创建、哪层由作者写 |
| `ui-template.md` | §事件从哪里进入(第 105–111 行) | `flowchart TD` 或删除改链接 | 一次点击从画布根到面板内的路径;与 `events.md` 重复时以链接替代 |
| `container-and-coordinates.md` | §渲染树:根、容器与子元素(现 `` ```text ``,第 15–24 行) | `flowchart TD` | 容器三个职责(坐标系/捕获单位/缓存边界)分别落在树的哪个位置 |
| `container-and-coordinates.md` | §坐标与变换如何沿树传递(第 38–54 行) | `flowchart LR` | 父级平移/缩放/旋转如何复合到子级坐标;锚点在其中的位置 |
| `container-and-coordinates.md` | §事件在嵌套容器中的路径(第 56–68 行) | `sequenceDiagram` | 命中 → 捕获(根→子)→ 冒泡(子→根)的参与者顺序;`stopPropagation` 截断点 |
| `events.md` | §命中测试(第 5–24 行) | `flowchart TD` + 决策节点 | 指针落点如何逐层筛到最上层元素;`zIndex`/插入顺序/`hidden`/`noevent` 在哪一步生效 |
| `events.md` | §捕获与冒泡(第 44–51 行,三层例子) | `sequenceDiagram` | 根捕获→面板捕获→按钮捕获→按钮冒泡→面板冒泡→根冒泡的完整时序 |
| `events.md` | §enter 与 leave 不走普通冒泡(第 153–166 行) | `flowchart TD` | 悬停集合如何生成、比较、差集触发 `leave`/`enter`;为何父级不闪 |
| `events.md` | §事件对象 / §事件坐标与变换(第 168–242 行) | `flowchart LR` | 画布坐标 `absoluteX` 如何逆变换成各层 `offsetX`;为何父子数值不同 |
| `layer-transform-performance.md` | §渲染树、层级与绘制顺序(第 5–18 行) | `flowchart LR` | 绘制顺序(小→大)与命中顺序(大→小)为何相反;同值时的插入顺序 |
| `layer-transform-performance.md` | §缓存与脏更新(第 118–147 行) | `flowchart TD` | 属性变化 → 标脏 → 沿父链上冒 → 父缓存重画;`custom` 手动触发在哪一步 |
| `ui-controller-and-stack.md` | §控制器、实例与栈(第 5–42 行) | `classDiagram` | `GameUI`/`UIController`/`UIInstance`/`UIContainer` 的持有与创建关系 |
| `ui-controller-and-stack.md` | §背景的四个名字(第 82–109 行) | `flowchart LR` | 用户设置(`showBackground`/`hideBackground`)与系统需求如何合成为 `showBack` |
| `ui-controller-and-stack.md` | §栈策略(第 111–177 行) | `stateDiagram-v2` | `open`/`close`/`hide`/`show` 在 `lastOnly` 与 `showAll` 下如何改变实例可见状态 |
| `ui-controller-and-stack.md` | §打开与关闭的完整例子(第 242–303 行) | `sequenceDiagram` | 工具栏 → 设置面板 → 确认框 → 逐层关闭的调用顺序与栈变化 |
| `component-tsx.md` | §组件如何映射成一棵子树(第 5–40 行) | `flowchart TD` | 组件树(Panel→Badge)与元素树(container 嵌套)的对应关系;组件边界为何不可见 |
| `component-tsx.md` | §生命周期与渲染树(第 211–218 行) | `stateDiagram-v2` | `setup` → 挂载 → 更新(patch)→ 卸载的迁移;哪些操作会触发卸载 |
| `reactivity.md` | §数据变化如何走到渲染树(第 7–19 行) | `flowchart LR` | 数据(ref/reactive)→ 组件重渲染 → VNode diff → 元素属性 → 绘制,五步各自粒度 |
| `reactivity.md` | §什么时候会重渲染、什么时候不会(第 168–186 行) | `flowchart TD` + 决策节点 | 一次数据变化是否会触发重渲染(是否被渲染函数读过、是否响应式、是否 `shallowRef`) |
| `props.md` | §props 的完整管线(第 7–18 行) | `flowchart LR` | 父组件属性 → VNode props → `props` 数组筛选 → setup;未声明键分流到 `attrs` |
| `slots-and-attrs.md` | §slots/attrs 与渲染树(第 254–342 行) | `flowchart TD` | slot 内容插入到子组件哪个位置;`attrs` 透传到根元素还是被 `inheritAttrs` 截断 |
| `conditional-and-list-rendering.md` | §条件/列表的树形示意(第 221–309 行) | `flowchart TD` | 同一棵树上 `hidden`、三元、`map`+`key` 三种更新的差异落点 |
| `basic-shapes.md` | §填充、描边与命中(第 98–166 行) | `flowchart TD` + 决策节点 | `fill`/`stroke`/`strokeAndFill` 各自命中哪里;`actionStroke` 如何收窄到描边 |
| `curves-and-paths.md` | §路径在渲染树与命中中的位置(第 104–117 行) | `flowchart LR` | 路径如何按几何命中;为何宽高不裁剪路径;`actionStroke` 的效果 |
| `text.md` | §尺寸与测量(第 98–129 行) | `flowchart LR` | 内容/字体/描边宽度如何决定测量尺寸,测量尺寸如何成为命中矩形 |
| `image-and-texture.md` | §纹理从哪里来(第 21–119 行) | `flowchart LR` | 图像源(canvas/ImageBitmap/HTMLImageElement)→ `Texture` → `image` 元素 → 拉伸绘制 |
| `image-and-texture.md` | §像素图与高清缓存(第 121–138 行) | `flowchart TD` + 决策节点 | `noanti`/`anti`/`hd`/`cache` 四开关谁能真正改善像素图;为何 `image` 默认不缓存时 `hd={false}` 无效 |
| `builtin-list-and-containers.md` | §组合示例与树形解释(第 345–431 行) | `flowchart TD` | `ListPage` → `List` → `Scroll` → 行、`Page` → 内容/页码条、弹窗另起树,三者归属 |
| `builtin-list-and-containers.md` | §列表、滚动、分页、弹窗各自解决什么(第 7–20 行) | `flowchart TD` + 决策节点 | 按需求(选一个/左右详情/超视口/翻页/弹一次)该选哪个组件 |
| `builtin-text-and-input.md` | §输入组件的受控边界(第 232–332 行) | `stateDiagram-v2` | `Input` 的值副本、覆盖输入框、失焦、确认/取消的状态迁移 |
| `replace-builtin-ui.md` | §替换的是入口,不是实现(第 7–36 行) | `flowchart LR` | 打开处替换与包装层替换两条路径;哪些调用方会被一起换掉 |
| `replace-builtin-ui.md` | §替换步骤(第 55–142 行) | `flowchart TD` | 找打开点 → 新建 UI → 保留 props/语义 → 验证的顺序与回退点 |
| `hotkey-in-ui.md` | §按键与元素事件是两条路径(第 7–16 行) | `flowchart LR` | 指针事件(命中→捕获→冒泡)与键盘事件(匹配指令→作用域)如何分流 |
| `hotkey-in-ui.md` | §按键与 UI 栈的关系(第 214–225 行) | `stateDiagram-v2` | 面板 A 打开 → B 打开(B 在栈顶)→ B 关闭 → A 恢复的按键归属变化 |
| `inventory-example-1-skeleton.md` | §骨架在渲染树里的位置(现 `` ```text ``,第 23–33 行) | `flowchart TD` | 720×480 面板里五个区域各挂在哪一层、谁是兄弟 |
| `inventory-example-1-skeleton.md` | §打开、状态与关闭归谁(第 69–90 行) | `flowchart LR` | `open` 产生实例、`props.instance` 回到控制器、状态归面板的归属关系 |
| `inventory-example-2-grid.md` | §从占位到网格(现 `` ```text ``,第 9–16 行) | `flowchart TD` | 左侧区域 → `ItemGrid` → `ItemCell` 的层级与坐标相对谁 |
| `inventory-example-2-grid.md` | §点击如何上报(现 `` ```text ``,第 255–261 行) | `sequenceDiagram` | `ItemCell` → `ItemGrid` → `InventoryPanel` 的 emit 链与重渲染 |
| `inventory-example-3-detail.md` | §详情区的树结构(现 `` ```text ``,第 29–40 行) | `flowchart TD` | 详情根内四块(标题/未选中提示/内容/取消按钮)与两个 `hidden` 分支 |
| `inventory-example-3-detail.md` | §选中态与两个隐藏分支(现 `` ```text ``,第 147–152 行) | `stateDiagram-v2` | 「未选中 ↔ 已选中」两态及各自可见子树 |
| `inventory-example-4-scroll.md` | §Scroll 在渲染树里的位置(现 `` ```text ``,第 25–36 行) | `flowchart TD` | 视口、行容器、两个按钮的位置关系;为何行必须是 `Scroll` 直接子元素 |
| `inventory-example-4-scroll.md` | §数据与选中态如何穿过滚动层(第 46–110 行) | `flowchart LR` | `items`/`selectedId` 从面板到 `ItemGrid` 到 `ItemCell` 的传递,`Scroll` 为何不持有数据 |
| `inventory-example-5-state.md` | §操作条的树与事件流(现 `` ```text ``,第 21–28 行) | `flowchart TD` + `sequenceDiagram` | `ActionBar` 三个按钮的树位置;按钮 → `ActionBar` → 面板的事件方向 |
| `inventory-example-5-state.md` | §状态变化如何反映到画面(现 `` ```text ``,第 168–174 行) | `flowchart LR` | 装备/使用/提示三条状态链各自改到树上哪一处 |
| `inventory-example-5-state.md` | §关闭的完整路径(现 `` ```text ``,第 184–192 行) | `flowchart TD` | 三个关闭入口如何汇到 `controller.close(instance)` 并卸载子树 |
| `inventory-example-6-animation-and-register.md` | §注册与打开(第 194–224 行) | `sequenceDiagram` | `GameUI` 对象 → `open` → 实例 → `close` 的调用链;`keep` 在切换中的位置 |
| `inventory-example-6-animation-and-register.md` | §最后一步要收什么(现 `` ```text ``,第 9–18 行) | 保留 `` ```text `` | 这是目录树,不是数据流;mermaid 反而更差,建议不替换 |
**结论**:D-95 落地时,至少覆盖以下 8 个「主图」:渲染树(`container-and-coordinates`)、命中规则(`events`)、捕获/冒泡时序(`events`)、缓存脏更新(`layer-transform-performance`)、UI 栈与实例关系(`ui-controller-and-stack`)、组件↔元素映射(`component-tsx`)、响应式五步(`reactivity`)、props 管线(`props`)。其余为按页补的局部图。
## 待确认项(只列问题,不下结论)
1. `pnpm docs:dev` 在 `dev.md` 中不存在(`dev.md` 只有 `pnpm i`、`pnpm dev` 与构建/lint 命令)。它是否是真实存在的脚本?若存在,命令说明的唯一归属应是 `dev.md` 还是保留在 `ui-template.md`?(本次未读 `package.json`,无法确认)
2. `ui-template.md:43` 写的别名映射(`@motajs/*` → `packages/*/src`、`@user/*` → `packages-user/*/src`)在 `src-tour.md` 与 `dev.md` 中都没有逐字出现;这属于构建配置细节。它应归入 `dev.md`、归入 `src-tour.md`,还是允许 UI 首篇保留一行?
3. `inventory-example-1-skeleton.md:47` 交叉引用「第 1 篇「工程与命令」」,但 `ui-template.md` 没有名为「工程与命令」的小节(命令只出现在第 43 行的段落里)。是补小节名,还是删除该引用?
4. UI 文档的 `state` 指 `IClientCore`(如 `props.state.mainUIController`),数据端文档的 `state` 指 `ICoreState`。是否需要在 UI 首篇显式声明这一同名不同义,或统一改称(如 `clientState`)?
5. `dev.md:138–143` 说渲染端分 `@user/client-base`(系统层)与 `@user/client-modules`(实现层);UI 文档示例还使用 `@motajs/system`、`@motajs/render-vue`、`@motajs/render`。哪些包属于作者应直接依赖的稳定 API,哪些只应在内部出现?教程是否应统一 import 来源?
6. 「`GameUI` 的名字不参与查找、打开/关闭/栈比较都用对象或实例」在 `ui-template.md:151`、`ui-controller-and-stack.md:333`、`inventory-example-6:222`、`replace-builtin-ui.md:16` 四处出现。应保留在哪一篇作为唯一权威?
7. `image-and-texture.md` §加载一张 PNG 示范手动 `new Image` + `onload`,同一篇第 117 行又说「素材由编辑器维护,正文只负责使用已登记素材」;`loading-system.md:283` 又说渲染端可复用加载器追加贴图。教程是否允许示范手动加载?还是只保留素材管理器路径、手动加载降为脚注?
8. 渲染树/元素树目前分散在 `ui-template`、`container-and-coordinates`、`component-tsx`、`inventory-example-1` 四处。是否把 `container-and-coordinates.md` 定为唯一权威(其余链接),还是在 UI 子分组内单列一篇「渲染树」?(本次不新增/删除页面,仅提问)
9. D-95 的 mermaid 是否要求「凡 `` ```text `` 树/流程块一律替换」?目录树(`inventory-example-6` 第 9–18 行)与纯坐标清单是否属于例外?
10. `layer-transform-performance.md`(第 72–147 行)与 `ui-performance.md`(第 22–97 行)的 `hidden`/缓存内容大面积重合,且两处「四种情况」列表几乎逐字相同。是合并到机制篇(`layer-transform`)+ 策略篇(`ui-performance`)各留一半,还是保留双份但互相链接?
## 声明
未读源码:是(未读任何 `.ts/.tsx/.vue/.json`、`packages*/`、`src/`;仅读 Markdown)
未修改任何文档:是(本文件之外未写入 `docs/`,未运行 `docs:dev`,未 commit)
@@ -0,0 +1,53 @@
import { defineComponent } from 'vue';
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<container loc={[8, 8, 228, 148]}>
<g-rect
loc={[110, 70, 100, 60, 0, 0]}
fillStyle="#2f6fed"
alpha={0.6}
/>
<g-circle circle={[110, 70, 6]} fillStyle="#e8f0ff" />
<text loc={[8, 122]} text="锚点 0, 0" fillStyle="#cfe0ff" />
</container>
<container loc={[244, 8, 228, 148]}>
<g-rect
loc={[110, 70, 100, 60, 0.5, 0.5]}
fillStyle="#f2b84b"
alpha={0.6}
/>
<g-circle circle={[110, 70, 6]} fillStyle="#ffe9b0" />
<text loc={[8, 122]} text="锚点 0.5, 0.5" fillStyle="#ffe9b0" />
</container>
<container loc={[8, 164, 228, 148]}>
<g-rect
loc={[110, 70, 100, 60, 1, 1]}
fillStyle="#58c4dd"
alpha={0.6}
/>
<g-circle circle={[110, 70, 6]} fillStyle="#e8f0ff" />
<text loc={[8, 122]} text="锚点 1, 1" fillStyle="#cfe0ff" />
</container>
<container loc={[244, 164, 228, 148]}>
<g-rect
loc={[110, 70, 160, 100, 0.5, 0.5]}
fillStyle="#c58af9"
alpha={0.5}
/>
<g-circle circle={[110, 70, 6]} fillStyle="#f3e8ff" />
<text
loc={[8, 122]}
text="中心锚点,尺寸更大"
fillStyle="#f3e8ff"
/>
</container>
</container>
);
});
@@ -0,0 +1,13 @@
import { defineComponent } from 'vue';
// UI 入门演示:一个 480×320 的容器,里面放一行文字和一个矩形
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
{/* 一行文字 */}
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
{/* 一个矩形 */}
<g-rect loc={[24, 64, 160, 80]} fill fillStyle="#2f6fed" />
</container>
);
});
@@ -0,0 +1,20 @@
import { defineComponent } from 'vue';
import { Arrow } from '../../../../../packages-user/client-base/src/components/misc';
// 箭头:三条箭头分别改 head 与 color
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<Arrow arrow={[48, 48, 300, 48]} head={8} color="#f2b84b" />
<text loc={[48, 80]} text="head = 8" fillStyle="#cfe0ff" />
<Arrow arrow={[48, 136, 300, 136]} head={18} color="#7ee787" />
<text loc={[48, 168]} text="head = 18" fillStyle="#cfe0ff" />
<Arrow arrow={[48, 224, 300, 224]} head={30} color="#7aa2ff" />
<text loc={[48, 256]} text="head = 30" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,33 @@
import { defineComponent } from 'vue';
import { Background } from '../../../../../packages-user/client-base/src/components/background';
// 背景:同一个组件换两组 color 与 border
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<container loc={[40, 48, 180, 150]}>
<Background
loc={[0, 0, 180, 150]}
color="#1d2b45"
border="#3a5a8c"
/>
<text
loc={[16, 16]}
text="color + border"
fillStyle="#e8f0ff"
/>
</container>
<container loc={[260, 48, 180, 150]}>
<Background
loc={[0, 0, 180, 150]}
color="#2a2140"
border="#c9a7ff"
/>
<text loc={[16, 16]} text="换一组颜色" fillStyle="#e8f0ff" />
</container>
</container>
);
});
@@ -0,0 +1,52 @@
import { defineComponent } from 'vue';
import {
PlayIcon,
PauseIcon,
RollbackIcon,
RetweetIcon,
SoundVolume,
Fullscreen,
DoubleArrow,
StepForward,
ArrowLeftTailless
} from '../../../../../packages-user/client-base/src/components/icons';
// 图标组件:每个图标都只接受 loc,按名字使用
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<PlayIcon loc={[56, 36, 32, 32]} />
<text loc={[56, 80]} text="PlayIcon" fillStyle="#cfe0ff" />
<PauseIcon loc={[196, 36, 32, 32]} />
<text loc={[196, 80]} text="PauseIcon" fillStyle="#cfe0ff" />
<RollbackIcon loc={[336, 36, 32, 32]} />
<text loc={[336, 80]} text="RollbackIcon" fillStyle="#cfe0ff" />
<RetweetIcon loc={[56, 128, 32, 32]} />
<text loc={[56, 172]} text="RetweetIcon" fillStyle="#cfe0ff" />
<SoundVolume loc={[196, 128, 32, 32]} />
<text loc={[196, 172]} text="SoundVolume" fillStyle="#cfe0ff" />
<Fullscreen loc={[336, 128, 32, 32]} />
<text loc={[336, 172]} text="Fullscreen" fillStyle="#cfe0ff" />
<DoubleArrow loc={[56, 220, 32, 32]} />
<text loc={[56, 264]} text="DoubleArrow" fillStyle="#cfe0ff" />
<ArrowLeftTailless loc={[196, 220, 32, 32]} />
<text
loc={[196, 264]}
text="ArrowLeftTailless"
fillStyle="#cfe0ff"
/>
<StepForward loc={[336, 220, 32, 32]} />
<text loc={[336, 264]} text="StepForward" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,33 @@
import { defineComponent, ref } from 'vue';
import { Input } from '../../../../../packages-user/client-base/src/components/input';
// 输入框:单行占位、单行已填内容与多行输入
export default defineComponent(() => {
const name = ref('');
const filled = ref('魔塔玩家');
const note = ref('第一行备注\n第二行备注');
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[40, 24]} text="单行" fillStyle="#cfe0ff" />
<Input
loc={[40, 48, 280, 32]}
v-model:value={name.value}
placeholder="输入名字"
/>
<text loc={[40, 96]} text="已填内容" fillStyle="#cfe0ff" />
<Input loc={[40, 120, 280, 32]} v-model:value={filled.value} />
<text loc={[40, 168]} text="多行" fillStyle="#cfe0ff" />
<Input
loc={[40, 192, 320, 88]}
v-model:value={note.value}
multiline
placeholder="多行备注"
/>
</container>
);
});
@@ -0,0 +1,30 @@
import { defineComponent, ref } from 'vue';
import { List } from '../../../../../packages-user/client-base/src/components/list';
const ITEMS: [string, string][] = [
['basic', '基础设置'],
['sound', '声音'],
['key', '按键'],
['about', '关于']
];
// 列表:四项由 list 渲染,选中项显示闪烁光标
export default defineComponent(() => {
const selected = ref(ITEMS[0][0]);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<List
loc={[40, 40, 300, 160]}
list={ITEMS}
lineHeight={32}
color="#2b4a6f"
border="#6fa8ff"
alphaRange={[0.6, 0.9]}
v-model:selected={selected.value}
/>
</container>
);
});
@@ -0,0 +1,38 @@
import { defineComponent, ref } from 'vue';
import { ListPage } from '../../../../../packages-user/client-base/src/components/list';
const ITEMS: [string, string][] = [
['basic', '基础设置'],
['sound', '声音'],
['key', '按键']
];
const DETAIL: Record<string, string> = {
basic: '这里放基础设置的说明。',
sound: '这里放音量与音效的说明。',
key: '这里放按键改绑的说明。'
};
// 左列表、右详情:选中项高亮,右侧显示对应内容
export default defineComponent(() => {
const selected = ref(ITEMS[0][0]);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<ListPage
loc={[40, 40, 400, 240]}
list={ITEMS}
v-model:selected={selected.value}
>
{(key: string) => (
<text
loc={[16, 16]}
text={DETAIL[key] ?? '没有内容'}
fillStyle="#e8f0ff"
/>
)}
</ListPage>
</container>
);
});
@@ -0,0 +1,25 @@
import { defineComponent, ref } from 'vue';
import { Page } from '../../../../../packages-user/client-base/src/components/page';
const PAGES = ['第一页:基础设置', '第二页:声音', '第三页:按键'];
// 分页:三页内容共用一个 loc,页码条在底部
export default defineComponent(() => {
const page = ref(0);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<Page pages={3} v-model:page={page.value} loc={[90, 48, 300, 200]}>
{(index: number) => (
<text
loc={[16, 16]}
text={PAGES[index] ?? ''}
fillStyle="#e8f0ff"
/>
)}
</Page>
</container>
);
});
@@ -0,0 +1,34 @@
import { defineComponent } from 'vue';
import { Progress } from '../../../../../packages-user/client-base/src/components/misc';
// 进度条:progress 分别取 0.3、0.6 与 1
const BARS = [
{ label: 'progress = 0.3', y: 68, progress: 0.3 },
{ label: 'progress = 0.6', y: 128, progress: 0.6 },
{ label: 'progress = 1', y: 188, progress: 1 }
];
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
{BARS.map(bar => (
<container key={bar.label} loc={[0, 0, 480, 320]}>
<text
loc={[48, bar.y - 24]}
text={bar.label}
fillStyle="#cfe0ff"
/>
<Progress
loc={[48, bar.y, 300, 10]}
progress={bar.progress}
success="#7ee787"
background="#26364d"
lineWidth={8}
/>
</container>
))}
</container>
);
});
@@ -0,0 +1,32 @@
import { defineComponent } from 'vue';
import { Scroll } from '../../../../../packages-user/client-base/src/components/scroll';
const ROWS = Array.from({ length: 12 }, (_, index) => `第 ${index + 1} 行`);
// 滚动区域:直接子元素从上往下排,右侧是滚动条
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[40, 24]}
text="直接子元素依次排列"
fillStyle="#cfe0ff"
/>
<g-rect loc={[40, 52, 300, 220]} fillStyle="#101820" />
<Scroll loc={[40, 52, 300, 220]}>
{ROWS.map((row, index) => (
<container key={row} loc={[8, 6 + index * 30, 280, 28]}>
<g-rect
loc={[0, 0, 280, 28]}
fillStyle={index % 2 === 0 ? '#26364d' : '#1d2b45'}
/>
<text loc={[10, 6]} text={row} fillStyle="#e8f0ff" />
</container>
))}
</Scroll>
</container>
);
});
@@ -0,0 +1,51 @@
import { defineComponent, onUnmounted, ref } from 'vue';
import {
ScrollText,
ScrollTextExpose
} from '../../../../../packages-user/client-base/src/components/misc';
const NOTICE = [
'公告:今晚八点维护',
'提示:记得保存进度',
'活动:新地图开放',
'注意:离开前先存档'
]
.join('\n')
.repeat(3);
// 滚动文字:内容在固定视口里向上滚动,超出视口的部分不显示
export default defineComponent(() => {
const scroll = ref<ScrollTextExpose>();
let timer: ReturnType<typeof setTimeout> | undefined;
const restart = () => {
// 组件触发 scrollEnd 后会立刻暂停,等一小段可见停顿后再恢复
timer = setTimeout(() => {
timer = undefined;
scroll.value?.rescroll();
scroll.value?.resume();
}, 1000);
};
onUnmounted(() => {
if (timer !== undefined) clearTimeout(timer);
});
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[40, 32]} text="公告" fillStyle="#cfe0ff" />
<ScrollText
ref={scroll}
loc={[40, 60, 400, 160]}
width={400}
speed={80}
text={NOTICE}
fillStyle="#7ee787"
onScrollEnd={restart}
/>
</container>
);
});
@@ -0,0 +1,38 @@
import { defineComponent } from 'vue';
import { Selection } from '../../../../../packages-user/client-base/src/components/misc';
// 选中框:两组 color 与 border,第二组调大 alphaRange
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<container loc={[40, 48, 240, 32]}>
<Selection
loc={[0, 0, 240, 32]}
color="#2f6fed"
border="#7aa2ff"
/>
<text loc={[12, 8]} text="被选中的项" fillStyle="#ffffff" />
</container>
<container loc={[40, 96, 240, 32]}>
<Selection
loc={[0, 0, 240, 32]}
color="#8a6a1f"
border="#f2b84b"
alphaRange={[0.4, 0.8]}
/>
<text
loc={[12, 8]}
text="alphaRange = [0.4, 0.8]"
fillStyle="#ffffff"
/>
</container>
<container loc={[40, 144, 240, 32]}>
<text loc={[12, 8]} text="没有选中框的项" fillStyle="#e8f0ff" />
</container>
</container>
);
});
@@ -0,0 +1,60 @@
import { defineComponent, ref } from 'vue';
import { Slider } from '../../../../../packages-user/client-base/src/components/slider';
// 滑动条:右侧显示当前值,旁边配两个按钮增减数值
export default defineComponent(() => {
const volume = ref(40);
const decrease = () => {
volume.value = Math.max(0, volume.value - 5);
};
const increase = () => {
volume.value = Math.min(100, volume.value + 5);
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[44, 48]} text="音量" fillStyle="#cfe0ff" />
<container loc={[44, 76, 196, 24]}>
<Slider
loc={[0, 0, 196, 24]}
v-model:value={volume.value}
min={0}
max={100}
step={5}
showValue
/>
</container>
<container loc={[44, 124, 64, 28]} onClick={decrease}>
<g-rectr
loc={[0, 0, 64, 28]}
circle={[4]}
fillStyle="#2f6fed"
/>
<text
loc={[32, 14]}
anc={[0.5, 0.5]}
text="-"
fillStyle="#ffffff"
/>
</container>
<container loc={[120, 124, 64, 28]} onClick={increase}>
<g-rectr
loc={[0, 0, 64, 28]}
circle={[4]}
fillStyle="#3a2f5f"
/>
<text
loc={[32, 14]}
anc={[0.5, 0.5]}
text="+"
fillStyle="#ffffff"
/>
</container>
</container>
);
});
@@ -0,0 +1,28 @@
import { defineComponent } from 'vue';
import { TextContent } from '../../../../../packages-user/client-base/src/components/textbox';
const TEXT =
'[c=#f2b84b][s=20]标题字号[/s][/c]\n' +
'[c=#7ee787]正文颜色,长句会按 width 折行,超出宽度的部分自动换到下一行[/c]\n' +
'[c=#8aa0b8][s=13]小字注释:[[[[ 和 ]]]] 显示为方括号[/s][/c]';
// 文本标记:颜色、字号、手动换行与方括号字面量,长句按 width 折行
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[40, 24]} text="文本标记" fillStyle="#cfe0ff" />
<g-rect loc={[40, 56, 400, 216]} fillStyle="#101820" />
<TextContent
loc={[60, 80]}
width={360}
autoHeight
lineHeight={8}
text={TEXT}
fillStyle="#e8f0ff"
/>
</container>
);
});
@@ -0,0 +1,45 @@
import { computed, defineComponent } from 'vue';
interface ItemCardProps {
position: [number, number];
label: string;
color?: string;
}
interface ItemCardOptions {
props: (keyof ItemCardProps)[];
}
const itemCardOptions: ItemCardOptions = {
props: ['position', 'label', 'color']
};
// 子组件:只按 props 决定卡片的位置、文字与颜色
const ItemCard = defineComponent<ItemCardProps>(props => {
// 没有传 color 时使用默认颜色
const color = computed(() => props.color ?? '#f2b84b');
return () => (
<container loc={props.position}>
<g-rect loc={[0, 0, 220, 64]} fillStyle={color.value} />
<text loc={[16, 22]} text={props.label} fillStyle="#ffffff" />
</container>
);
}, itemCardOptions);
// 父组件:同一个 ItemCard 声明一次,用三次,只改传入的 props
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[40, 24]}
text="同一个组件,不同的 props"
fillStyle="#cfe0ff"
/>
<ItemCard position={[40, 56]} label="卡片 A" color="#2f6fed" />
<ItemCard position={[40, 144]} label="卡片 B" color="#7ee787" />
<ItemCard position={[40, 232]} label="卡片 C" />
</container>
);
});
@@ -0,0 +1,53 @@
import { defineComponent, ref } from 'vue';
// hidden 只切换绘制与命中,面板实例和内部计数都保留
export default defineComponent(() => {
const open = ref(true);
const count = ref(0);
const togglePanel = () => {
open.value = !open.value;
};
const increaseCount = () => {
count.value++;
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<container loc={[40, 32, 180, 36]} onClick={togglePanel}>
<g-rect loc={[0, 0, 180, 36]} fill fillStyle="#2f6fed" />
<text
loc={[12, 10]}
text="隐藏 / 显示面板"
fillStyle="#e8f0ff"
/>
</container>
<container
loc={[40, 92, 240, 160]}
hidden={!open.value}
onClick={increaseCount}
>
<g-rect loc={[0, 0, 240, 160]} fill fillStyle="#26364d" />
<text
loc={[16, 16]}
text="点击面板内部 +1"
fillStyle="#e8f0ff"
/>
<text
loc={[16, 52]}
text={`面板内点击:${count.value}`}
fillStyle="#ffffff"
/>
<text
loc={[16, 96]}
text="隐藏后再显示,状态仍在"
fillStyle="#cfe0ff"
/>
</container>
</container>
);
});
@@ -0,0 +1,96 @@
import { defineComponent, ref } from 'vue';
interface Row {
id: number;
label: string;
}
interface StatefulRowProps {
label: string;
offsetY: number;
}
interface StatefulRowOptions {
props: (keyof StatefulRowProps)[];
}
const statefulRowOptions: StatefulRowOptions = {
props: ['label', 'offsetY']
};
// 每一行有自己的计数;重排后它跟着组件实例走
const StatefulRow = defineComponent<StatefulRowProps, {}, string>(props => {
const count = ref(0);
const increaseCount = () => {
count.value++;
};
return () => (
<container loc={[0, props.offsetY, 200, 36]} onClick={increaseCount}>
<g-rect loc={[0, 0, 200, 36]} fill fillStyle="#26364d" />
<text loc={[10, 10]} text={props.label} fillStyle="#ffffff" />
<text
loc={[104, 10]}
text={`点击 ${count.value}`}
fillStyle="#f2b84b"
/>
</container>
);
}, statefulRowOptions);
// key=id 的状态跟着项,key=index 的状态留在原位置
export default defineComponent(() => {
const rows = ref<Row[]>([
{ id: 1, label: '甲' },
{ id: 2, label: '乙' },
{ id: 3, label: '丙' }
]);
const rotateRows = () => {
const first = rows.value.shift();
if (first) {
rows.value.push(first);
}
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 16]}
text="点行内 +1,再点「轮换顺序」"
fillStyle="#cfe0ff"
/>
<text loc={[24, 52]} text="key = id" fillStyle="#58c4dd" />
<text loc={[256, 52]} text="key = index" fillStyle="#f2b84b" />
<container loc={[24, 84]}>
{rows.value.map((row, index) => (
<StatefulRow
key={row.id}
label={row.label}
offsetY={index * 42}
/>
))}
</container>
<container loc={[256, 84]}>
{rows.value.map((row, index) => (
<StatefulRow
key={index}
label={row.label}
offsetY={index * 42}
/>
))}
</container>
<container loc={[160, 260, 160, 36]} onClick={rotateRows}>
<g-rect loc={[0, 0, 160, 36]} fill fillStyle="#2f6fed" />
<text loc={[52, 10]} text="轮换顺序" fillStyle="#e8f0ff" />
</container>
</container>
);
});
@@ -0,0 +1,57 @@
import { defineComponent, ref } from 'vue';
// 面板自己的计数:组件被卸载后实例消失,再挂载时从 0 开始
const CounterPanel = defineComponent(() => {
const count = ref(0);
const increaseCount = () => {
count.value++;
};
return () => (
<container loc={[0, 0, 240, 160]} onClick={increaseCount}>
<g-rect loc={[0, 0, 240, 160]} fill fillStyle="#26364d" />
<text loc={[16, 16]} text="点击面板内部 +1" fillStyle="#e8f0ff" />
<text
loc={[16, 52]}
text={`面板内点击:${count.value}`}
fillStyle="#ffffff"
/>
<text
loc={[16, 96]}
text="重新显示后,计数归零"
fillStyle="#cfe0ff"
/>
</container>
);
});
// 三元切换:面板被卸载与重建
export default defineComponent(() => {
const open = ref(true);
const togglePanel = () => {
open.value = !open.value;
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<container loc={[40, 32, 180, 36]} onClick={togglePanel}>
<g-rect loc={[0, 0, 180, 36]} fill fillStyle="#2f6fed" />
<text
loc={[12, 10]}
text="隐藏 / 显示面板"
fillStyle="#e8f0ff"
/>
</container>
{open.value ? (
<container loc={[40, 92]}>
<CounterPanel />
</container>
) : null}
</container>
);
});
@@ -0,0 +1,70 @@
import type { CustomContainerRenderFn } from '@motajs/render';
import { defineComponent } from 'vue';
// 同一组 3 个子元素:左侧普通 container 原样绘制,右侧 container-custom 逐个设置递增模糊
const rows = [
{ fillStyle: '#2f6fed', textFillStyle: '#e8f0ff', label: '第一行' },
{ fillStyle: '#7aa7ff', textFillStyle: '#141a22', label: '第二行' },
{ fillStyle: '#f2b84b', textFillStyle: '#141a22', label: '第三行' }
];
export default defineComponent(() => {
// render 接管子元素绘制:按 index 给每个子元素设置递增的 blur,再逐个绘制
const render: CustomContainerRenderFn = (canvas, children, transform) => {
children.forEach((child, index) => {
if (child.hidden) return;
child.setFilter(`blur(${index * 2}px)`);
child.renderContent(canvas, transform);
});
};
// 两侧使用相同结构的三行内容
const renderRows = () =>
rows.map((row, index) => (
<container loc={[0, index * 52, 180, 44]}>
<g-rect loc={[0, 0, 180, 44]} fillStyle={row.fillStyle} />
<text
loc={[14, 12]}
text={row.label}
fillStyle={row.textFillStyle}
/>
</container>
));
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="<container-custom> 逐个设置递增 blur"
fillStyle="#cfe0ff"
/>
<g-rect loc={[40, 72, 180, 160]} fillStyle="#1d2430" />
<g-rect loc={[260, 72, 180, 160]} fillStyle="#1d2430" />
<text
loc={[40, 48]}
text="container:原样绘制"
fillStyle="#8b98a8"
/>
<container loc={[40, 72, 180, 160]}>{renderRows()}</container>
<text
loc={[260, 48]}
text="custom:递增 blur"
fillStyle="#8b98a8"
/>
<container-custom loc={[260, 72, 180, 160]} render={render}>
{renderRows()}
</container-custom>
<text
loc={[40, 272]}
text="同一组子元素:右侧按顺序设置 blur(0 / 2 / 4px)"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,33 @@
import { defineComponent } from 'vue';
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<container loc={[60, 50, 360, 220]}>
<g-rect
loc={[0, 0, 360, 220]}
fillStyle="#2f6fed"
alpha={0.22}
/>
<g-circle circle={[0, 0, 6]} fillStyle="#e8f0ff" />
<text loc={[16, 16]} text="父容器原点" fillStyle="#cfe0ff" />
<container loc={[80, 60, 200, 120]}>
<g-rect
loc={[0, 0, 200, 120]}
fillStyle="#f2b84b"
alpha={0.3}
/>
<g-circle circle={[0, 0, 6]} fillStyle="#ffe9b0" />
<text
loc={[16, 16]}
text="子容器原点"
fillStyle="#ffe9b0"
/>
</container>
</container>
</container>
);
});
@@ -0,0 +1,95 @@
import { computed, defineComponent, onUnmounted } from 'vue';
import {
GameUI,
IUIDefaultPropsBase,
IUIInstance,
UIController
} from '@motajs/system';
// 最小控制器:只注入 instance 与 controller,不依赖游戏状态
const controller = new UIController<IUIDefaultPropsBase>();
controller.setPropsBaseCreator((instance, ctrl) => ({
instance,
controller: ctrl
}));
// 被打开的 UI:固定在画布右侧,避免和按钮重叠
const DemoPanel = defineComponent(() => {
return () => (
<container loc={[220, 120, 220, 150]}>
<g-rect loc={[0, 0, 220, 150]} fill fillStyle="#1d2b45" />
<g-rect loc={[0, 0, 220, 150]} stroke strokeStyle="#7aa2ff" />
<text loc={[16, 24]} text="这是一个最小 UI" fillStyle="#e8f0ff" />
<text
loc={[16, 64]}
text="由 UIController 打开"
fillStyle="#8fb6ff"
/>
</container>
);
});
const demoUI = new GameUI('controller-demo-panel', DemoPanel);
// 把 controller.render() 挂进同一棵渲染树
const UIRenderer = defineComponent(() => {
return () => controller.render();
});
export default defineComponent(() => {
// 打开与关闭必须复用同一个实例
let instance: IUIInstance | null = null;
const stackSize = computed(() => controller.stack.length);
const activeText = computed(() =>
controller.active.value ? '已打开' : '未打开'
);
const openUI = () => {
if (!instance) {
instance = controller.open(demoUI, {});
}
};
const closeUI = () => {
if (instance) {
controller.close(instance);
instance = null;
}
};
onUnmounted(() => {
controller.closeAll();
});
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#141a22" />
<text loc={[20, 20]} text="打开 UI" fillStyle="#e8f0ff" />
<container loc={[20, 44, 150, 44]} onClick={openUI}>
<g-rect loc={[0, 0, 150, 44]} fill fillStyle="#2f6fed" />
<text loc={[16, 12]} text="打开" fillStyle="#ffffff" />
</container>
<text loc={[20, 116]} text="关闭 UI" fillStyle="#e8f0ff" />
<container loc={[20, 140, 150, 44]} onClick={closeUI}>
<g-rect loc={[0, 0, 150, 44]} fill fillStyle="#3a2f5f" />
<text loc={[16, 12]} text="关闭" fillStyle="#ffffff" />
</container>
<text
loc={[20, 220]}
text={`栈长度:${stackSize.value}`}
fillStyle="#8fb6ff"
/>
<text
loc={[20, 252]}
text={`状态:${activeText.value}`}
fillStyle="#8fb6ff"
/>
<UIRenderer />
</container>
);
});
@@ -0,0 +1,74 @@
import { computed, defineComponent, ref } from 'vue';
interface ItemCardProps {
label: string;
active?: boolean;
}
type ItemCardEmits = {
pick: (label: string) => void;
};
interface ItemCardOptions {
props: (keyof ItemCardProps)[];
emits: (keyof ItemCardEmits)[];
}
const itemCardOptions: ItemCardOptions = {
props: ['label', 'active'],
emits: ['pick']
};
// 子组件:按 props 决定颜色,点击时发出 pick 事件,底部内容由默认 slot 填入
const ItemCard = defineComponent<
ItemCardProps,
ItemCardEmits,
keyof ItemCardEmits
>((props, { emit, slots }) => {
const fill = computed(() => (props.active ? '#2f6fed' : '#26364d'));
return () => (
<container
loc={[0, 0, 200, 96]}
onClick={() => emit('pick', props.label)}
>
<g-rect loc={[0, 0, 200, 96]} fillStyle={fill.value} />
<text loc={[12, 12]} text={props.label} fillStyle="#ffffff" />
{slots.default?.()}
</container>
);
}, itemCardOptions);
// 父组件:用 ref 保存选中项,把 props、事件与默认 slot 传给两个卡片
export default defineComponent(() => {
const selected = ref('甲');
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 28]}
text={`当前选择:${selected.value}`}
fillStyle="#cfe0ff"
/>
<container loc={[24, 72]}>
<ItemCard
label="甲"
active={selected.value === '甲'}
onPick={label => (selected.value = label)}
>
<text loc={[12, 60]} text="点我选择" fillStyle="#cfe0ff" />
</ItemCard>
</container>
<container loc={[256, 72]}>
<ItemCard
label="乙"
active={selected.value === '乙'}
onPick={label => (selected.value = label)}
>
<text loc={[12, 60]} text="点我选择" fillStyle="#cfe0ff" />
</ItemCard>
</container>
</container>
);
});
@@ -0,0 +1,88 @@
import type { CustomRenderFunction } from '@motajs/render';
import { defineComponent, ref } from 'vue';
const ringColors = ['#2f6fed', '#7aa7ff', '#f2b84b'];
// 演示 custom 的局部坐标绘制:同心圆环、径向渐变与旋转指针
export default defineComponent(() => {
// 把 angle.value 放进 bindings;点击按钮改变角度时会触发重绘
const angle = ref(0);
// 在元素局部坐标里直接绘制:同心圆环、径向渐变与旋转指针
const render: CustomRenderFunction = canvas => {
const ctx = canvas.ctx;
const cx = 100;
const cy = 100;
// 径向渐变与同心圆环直接走 Canvas 2D
const gradient = ctx.createRadialGradient(cx, cy, 12, cx, cy, 88);
gradient.addColorStop(0, '#2f6fed');
gradient.addColorStop(1, '#141a22');
ctx.beginPath();
ctx.arc(cx, cy, 88, 0, Math.PI * 2);
ctx.fillStyle = gradient;
ctx.fill();
ringColors.forEach((color, index) => {
ctx.beginPath();
ctx.arc(cx, cy, 70 - index * 16, 0, Math.PI * 2);
ctx.strokeStyle = color;
ctx.lineWidth = 3;
ctx.stroke();
});
// 指针从圆心出发,按 angle 旋转;坐标都相对元素左上角
ctx.translate(cx, cy);
ctx.rotate(angle.value);
ctx.beginPath();
ctx.moveTo(0, 0);
ctx.lineTo(0, -64);
ctx.strokeStyle = '#e8f0ff';
ctx.lineWidth = 4;
ctx.stroke();
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="<custom> 在局部坐标里直接绘制"
fillStyle="#cfe0ff"
/>
<custom
loc={[140, 44, 200, 200]}
bindings={[angle.value]}
render={render}
/>
<container
loc={[138, 256, 92, 36]}
onClick={() => {
angle.value -= Math.PI / 12;
}}
>
<g-rect loc={[0, 0, 92, 36]} fillStyle="#2f6fed" />
<text loc={[18, 9]} text="−15°" fillStyle="#e8f0ff" />
</container>
<container
loc={[250, 256, 92, 36]}
onClick={() => {
angle.value += Math.PI / 12;
}}
>
<g-rect loc={[0, 0, 92, 36]} fillStyle="#2f6fed" />
<text loc={[18, 9]} text="+15°" fillStyle="#e8f0ff" />
</container>
<text
loc={[24, 300]}
text="angle.value 放进 bindings,点击按钮会重绘"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,73 @@
import { defineComponent, ref } from 'vue';
import type { IActionEvent, IWheelEvent } from '@motajs/render';
// 内置事件:按下、抬起、点击,以及进入、离开、移动、滚轮
export default defineComponent(() => {
const log = ref<string[]>([]);
const move = ref('—');
const push = (text: string) => {
log.value = [...log.value, text].slice(-4);
};
const handleDown = () => push('按下');
const handleUp = () => push('抬起');
const handleClick = () => push('点击');
const handleEnter = () => push('进入');
const handleLeave = () => push('离开');
const handleMove = (ev: IActionEvent) => {
move.value = `${Math.round(ev.offsetX)}, ${Math.round(ev.offsetY)}`;
};
const handleWheel = (ev: IWheelEvent) => {
push(`滚轮 ${Math.round(ev.wheelY)}`);
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="内置事件" fillStyle="#cfe0ff" />
<g-rect
loc={[24, 56, 160, 48]}
fillStyle="#2f6fed"
onDown={handleDown}
onUp={handleUp}
onClick={handleClick}
/>
<text loc={[64, 73]} text="点我" fillStyle="#e8f0ff" noevent />
<g-rect
loc={[212, 56, 244, 112]}
fillStyle="#26364d"
onEnter={handleEnter}
onLeave={handleLeave}
onMove={handleMove}
onWheel={handleWheel}
/>
<text
loc={[228, 72]}
text="悬停、移动、滚轮"
fillStyle="#cfe0ff"
noevent
/>
<text
loc={[228, 100]}
text={`局部坐标:${move.value}`}
fillStyle="#8b98a8"
noevent
/>
<text
loc={[24, 196]}
text={`事件:${log.value.join(' → ')}`}
fillStyle="#f2b84b"
/>
<text
loc={[24, 236]}
text="移动只更新坐标,不写入事件日志"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,76 @@
import { defineComponent, ref } from 'vue';
import type { IActionEvent } from '@motajs/render';
// 同一个点击在内层、外层与画布坐标下的不同结果
export default defineComponent(() => {
const inner = ref('—');
const outer = ref('—');
const absolute = ref('—');
// 外层移动与点击都刷新同一组外层坐标
const handleOuterPoint = (ev: IActionEvent) => {
outer.value = `${Math.round(ev.offsetX)}, ${Math.round(ev.offsetY)}`;
absolute.value = `${Math.round(ev.absoluteX)}, ${Math.round(
ev.absoluteY
)}`;
};
// 内层移动与点击都刷新同一组内层坐标
const handleInnerPoint = (ev: IActionEvent) => {
inner.value = `${Math.round(ev.offsetX)}, ${Math.round(ev.offsetY)}`;
};
const handleInnerLeave = () => {
inner.value = '—';
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="事件坐标" fillStyle="#cfe0ff" />
<container
loc={[24, 60, 216, 180]}
onMove={handleOuterPoint}
onClick={handleOuterPoint}
>
<g-rect loc={[0, 0, 216, 180]} fillStyle="#26364d" />
<g-rect
loc={[36, 40, 144, 88]}
fillStyle="#2f6fed"
onMove={handleInnerPoint}
onClick={handleInnerPoint}
onLeave={handleInnerLeave}
/>
<text
loc={[72, 76]}
text="点这里"
fillStyle="#e8f0ff"
noevent
/>
</container>
<text
loc={[264, 76]}
text={`内层 offset:${inner.value}`}
fillStyle="#ffffff"
/>
<text
loc={[264, 108]}
text={`外层 offset:${outer.value}`}
fillStyle="#f2b84b"
/>
<text
loc={[264, 140]}
text={`画布 absolute:${absolute.value}`}
fillStyle="#7ee787"
/>
<text
loc={[24, 264]}
text="在内层与外层移动、点击,比较三组坐标"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,95 @@
import { defineComponent, ref } from 'vue';
import type { IWheelEvent } from '@motajs/render';
// enter / leave 由悬停集合做差集触发,滚轮与 cursor 跟随命中结果
export default defineComponent(() => {
const outerState = ref('未进入');
const innerState = ref('未进入');
const cursor = ref('pointer');
const total = ref(0);
const handleOuterEnter = () => {
outerState.value = '进入';
cursor.value = 'pointer';
};
const handleOuterLeave = () => {
outerState.value = '离开';
cursor.value = 'pointer';
};
const handleOuterWheel = (ev: IWheelEvent) => {
total.value += ev.wheelY;
};
const handleInnerEnter = () => {
innerState.value = '进入';
cursor.value = 'text';
};
const handleInnerLeave = () => {
innerState.value = '离开';
cursor.value = 'pointer';
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="悬停与滚轮" fillStyle="#cfe0ff" />
<container
loc={[24, 64, 220, 176]}
cursor="pointer"
onEnter={handleOuterEnter}
onLeave={handleOuterLeave}
onWheel={handleOuterWheel}
>
<g-rect loc={[0, 0, 220, 176]} fillStyle="#26364d" />
<text
loc={[16, 16]}
text="外层:cursor pointer"
fillStyle="#cfe0ff"
/>
<g-rect
loc={[40, 64, 140, 80]}
fillStyle="#2f6fed"
cursor="text"
onEnter={handleInnerEnter}
onLeave={handleInnerLeave}
/>
<text
loc={[40, 152]}
text="内层:cursor text"
fillStyle="#e8f0ff"
/>
</container>
<text
loc={[264, 80]}
text={`外层:${outerState.value}`}
fillStyle="#ffffff"
/>
<text
loc={[264, 112]}
text={`内层:${innerState.value}`}
fillStyle="#7ee787"
/>
<text
loc={[264, 144]}
text={`cursor:${cursor.value}`}
fillStyle="#f2b84b"
/>
<text
loc={[264, 176]}
text={`滚轮累计:${Math.round(total.value)}`}
fillStyle="#cfe0ff"
/>
<text
loc={[24, 264]}
text="从内层移回外层时,外层不会重新 enter"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,94 @@
import { defineComponent, ref } from 'vue';
import type { IActionEvent } from '@motajs/render';
// 嵌套容器中的捕获与冒泡,以及可切换的 stopPropagation
export default defineComponent(() => {
const log = ref<string[]>([]);
const stop = ref(false);
// 每次点击只保留本次交互的日志,不做累积
const push = (text: string) => {
log.value = [...log.value, text];
};
const handleToggleStop = () => {
stop.value = !stop.value;
};
// 外层捕获是一次点击的起点:先清空日志,再记录本次触发的后续事件
const handleOuterCapture = () => {
log.value = ['外层捕获'];
};
const handleOuterBubble = () => push('外层冒泡');
const handleInnerCapture = () => push('内层捕获');
const handleInnerBubble = () => push('内层冒泡');
const handleButtonCapture = () => push('按钮捕获');
const handleButtonBubble = (ev: IActionEvent) => {
// 先记录按钮冒泡,再按开关决定是否截断向外传播
push('按钮冒泡');
if (stop.value) ev.stopPropagation();
};
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="捕获与冒泡" fillStyle="#cfe0ff" />
{/* 切换 stop:只影响下方按钮冒泡是否继续向外层传递 */}
<container loc={[24, 52, 156, 36]} onClick={handleToggleStop}>
<g-rect
loc={[0, 0, 156, 36]}
fillStyle={stop.value ? '#f2b84b' : '#2f6fed'}
/>
<text
loc={[18, 10]}
text={stop.value ? 'stop:开启' : 'stop:关闭'}
fillStyle="#141a22"
/>
</container>
{/* 外层捕获是一次点击的起点:先清空日志,再记录本次触发的后续事件 */}
<container
loc={[24, 108, 264, 172]}
onClickCapture={handleOuterCapture}
onClick={handleOuterBubble}
>
<g-rect loc={[0, 0, 264, 172]} fillStyle="#26364d" />
<container
loc={[32, 32, 200, 108]}
onClickCapture={handleInnerCapture}
onClick={handleInnerBubble}
>
<g-rect loc={[0, 0, 200, 108]} fillStyle="#1d2a3a" />
<g-rect
loc={[40, 28, 120, 52]}
fillStyle="#2f6fed"
onClickCapture={handleButtonCapture}
onClick={handleButtonBubble}
/>
<text loc={[40, 90]} text="点按钮" fillStyle="#e8f0ff" />
</container>
</container>
<text loc={[308, 80]} text="只显示本次点击" fillStyle="#8b98a8" />
{[0, 1, 2, 3, 4, 5].map(index => (
<text
key={index}
loc={[308, 112 + index * 24]}
text={log.value[index] ?? ''}
fillStyle="#f2b84b"
/>
))}
<text
loc={[24, 292]}
text="stop 开启后,按钮冒泡不再传给外层"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,47 @@
import { Texture } from '@motajs/render';
import { defineComponent } from 'vue';
// 演示用纹理:只在 demo 内部生成,正文不展示生成方式
function createDemoTexture() {
const canvas = document.createElement('canvas');
canvas.width = 64;
canvas.height = 64;
const ctx = canvas.getContext('2d')!;
ctx.fillStyle = '#1d2733';
ctx.fillRect(0, 0, 64, 64);
ctx.strokeStyle = '#7aa7ff';
ctx.lineWidth = 4;
ctx.strokeRect(8, 8, 48, 48);
ctx.fillStyle = '#f2b84b';
ctx.beginPath();
ctx.arc(32, 32, 14, 0, Math.PI * 2);
ctx.fill();
return new Texture(canvas);
}
const demoTexture = createDemoTexture();
// 单张图片:loc 固定为 [40, 64, 128, 128]
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="<image> 按 loc 显示纹理的效果"
fillStyle="#cfe0ff"
/>
<image image={demoTexture} loc={[40, 64, 128, 128]} />
<text
loc={[40, 208]}
text="loc = [40, 64, 128, 128]"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,48 @@
import { Texture } from '@motajs/render';
import { defineComponent } from 'vue';
// 演示用纹理:只在 demo 内部生成,正文不展示生成方式
function createDemoTexture() {
const canvas = document.createElement('canvas');
canvas.width = 64;
canvas.height = 64;
const ctx = canvas.getContext('2d')!;
ctx.fillStyle = '#1d2733';
ctx.fillRect(0, 0, 64, 64);
ctx.strokeStyle = '#7aa7ff';
ctx.lineWidth = 4;
ctx.strokeRect(8, 8, 48, 48);
ctx.fillStyle = '#f2b84b';
ctx.beginPath();
ctx.arc(32, 32, 14, 0, Math.PI * 2);
ctx.fill();
return new Texture(canvas);
}
const demoTexture = createDemoTexture();
// 同一张纹理放进三种尺寸的矩形
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="同一张图,三种显示尺寸"
fillStyle="#cfe0ff"
/>
<image image={demoTexture} loc={[48, 96, 64, 64]} />
<text loc={[48, 172]} text="64×64" fillStyle="#8b98a8" />
<image image={demoTexture} loc={[192, 80, 96, 96]} />
<text loc={[192, 188]} text="96×96" fillStyle="#8b98a8" />
<image image={demoTexture} loc={[336, 64, 128, 128]} />
<text loc={[336, 204]} text="128×128" fillStyle="#8b98a8" />
</container>
);
});
@@ -0,0 +1,50 @@
import { defineComponent, ref } from 'vue';
// 示例(一)的 live:720×480 骨架、标题、关闭按钮与左右占位
export default defineComponent(() => {
const hint = ref('骨架阶段:先确认面板能显示、关闭按钮能用');
const close = () => {
// 文档站没有真实 UI 栈,用一行提示代替 controller.close
hint.value = '已请求关闭(真实面板会调用 controller.close)';
};
return () => (
<container loc={[0, 0, 720, 480]}>
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
stroke
strokeStyle="#2f6fed"
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
<container loc={[626, 50, 56, 32]} onClick={close}>
<g-rectr
loc={[0, 0, 56, 32]}
circle={[8]}
fill
fillStyle="#7a3d3d"
/>
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
</container>
<container loc={[54, 110, 400, 330]}>
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
<text loc={[16, 16]} text="道具网格占位" fillStyle="#8fb6ff" />
</container>
<container loc={[470, 110, 196, 330]}>
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
<text loc={[16, 16]} text="详情占位" fillStyle="#8fb6ff" />
</container>
<text loc={[54, 420]} text={hint.value} fillStyle="#8fb6ff" />
</container>
);
});
@@ -0,0 +1,192 @@
import { computed, defineComponent, ref } from 'vue';
interface Item {
id: string;
name: string;
count: number;
desc: string;
}
interface ItemCellProps {
item: Item;
selected: boolean;
size: number;
}
type ItemCellEmits = {
select: (id: string) => void;
};
interface ItemCellOptions {
props: (keyof ItemCellProps)[];
emits: (keyof ItemCellEmits)[];
}
const itemCellOptions: ItemCellOptions = {
props: ['item', 'selected', 'size'],
emits: ['select']
};
// 单个格子:只负责画名称、数量与选中态,点击后把 id 交给父组件
// 格子只接收结果,选中状态由父组件持有
const ItemCell = defineComponent<
ItemCellProps,
ItemCellEmits,
keyof ItemCellEmits
>((props, { emit }) => {
return () => (
<container
loc={[0, 0, props.size, props.size]}
onClick={() => emit('select', props.item.id)}
>
<g-rectr
loc={[0, 0, props.size, props.size]}
circle={[10]}
fill
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
/>
<g-rectr
loc={[1, 1, props.size - 2, props.size - 2]}
circle={[9]}
stroke
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
/>
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
<text
loc={[8, props.size - 24]}
text={`× ${props.item.count}`}
fillStyle="#cfe0ff"
/>
</container>
);
}, itemCellOptions);
interface ItemGridProps {
items: Item[];
selectedId: string;
columns: number;
cellSize: number;
gap: number;
}
type ItemGridEmits = {
select: (id: string) => void;
};
interface ItemGridOptions {
props: (keyof ItemGridProps)[];
emits: (keyof ItemGridEmits)[];
}
const itemGridOptions: ItemGridOptions = {
props: ['items', 'selectedId', 'columns', 'cellSize', 'gap'],
emits: ['select']
};
// 网格:用列数、格子尺寸与间距算出位置,不写死每格坐标
const ItemGrid = defineComponent<
ItemGridProps,
ItemGridEmits,
keyof ItemGridEmits
>((props, { emit }) => {
return () => (
<container loc={[0, 0, 0, 0]}>
{props.items.map((item, index) => {
const col = index % props.columns;
const row = Math.floor(index / props.columns);
const x = col * (props.cellSize + props.gap);
const y = row * (props.cellSize + props.gap);
return (
<container loc={[x, y]}>
<ItemCell
item={item}
selected={item.id === props.selectedId}
size={props.cellSize}
onSelect={id => emit('select', id)}
/>
</container>
);
})}
</container>
);
}, itemGridOptions);
const items: Item[] = [
{ id: 'potion-red', name: '红药水', count: 3, desc: '恢复少量生命。' },
{ id: 'potion-blue', name: '蓝药水', count: 1, desc: '恢复少量魔力。' },
{ id: 'key-yellow', name: '黄钥匙', count: 5, desc: '打开黄色的门。' },
{ id: 'key-blue', name: '蓝钥匙', count: 2, desc: '打开蓝色的门。' },
{ id: 'sword-wood', name: '木剑', count: 1, desc: '最基础的武器。' },
{ id: 'shield-wood', name: '木盾', count: 1, desc: '最基础的防具。' },
{ id: 'gem-red', name: '红宝石', count: 4, desc: '镶嵌用的素材。' },
{ id: 'gem-blue', name: '蓝宝石', count: 2, desc: '镶嵌用的素材。' },
{ id: 'scroll', name: '回城卷轴', count: 1, desc: '回到起点。' },
{ id: 'bread', name: '面包', count: 6, desc: '恢复少量生命。' }
];
// 示例(二)的 live:骨架 + 网格 + 选中态
export default defineComponent(() => {
const selectedId = ref('potion-red');
const selectedItem = computed(() =>
items.find(item => item.id === selectedId.value)
);
return () => (
<container loc={[0, 0, 720, 480]}>
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
stroke
strokeStyle="#2f6fed"
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
<container loc={[626, 50, 56, 32]}>
<g-rectr
loc={[0, 0, 56, 32]}
circle={[8]}
fill
fillStyle="#7a3d3d"
/>
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
</container>
<container loc={[54, 110, 400, 330]}>
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
<ItemGrid
items={items}
selectedId={selectedId.value}
columns={5}
cellSize={66}
gap={8}
onSelect={id => (selectedId.value = id)}
/>
</container>
<container loc={[470, 110, 196, 330]}>
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
<text
loc={[16, 16]}
text={
selectedItem.value ? selectedItem.value.name : '未选择'
}
fillStyle="#8fb6ff"
/>
<text
loc={[16, 48]}
text={
selectedItem.value
? `数量 × ${selectedItem.value.count}`
: '点击左侧格子'
}
fillStyle="#cfe0ff"
/>
</container>
</container>
);
});
@@ -0,0 +1,251 @@
import { computed, defineComponent, ref } from 'vue';
interface Item {
id: string;
name: string;
count: number;
desc: string;
}
interface ItemCellProps {
item: Item;
selected: boolean;
size: number;
}
type ItemCellEmits = {
select: (id: string) => void;
};
interface ItemCellOptions {
props: (keyof ItemCellProps)[];
emits: (keyof ItemCellEmits)[];
}
const itemCellOptions: ItemCellOptions = {
props: ['item', 'selected', 'size'],
emits: ['select']
};
// 网格、详情与父组件共享同一份道具数据
const ItemCell = defineComponent<
ItemCellProps,
ItemCellEmits,
keyof ItemCellEmits
>((props, { emit }) => {
return () => (
<container
loc={[0, 0, props.size, props.size]}
onClick={() => emit('select', props.item.id)}
>
<g-rectr
loc={[0, 0, props.size, props.size]}
circle={[10]}
fill
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
/>
<g-rectr
loc={[1, 1, props.size - 2, props.size - 2]}
circle={[9]}
stroke
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
/>
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
<text
loc={[8, props.size - 24]}
text={`× ${props.item.count}`}
fillStyle="#cfe0ff"
/>
</container>
);
}, itemCellOptions);
interface ItemGridProps {
items: Item[];
selectedId: string;
columns: number;
cellSize: number;
gap: number;
}
type ItemGridEmits = {
select: (id: string) => void;
};
interface ItemGridOptions {
props: (keyof ItemGridProps)[];
emits: (keyof ItemGridEmits)[];
}
const itemGridOptions: ItemGridOptions = {
props: ['items', 'selectedId', 'columns', 'cellSize', 'gap'],
emits: ['select']
};
const ItemGrid = defineComponent<
ItemGridProps,
ItemGridEmits,
keyof ItemGridEmits
>((props, { emit }) => {
return () => (
<container loc={[0, 0, 0, 0]}>
{props.items.map((item, index) => {
const col = index % props.columns;
const row = Math.floor(index / props.columns);
const x = col * (props.cellSize + props.gap);
const y = row * (props.cellSize + props.gap);
return (
<container loc={[x, y]}>
<ItemCell
item={item}
selected={item.id === props.selectedId}
size={props.cellSize}
onSelect={id => emit('select', id)}
/>
</container>
);
})}
</container>
);
}, itemGridOptions);
interface ItemDetailProps {
item?: Item;
}
type ItemDetailEmits = {
clear: () => void;
};
interface ItemDetailOptions {
props: (keyof ItemDetailProps)[];
emits: (keyof ItemDetailEmits)[];
}
const itemDetailOptions: ItemDetailOptions = {
props: ['item'],
emits: ['clear']
};
// 右侧详情:没有选中时显示提示,有选中时显示名称、数量与描述
// 详情只接收选中的道具,没有选中时显示提示
const ItemDetail = defineComponent<
ItemDetailProps,
ItemDetailEmits,
keyof ItemDetailEmits
>((props, { emit }) => {
const clear = () => emit('clear');
return () => (
<container loc={[0, 0, 196, 330]}>
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
{/* 两块都渲染,用 hidden 切换 */}
<container hidden={!!props.item}>
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
</container>
<container hidden={!props.item}>
<text
loc={[16, 52]}
text={props.item ? props.item.name : ''}
fillStyle="#e8f0ff"
/>
<text
loc={[16, 84]}
text={props.item ? `数量:${props.item.count}` : ''}
fillStyle="#cfe0ff"
/>
<text
loc={[16, 120]}
text={props.item ? props.item.desc : ''}
fillStyle="#8fb6ff"
/>
<text
loc={[16, 156]}
text="live 用 text 等价展示说明"
fillStyle="#4f6d94"
/>
</container>
<container loc={[16, 286, 164, 28]} onClick={clear}>
<g-rectr
loc={[0, 0, 164, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
</container>
</container>
);
}, itemDetailOptions);
// 假数据只用于演示,可替换成存档数据
const items: Item[] = [
{ id: 'potion-red', name: '红药水', count: 3, desc: '恢复少量生命。' },
{ id: 'potion-blue', name: '蓝药水', count: 1, desc: '恢复少量魔力。' },
{ id: 'key-yellow', name: '黄钥匙', count: 5, desc: '打开黄色的门。' },
{ id: 'key-blue', name: '蓝钥匙', count: 2, desc: '打开蓝色的门。' },
{ id: 'sword-wood', name: '木剑', count: 1, desc: '最基础的武器。' },
{ id: 'shield-wood', name: '木盾', count: 1, desc: '最基础的防具。' },
{ id: 'gem-red', name: '红宝石', count: 4, desc: '镶嵌用的素材。' },
{ id: 'gem-blue', name: '蓝宝石', count: 2, desc: '镶嵌用的素材。' },
{ id: 'scroll', name: '回城卷轴', count: 1, desc: '回到起点。' },
{ id: 'bread', name: '面包', count: 6, desc: '恢复少量生命。' }
];
// 示例(三)的 live:骨架 + 网格 + 选中态 + 详情区
export default defineComponent(() => {
const selectedId = ref('potion-red');
const selectedItem = computed(() =>
items.find(item => item.id === selectedId.value)
);
return () => (
<container loc={[0, 0, 720, 480]}>
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
stroke
strokeStyle="#2f6fed"
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
<container loc={[626, 50, 56, 32]}>
<g-rectr
loc={[0, 0, 56, 32]}
circle={[8]}
fill
fillStyle="#7a3d3d"
/>
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
</container>
<container loc={[54, 110, 400, 330]}>
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
<ItemGrid
items={items}
selectedId={selectedId.value}
columns={5}
cellSize={66}
gap={8}
onSelect={id => (selectedId.value = id)}
/>
</container>
<container loc={[470, 110, 196, 330]}>
<ItemDetail
item={selectedItem.value}
onClear={() => (selectedId.value = '')}
/>
</container>
</container>
);
});
@@ -0,0 +1,301 @@
import { computed, defineComponent, ref } from 'vue';
interface Item {
id: string;
name: string;
count: number;
desc: string;
}
interface ItemCellProps {
item: Item;
selected: boolean;
size: number;
}
type ItemCellEmits = {
select: (id: string) => void;
};
interface ItemCellOptions {
props: (keyof ItemCellProps)[];
emits: (keyof ItemCellEmits)[];
}
const itemCellOptions: ItemCellOptions = {
props: ['item', 'selected', 'size'],
emits: ['select']
};
// 滚动演示沿用网格与详情的组件结构
const ItemCell = defineComponent<
ItemCellProps,
ItemCellEmits,
keyof ItemCellEmits
>((props, { emit }) => {
return () => (
<container
loc={[0, 0, props.size, props.size]}
onClick={() => emit('select', props.item.id)}
>
<g-rectr
loc={[0, 0, props.size, props.size]}
circle={[10]}
fill
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
/>
<g-rectr
loc={[1, 1, props.size - 2, props.size - 2]}
circle={[9]}
stroke
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
/>
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
<text
loc={[8, props.size - 24]}
text={`× ${props.item.count}`}
fillStyle="#cfe0ff"
/>
</container>
);
}, itemCellOptions);
interface ItemDetailProps {
item?: Item;
}
type ItemDetailEmits = {
clear: () => void;
};
interface ItemDetailOptions {
props: (keyof ItemDetailProps)[];
emits: (keyof ItemDetailEmits)[];
}
const itemDetailOptions: ItemDetailOptions = {
props: ['item'],
emits: ['clear']
};
const ItemDetail = defineComponent<
ItemDetailProps,
ItemDetailEmits,
keyof ItemDetailEmits
>((props, { emit }) => {
const clear = () => emit('clear');
return () => (
<container loc={[0, 0, 196, 330]}>
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
<container hidden={!!props.item}>
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
</container>
<container hidden={!props.item}>
<text
loc={[16, 52]}
text={props.item ? props.item.name : ''}
fillStyle="#e8f0ff"
/>
<text
loc={[16, 84]}
text={props.item ? `数量:${props.item.count}` : ''}
fillStyle="#cfe0ff"
/>
<text
loc={[16, 120]}
text={props.item ? props.item.desc : ''}
fillStyle="#8fb6ff"
/>
</container>
<container loc={[16, 286, 164, 28]} onClick={clear}>
<g-rectr
loc={[0, 0, 164, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
</container>
</container>
);
}, itemDetailOptions);
const NAMES = [
'红药水',
'蓝药水',
'黄钥匙',
'蓝钥匙',
'木剑',
'木盾',
'红宝石',
'蓝宝石',
'回城卷轴',
'面包'
];
// 40 个假道具用来撑出可滚动的内容
const items: Item[] = Array.from({ length: 40 }, (_, index) => ({
id: `item-${index + 1}`,
name: NAMES[index % NAMES.length],
count: (index % 6) + 1,
desc: `第 ${index + 1} 个道具。`
}));
const COLUMNS = 5;
const CELL_SIZE = 66;
const GAP = 8;
const ROW_PITCH = CELL_SIZE + GAP;
const VIEW_WIDTH = 372;
const VIEW_HEIGHT = 294;
const ROWS = Math.ceil(items.length / COLUMNS);
const CONTENT_HEIGHT = ROWS * ROW_PITCH;
const MAX_START_ROW = Math.max(0, ROWS - Math.floor(VIEW_HEIGHT / ROW_PITCH));
const MAX_SCROLL = MAX_START_ROW * ROW_PITCH;
// 示例(四)的 live:用元素层等价实现 Scroll 的滚动窗口与滚动条
// 滚动位置只保存在本地 ref,滚动条由计算出的位置绘制
export default defineComponent(() => {
const selectedId = ref('item-1');
const scrollTop = ref(0);
const selectedItem = computed(() =>
items.find(item => item.id === selectedId.value)
);
const startRow = computed(() => Math.round(scrollTop.value / ROW_PITCH));
// 滚轮与按钮都只调整 scrollTop
const scrollRows = (delta: number) => {
const current = Math.round(scrollTop.value / ROW_PITCH);
const next = Math.max(0, Math.min(MAX_START_ROW, current + delta));
scrollTop.value = next * ROW_PITCH;
};
const onWheel = (ev: { wheelY: number }) => {
scrollRows(ev.wheelY > 0 ? 1 : -1);
};
const backToTop = () => {
scrollTop.value = 0;
};
const toBottom = () => {
scrollTop.value = MAX_SCROLL;
};
const thumbHeight = Math.max(
28,
(VIEW_HEIGHT / CONTENT_HEIGHT) * VIEW_HEIGHT
);
const thumbY =
MAX_SCROLL === 0
? 0
: (scrollTop.value / MAX_SCROLL) * (VIEW_HEIGHT - thumbHeight);
return () => (
<container loc={[0, 0, 720, 480]}>
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
stroke
strokeStyle="#2f6fed"
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
<container loc={[626, 50, 56, 32]}>
<g-rectr
loc={[0, 0, 56, 32]}
circle={[8]}
fill
fillStyle="#7a3d3d"
/>
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
</container>
<container loc={[54, 110, 400, 330]}>
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
<container
loc={[0, 0, VIEW_WIDTH, VIEW_HEIGHT]}
onWheel={onWheel}
>
{items.map((item, index) => {
const row = Math.floor(index / COLUMNS);
// 只渲染视口附近的行,等价于 Scroll 的虚拟滚动
if (row < startRow.value || row >= startRow.value + 5) {
return null;
}
const col = index % COLUMNS;
return (
<container
key={item.id}
loc={[
col * ROW_PITCH,
(row - startRow.value) * ROW_PITCH
]}
>
<ItemCell
item={item}
selected={item.id === selectedId.value}
size={CELL_SIZE}
onSelect={id => (selectedId.value = id)}
/>
</container>
);
})}
</container>
<g-rect
loc={[378, 0, 6, VIEW_HEIGHT]}
fill
fillStyle="#1b2634"
/>
<g-rectr
loc={[378, thumbY, 6, thumbHeight]}
circle={[3]}
fill
fillStyle="#3f6fa8"
/>
<container loc={[0, 302, 90, 28]} onClick={backToTop}>
<g-rectr
loc={[0, 0, 90, 28]}
circle={[6]}
fill
fillStyle="#2f6fed"
/>
<text loc={[10, 6]} text="回到顶部" fillStyle="#ffffff" />
</container>
<container loc={[100, 302, 90, 28]} onClick={toBottom}>
<g-rectr
loc={[0, 0, 90, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[10, 6]} text="滚到底部" fillStyle="#e8f0ff" />
</container>
<text
loc={[204, 308]}
text={`已滚动 ${scrollTop.value} / ${MAX_SCROLL}`}
fillStyle="#8fb6ff"
/>
</container>
<container loc={[470, 110, 196, 330]}>
<ItemDetail
item={selectedItem.value}
onClear={() => (selectedId.value = '')}
/>
</container>
</container>
);
});
@@ -0,0 +1,402 @@
import { computed, defineComponent, ref, watch } from 'vue';
interface Item {
id: string;
name: string;
count: number;
desc: string;
}
interface ItemCellProps {
item: Item;
selected: boolean;
equipped: boolean;
size: number;
}
type ItemCellEmits = {
select: (id: string) => void;
};
interface ItemCellOptions {
props: (keyof ItemCellProps)[];
emits: (keyof ItemCellEmits)[];
}
const itemCellOptions: ItemCellOptions = {
props: ['item', 'selected', 'equipped', 'size'],
emits: ['select']
};
// 装备、使用与关闭的状态全部集中在根组件
const ItemCell = defineComponent<
ItemCellProps,
ItemCellEmits,
keyof ItemCellEmits
>((props, { emit }) => {
const strokeStyle = computed(() => {
if (props.equipped) return '#7ee787';
if (props.selected) return '#f2b84b';
return '#33465f';
});
return () => (
<container
loc={[0, 0, props.size, props.size]}
onClick={() => emit('select', props.item.id)}
>
<g-rectr
loc={[0, 0, props.size, props.size]}
circle={[10]}
fill
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
/>
<g-rectr
loc={[1, 1, props.size - 2, props.size - 2]}
circle={[9]}
stroke
strokeStyle={strokeStyle.value}
/>
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
<text
loc={[8, props.size - 24]}
text={`× ${props.item.count}`}
fillStyle="#cfe0ff"
/>
</container>
);
}, itemCellOptions);
interface ItemDetailProps {
item?: Item;
}
type ItemDetailEmits = {
clear: () => void;
};
interface ItemDetailOptions {
props: (keyof ItemDetailProps)[];
emits: (keyof ItemDetailEmits)[];
}
const itemDetailOptions: ItemDetailOptions = {
props: ['item'],
emits: ['clear']
};
// 详情只负责显示父组件算好的结果
const ItemDetail = defineComponent<
ItemDetailProps,
ItemDetailEmits,
keyof ItemDetailEmits
>((props, { emit }) => {
return () => (
<container loc={[0, 0, 196, 280]}>
<g-rect loc={[0, 0, 196, 280]} fill fillStyle="#101820" />
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
<container hidden={!!props.item}>
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
</container>
<container hidden={!props.item}>
<text
loc={[16, 52]}
text={props.item ? props.item.name : ''}
fillStyle="#e8f0ff"
/>
<text
loc={[16, 84]}
text={props.item ? `数量:${props.item.count}` : ''}
fillStyle="#cfe0ff"
/>
<text
loc={[16, 120]}
text={props.item ? props.item.desc : ''}
fillStyle="#8fb6ff"
/>
</container>
<container loc={[16, 236, 164, 28]} onClick={() => emit('clear')}>
<g-rectr
loc={[0, 0, 164, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
</container>
</container>
);
}, itemDetailOptions);
interface ActionBarProps {
canEquip: boolean;
canUse: boolean;
equipped: boolean;
}
type ActionBarEmits = {
equip: () => void;
use: () => void;
close: () => void;
};
interface ActionBarOptions {
props: (keyof ActionBarProps)[];
emits: (keyof ActionBarEmits)[];
}
const actionBarOptions: ActionBarOptions = {
props: ['canEquip', 'canUse', 'equipped'],
emits: ['equip', 'use', 'close']
};
// 按钮的可用性由父组件传入,自己不做业务判断
const ActionBar = defineComponent<
ActionBarProps,
ActionBarEmits,
keyof ActionBarEmits
>((props, { emit }) => {
const makeButton = (
x: number,
label: string,
enabled: boolean,
onClick: () => void
) => (
<container
loc={[x, 0, 96, 32]}
onClick={() => {
if (!enabled) return;
onClick();
}}
>
<g-rectr
loc={[0, 0, 96, 32]}
circle={[8]}
fill
fillStyle={enabled ? '#2f6fed' : '#26364d'}
alpha={enabled ? 1 : 0.5}
/>
<text loc={[12, 8]} text={label} fillStyle="#ffffff" />
</container>
);
return () => (
<container loc={[0, 0, 304, 32]}>
{makeButton(
0,
props.equipped ? '已装备' : '装备',
props.canEquip,
() => emit('equip')
)}
{makeButton(104, '使用', props.canUse, () => emit('use'))}
{makeButton(208, '关闭', true, () => emit('close'))}
</container>
);
}, actionBarOptions);
const NAMES = [
'红药水',
'蓝药水',
'黄钥匙',
'蓝钥匙',
'木剑',
'木盾',
'红宝石',
'蓝宝石',
'回城卷轴',
'面包'
];
// 40 个假道具同时用于测试滚动与使用次数
const sourceItems: Item[] = Array.from({ length: 40 }, (_, index) => ({
id: `item-${index + 1}`,
name: NAMES[index % NAMES.length],
count: (index % 6) + 1,
desc: `第 ${index + 1} 个道具。`
}));
const COLUMNS = 5;
const CELL_SIZE = 66;
const GAP = 8;
const ROW_PITCH = CELL_SIZE + GAP;
const VIEW_WIDTH = 372;
const VIEW_HEIGHT = 244;
const ROWS = Math.ceil(sourceItems.length / COLUMNS);
const MAX_START_ROW = Math.max(0, ROWS - Math.floor(VIEW_HEIGHT / ROW_PITCH));
const MAX_SCROLL = MAX_START_ROW * ROW_PITCH;
// 示例(五)的 live:滚动网格 + 详情 + 装备 / 使用 / 关闭
// items 复制一份,使用道具时只改本地副本
export default defineComponent(() => {
const items = ref<Item[]>(sourceItems.map(item => ({ ...item })));
const selectedId = ref('item-1');
const equippedId = ref('');
const hint = ref('选择道具后可以装备或使用');
const scrollTop = ref(0);
const selectedItem = computed(() =>
items.value.find(item => item.id === selectedId.value)
);
const canEquip = computed(() => !!selectedItem.value);
const canUse = computed(
() => !!selectedItem.value && selectedItem.value.count > 0
);
const isEquipped = computed(
() => !!selectedId.value && equippedId.value === selectedId.value
);
const startRow = computed(() => Math.round(scrollTop.value / ROW_PITCH));
const equip = () => {
if (!selectedItem.value) return;
equippedId.value = selectedItem.value.id;
hint.value = `已装备:${selectedItem.value.name}`;
};
const use = () => {
const item = selectedItem.value;
if (!item || item.count <= 0) return;
item.count -= 1;
};
watch(
() => selectedItem.value?.count ?? 0,
(next, prev) => {
hint.value = `数量:${prev} → ${next}`;
}
);
const scrollRows = (delta: number) => {
const current = Math.round(scrollTop.value / ROW_PITCH);
const next = Math.max(0, Math.min(MAX_START_ROW, current + delta));
scrollTop.value = next * ROW_PITCH;
};
const onWheel = (ev: { wheelY: number }) => {
scrollRows(ev.wheelY > 0 ? 1 : -1);
};
const thumbHeight = Math.max(
28,
(VIEW_HEIGHT / (ROWS * ROW_PITCH)) * VIEW_HEIGHT
);
const thumbY =
MAX_SCROLL === 0
? 0
: (scrollTop.value / MAX_SCROLL) * (VIEW_HEIGHT - thumbHeight);
return () => (
<container loc={[0, 0, 720, 480]}>
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
stroke
strokeStyle="#2f6fed"
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
<container loc={[54, 100, 400, 280]}>
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
<container
loc={[0, 0, VIEW_WIDTH, VIEW_HEIGHT]}
onWheel={onWheel}
>
{items.value.map((item, index) => {
const row = Math.floor(index / COLUMNS);
if (row < startRow.value || row >= startRow.value + 4) {
return null;
}
const col = index % COLUMNS;
return (
<container
key={item.id}
loc={[
col * ROW_PITCH,
(row - startRow.value) * ROW_PITCH
]}
>
<ItemCell
item={item}
selected={item.id === selectedId.value}
equipped={item.id === equippedId.value}
size={CELL_SIZE}
onSelect={id => (selectedId.value = id)}
/>
</container>
);
})}
</container>
<g-rect
loc={[378, 0, 6, VIEW_HEIGHT]}
fill
fillStyle="#1b2634"
/>
<g-rectr
loc={[378, thumbY, 6, thumbHeight]}
circle={[3]}
fill
fillStyle="#3f6fa8"
/>
<container
loc={[0, 252, 90, 28]}
onClick={() => scrollRows(-1)}
>
<g-rectr
loc={[0, 0, 90, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[10, 6]} text="上一行" fillStyle="#e8f0ff" />
</container>
<container
loc={[100, 252, 90, 28]}
onClick={() => scrollRows(1)}
>
<g-rectr
loc={[0, 0, 90, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[10, 6]} text="下一行" fillStyle="#e8f0ff" />
</container>
<text
loc={[204, 258]}
text={`已滚动 ${scrollTop.value} / ${MAX_SCROLL}`}
fillStyle="#8fb6ff"
/>
</container>
<container loc={[470, 100, 196, 280]}>
<ItemDetail
item={selectedItem.value}
onClear={() => (selectedId.value = '')}
/>
</container>
<container loc={[54, 392, 304, 32]}>
<ActionBar
canEquip={canEquip.value}
canUse={canUse.value}
equipped={isEquipped.value}
onEquip={equip}
onUse={use}
onClose={() => (hint.value = '已请求关闭')}
/>
</container>
<text loc={[54, 432]} text={hint.value} fillStyle="#8fb6ff" />
</container>
);
});
@@ -0,0 +1,482 @@
import {
computed,
defineComponent,
onMounted,
onUnmounted,
ref,
watch
} from 'vue';
interface Item {
id: string;
name: string;
count: number;
desc: string;
}
interface ItemCellProps {
item: Item;
selected: boolean;
equipped: boolean;
size: number;
pulse: number;
}
type ItemCellEmits = {
select: (id: string) => void;
};
interface ItemCellOptions {
props: (keyof ItemCellProps)[];
emits: (keyof ItemCellEmits)[];
}
const itemCellOptions: ItemCellOptions = {
props: ['item', 'selected', 'equipped', 'size', 'pulse'],
emits: ['select']
};
// 完整示例把网格、详情、滚动、装备与动画放在一个文件里
const ItemCell = defineComponent<
ItemCellProps,
ItemCellEmits,
keyof ItemCellEmits
>((props, { emit }) => {
const strokeStyle = computed(() => {
if (props.equipped) return '#7ee787';
if (props.selected) return '#f2b84b';
return '#33465f';
});
return () => (
<container
loc={[0, 0, props.size, props.size]}
onClick={() => emit('select', props.item.id)}
>
<g-rectr
loc={[0, 0, props.size, props.size]}
circle={[10]}
fill
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
/>
<g-rectr
loc={[1, 1, props.size - 2, props.size - 2]}
circle={[9]}
stroke
strokeStyle={strokeStyle.value}
alpha={props.selected ? props.pulse : 1}
/>
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
<text
loc={[8, props.size - 24]}
text={`× ${props.item.count}`}
fillStyle="#cfe0ff"
/>
</container>
);
}, itemCellOptions);
interface ItemDetailProps {
item?: Item;
pulse: number;
}
type ItemDetailEmits = {
clear: () => void;
};
interface ItemDetailOptions {
props: (keyof ItemDetailProps)[];
emits: (keyof ItemDetailEmits)[];
}
const itemDetailOptions: ItemDetailOptions = {
props: ['item', 'pulse'],
emits: ['clear']
};
const ItemDetail = defineComponent<
ItemDetailProps,
ItemDetailEmits,
keyof ItemDetailEmits
>((props, { emit }) => {
return () => (
<container loc={[0, 0, 196, 280]}>
<g-rect loc={[0, 0, 196, 280]} fill fillStyle="#101820" />
{/* 顶部亮条只改 alpha 与 scale,不重建组件 */}
<g-rect
loc={[0, 0, 196, 4]}
fill
fillStyle="#f2b84b"
alpha={props.pulse}
scale={[1, 0.5 + props.pulse]}
/>
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
<container hidden={!!props.item}>
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
</container>
<container hidden={!props.item}>
<text
loc={[16, 52]}
text={props.item ? props.item.name : ''}
fillStyle="#e8f0ff"
/>
<text
loc={[16, 84]}
text={props.item ? `数量:${props.item.count}` : ''}
fillStyle="#cfe0ff"
/>
<text
loc={[16, 120]}
text={props.item ? props.item.desc : ''}
fillStyle="#8fb6ff"
/>
</container>
<container loc={[16, 236, 164, 28]} onClick={() => emit('clear')}>
<g-rectr
loc={[0, 0, 164, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
</container>
</container>
);
}, itemDetailOptions);
interface ActionBarProps {
canEquip: boolean;
canUse: boolean;
equipped: boolean;
}
type ActionBarEmits = {
equip: () => void;
use: () => void;
close: () => void;
};
interface ActionBarOptions {
props: (keyof ActionBarProps)[];
emits: (keyof ActionBarEmits)[];
}
const actionBarOptions: ActionBarOptions = {
props: ['canEquip', 'canUse', 'equipped'],
emits: ['equip', 'use', 'close']
};
const ActionBar = defineComponent<
ActionBarProps,
ActionBarEmits,
keyof ActionBarEmits
>((props, { emit }) => {
const makeButton = (
x: number,
label: string,
enabled: boolean,
onClick: () => void
) => (
<container
loc={[x, 0, 96, 32]}
onClick={() => {
if (!enabled) return;
onClick();
}}
>
<g-rectr
loc={[0, 0, 96, 32]}
circle={[8]}
fill
fillStyle={enabled ? '#2f6fed' : '#26364d'}
alpha={enabled ? 1 : 0.5}
/>
<text loc={[12, 8]} text={label} fillStyle="#ffffff" />
</container>
);
return () => (
<container loc={[0, 0, 304, 32]}>
{makeButton(
0,
props.equipped ? '已装备' : '装备',
props.canEquip,
() => emit('equip')
)}
{makeButton(104, '使用', props.canUse, () => emit('use'))}
{makeButton(208, '关闭', true, () => emit('close'))}
</container>
);
}, actionBarOptions);
const NAMES = [
'红药水',
'蓝药水',
'黄钥匙',
'蓝钥匙',
'木剑',
'木盾',
'红宝石',
'蓝宝石',
'回城卷轴',
'面包'
];
const sourceItems: Item[] = Array.from({ length: 40 }, (_, index) => ({
id: `item-${index + 1}`,
name: NAMES[index % NAMES.length],
count: (index % 6) + 1,
desc: `第 ${index + 1} 个道具。`
}));
const COLUMNS = 5;
const CELL_SIZE = 66;
const GAP = 8;
const ROW_PITCH = CELL_SIZE + GAP;
const VIEW_WIDTH = 372;
const VIEW_HEIGHT = 244;
const ROWS = Math.ceil(sourceItems.length / COLUMNS);
const MAX_START_ROW = Math.max(0, ROWS - Math.floor(VIEW_HEIGHT / ROW_PITCH));
const MAX_SCROLL = MAX_START_ROW * ROW_PITCH;
// 示例(六)的 live:完整背包面板,含动画与关闭 / 重新打开
// InventoryPanel 是唯一注册为 GameUI 的根组件
const InventoryPanel = defineComponent(() => {
const items = ref<Item[]>(sourceItems.map(item => ({ ...item })));
const selectedId = ref('item-1');
const equippedId = ref('');
const hint = ref('选择道具后可以装备或使用');
const scrollTop = ref(0);
const closed = ref(false);
const pulse = ref(0.4);
let raf = 0;
const tick = (now: number) => {
const phase = (now % 1600) / 1600;
pulse.value = 0.35 + Math.sin(phase * Math.PI * 2) * 0.3;
raf = requestAnimationFrame(tick);
};
onMounted(() => {
raf = requestAnimationFrame(tick);
});
onUnmounted(() => {
// 卸载后必须停掉,否则回调会继续访问已销毁的组件
cancelAnimationFrame(raf);
});
const selectedItem = computed(() =>
items.value.find(item => item.id === selectedId.value)
);
const canEquip = computed(() => !!selectedItem.value);
const canUse = computed(
() => !!selectedItem.value && selectedItem.value.count > 0
);
const isEquipped = computed(
() => !!selectedId.value && equippedId.value === selectedId.value
);
const startRow = computed(() => Math.round(scrollTop.value / ROW_PITCH));
const equip = () => {
if (!selectedItem.value) return;
equippedId.value = selectedItem.value.id;
hint.value = `已装备:${selectedItem.value.name}`;
};
const use = () => {
const item = selectedItem.value;
if (!item || item.count <= 0) return;
item.count -= 1;
};
watch(
() => selectedItem.value?.count ?? 0,
(next, prev) => {
hint.value = `数量:${prev} → ${next}`;
}
);
const scrollRows = (delta: number) => {
const current = Math.round(scrollTop.value / ROW_PITCH);
const next = Math.max(0, Math.min(MAX_START_ROW, current + delta));
scrollTop.value = next * ROW_PITCH;
};
const onWheel = (ev: { wheelY: number }) => {
scrollRows(ev.wheelY > 0 ? 1 : -1);
};
const thumbHeight = Math.max(
28,
(VIEW_HEIGHT / (ROWS * ROW_PITCH)) * VIEW_HEIGHT
);
const thumbY =
MAX_SCROLL === 0
? 0
: (scrollTop.value / MAX_SCROLL) * (VIEW_HEIGHT - thumbHeight);
return () => (
<container loc={[0, 0, 720, 480]}>
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
<container loc={[0, 0, 720, 480]} hidden={closed.value}>
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
stroke
strokeStyle="#2f6fed"
/>
{/* 呼吸边框只改 alpha,不每帧重建 */}
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
stroke
strokeStyle="#f2b84b"
alpha={pulse.value * 0.6}
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
<container
loc={[626, 50, 56, 32]}
onClick={() => (closed.value = true)}
>
<g-rectr
loc={[0, 0, 56, 32]}
circle={[8]}
fill
fillStyle="#7a3d3d"
/>
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
</container>
<container loc={[54, 100, 400, 280]}>
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
<container
loc={[0, 0, VIEW_WIDTH, VIEW_HEIGHT]}
onWheel={onWheel}
>
{items.value.map((item, index) => {
const row = Math.floor(index / COLUMNS);
if (
row < startRow.value ||
row >= startRow.value + 4
) {
return null;
}
const col = index % COLUMNS;
return (
<container
key={item.id}
loc={[
col * ROW_PITCH,
(row - startRow.value) * ROW_PITCH
]}
>
<ItemCell
item={item}
selected={item.id === selectedId.value}
equipped={item.id === equippedId.value}
size={CELL_SIZE}
pulse={pulse.value}
onSelect={id => (selectedId.value = id)}
/>
</container>
);
})}
</container>
<g-rect
loc={[378, 0, 6, VIEW_HEIGHT]}
fill
fillStyle="#1b2634"
/>
<g-rectr
loc={[378, thumbY, 6, thumbHeight]}
circle={[3]}
fill
fillStyle="#3f6fa8"
/>
<container
loc={[0, 252, 90, 28]}
onClick={() => scrollRows(-1)}
>
<g-rectr
loc={[0, 0, 90, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[10, 6]} text="上一行" fillStyle="#e8f0ff" />
</container>
<container
loc={[100, 252, 90, 28]}
onClick={() => scrollRows(1)}
>
<g-rectr
loc={[0, 0, 90, 28]}
circle={[6]}
fill
fillStyle="#33465f"
/>
<text loc={[10, 6]} text="下一行" fillStyle="#e8f0ff" />
</container>
<text
loc={[204, 258]}
text={`已滚动 ${scrollTop.value} / ${MAX_SCROLL}`}
fillStyle="#8fb6ff"
/>
</container>
<container loc={[470, 100, 196, 280]}>
<ItemDetail
item={selectedItem.value}
pulse={pulse.value}
onClear={() => (selectedId.value = '')}
/>
</container>
<container loc={[54, 392, 304, 32]}>
<ActionBar
canEquip={canEquip.value}
canUse={canUse.value}
equipped={isEquipped.value}
onEquip={equip}
onUse={use}
onClose={() => (closed.value = true)}
/>
</container>
<text loc={[54, 432]} text={hint.value} fillStyle="#8fb6ff" />
</container>
<container loc={[0, 0, 720, 480]} hidden={!closed.value}>
<text loc={[300, 220]} text="面板已关闭" fillStyle="#e8f0ff" />
<container
loc={[300, 260, 120, 32]}
onClick={() => (closed.value = false)}
>
<g-rectr
loc={[0, 0, 120, 32]}
circle={[8]}
fill
fillStyle="#2f6fed"
/>
<text loc={[18, 8]} text="重新打开" fillStyle="#ffffff" />
</container>
</container>
</container>
);
});
export default InventoryPanel;
@@ -0,0 +1,56 @@
import { defineComponent } from 'vue';
// 同一组重叠图形分别使用 source-over、multiply 与 screen
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="composite 对照" fillStyle="#cfe0ff" />
<text
loc={[24, 48]}
text="默认 source-over,可换成 multiply / screen"
fillStyle="#8b98a8"
/>
<container loc={[25, 76, 140, 150]}>
<g-rect loc={[0, 0, 140, 150]} fillStyle="#1b2430" />
<g-circle circle={[50, 50, 50]} fillStyle="#2f6fed" />
<g-rect
loc={[40, 60, 100, 90]}
fillStyle="#f2b84b"
composite="source-over"
/>
</container>
<container loc={[170, 76, 140, 150]}>
<g-rect loc={[0, 0, 140, 150]} fillStyle="#1b2430" />
<g-circle circle={[50, 50, 50]} fillStyle="#2f6fed" />
<g-rect
loc={[40, 60, 100, 90]}
fillStyle="#f2b84b"
composite="multiply"
/>
</container>
<container loc={[315, 76, 140, 150]}>
<g-rect loc={[0, 0, 140, 150]} fillStyle="#1b2430" />
<g-circle circle={[50, 50, 50]} fillStyle="#2f6fed" />
<g-rect
loc={[40, 60, 100, 90]}
fillStyle="#f2b84b"
composite="screen"
/>
</container>
<text loc={[25, 244]} text="source-over" fillStyle="#8b98a8" />
<text loc={[170, 244]} text="multiply" fillStyle="#8b98a8" />
<text loc={[315, 244]} text="screen" fillStyle="#8b98a8" />
<text
loc={[24, 286]}
text="composite 只影响绘制结果,不改变布局与命中"
fillStyle="#8b98a8"
/>
</container>
);
});
@@ -0,0 +1,38 @@
import { defineComponent } from 'vue';
// 父级缩放,子元素仍按局部坐标描述内容
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="变换沿树传递" fillStyle="#cfe0ff" />
<text
loc={[24, 48]}
text="父级 scale 后,子元素的 loc 不变"
fillStyle="#8b98a8"
/>
{/* 父级放大 1.5 倍,子元素仍写 [0, 0, 140, 100];加 nocache 避免缓存图被重采样 */}
<container loc={[40, 88, 140, 100]} scale={[1.5, 1.5]} nocache>
<g-rect loc={[0, 0, 140, 100]} fill fillStyle="#2f6fed" />
<g-circle circle={[18, 18, 10]} fillStyle="#f2b84b" />
<text loc={[12, 44]} text="子元素" fillStyle="#e8f0ff" />
</container>
{/* 同一棵子树未缩放的参考 */}
<container loc={[290, 88, 140, 100]}>
<g-rect loc={[0, 0, 140, 100]} fill fillStyle="#2f6fed" />
<g-circle circle={[18, 18, 10]} fillStyle="#f2b84b" />
<text loc={[12, 44]} text="子元素" fillStyle="#e8f0ff" />
</container>
<text
loc={[40, 252]}
text="父级 scale [1.5, 1.5]"
fillStyle="#8b98a8"
/>
<text loc={[290, 252]} text="未缩放参考" fillStyle="#8b98a8" />
</container>
);
});
@@ -0,0 +1,101 @@
import { defineComponent } from 'vue';
// 同一变换在左上角锚点与中心锚点下的对比;白点 = 锚点
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 14]}
text="同一变换,不同锚点"
fillStyle="#cfe0ff"
/>
<text
loc={[24, 34]}
text="白点 = 锚点:分别对比绕左上角与绕中心"
fillStyle="#8b98a8"
/>
{/* scale:左上角锚点 */}
<container loc={[12, 52, 224, 124]}>
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
<text
loc={[10, 8]}
text="scale · anc [0, 0]"
fillStyle="#cfe0ff"
/>
<container
loc={[84, 58, 76, 42]}
anc={[0, 0]}
scale={[1.35, 0.7]}
nocache
>
<g-rect loc={[0, 0, 76, 42]} fillStyle="#2f6fed" />
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
</container>
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
</container>
{/* scale:中心锚点 */}
<container loc={[244, 52, 224, 124]}>
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
<text
loc={[10, 8]}
text="scale · anc [0.5, 0.5]"
fillStyle="#cfe0ff"
/>
<container
loc={[84, 58, 76, 42]}
anc={[0.5, 0.5]}
scale={[1.35, 0.7]}
nocache
>
<g-rect loc={[0, 0, 76, 42]} fillStyle="#2f6fed" />
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
</container>
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
</container>
{/* rotate:左上角锚点 */}
<container loc={[12, 180, 224, 124]}>
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
<text
loc={[10, 8]}
text="rotate · anc [0, 0]"
fillStyle="#cfe0ff"
/>
<container
loc={[84, 58, 76, 42]}
anc={[0, 0]}
rotate={Math.PI / 12}
nocache
>
<g-rect loc={[0, 0, 76, 42]} fillStyle="#c58af9" />
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
</container>
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
</container>
{/* rotate:中心锚点 */}
<container loc={[244, 180, 224, 124]}>
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
<text
loc={[10, 8]}
text="rotate · anc [0.5, 0.5]"
fillStyle="#cfe0ff"
/>
<container
loc={[84, 58, 76, 42]}
anc={[0.5, 0.5]}
rotate={Math.PI / 12}
nocache
>
<g-rect loc={[0, 0, 76, 42]} fillStyle="#c58af9" />
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
</container>
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
</container>
</container>
);
});
@@ -0,0 +1,102 @@
import { computed, defineComponent, onUnmounted, ref } from 'vue';
import { GameUI, IUIDefaultPropsBase, UIController } from '@motajs/system';
// 切换 hidden / cache 的小面板,并显示 active / showBack 状态
export default defineComponent(() => {
// 控制器与状态 UI 都在 setup 里创建,卸载时释放
const controller = new UIController<IUIDefaultPropsBase>();
controller.setPropsBaseCreator((instance, ctrl) => ({
instance,
controller: ctrl
}));
// 状态 UI 只负责显示控制器的两个引用值
const StateUI = defineComponent(() => {
return () => (
<container loc={[330, 200, 130, 96]}>
<g-rect loc={[0, 0, 130, 96]} fill fillStyle="#1d2b45" />
<g-rect loc={[0, 0, 130, 96]} stroke strokeStyle="#7aa2ff" />
<text loc={[10, 10]} text="控制器状态" fillStyle="#e8f0ff" />
<text
loc={[10, 40]}
text={`active:${controller.active.value}`}
fillStyle="#8fb6ff"
/>
<text
loc={[10, 64]}
text={`showBack:${controller.showBack.value}`}
fillStyle="#8fb6ff"
/>
</container>
);
});
const stateUI = new GameUI('perf-state', StateUI);
controller.open(stateUI, {});
const Renderer = defineComponent(() => {
return () => controller.render();
});
const visible = ref(true);
const cached = ref(false);
const cacheText = computed(() => (cached.value ? '已开缓存' : '未开缓存'));
onUnmounted(() => {
controller.closeAll();
});
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#141a22" />
<container
loc={[20, 20, 120, 32]}
onClick={() => (visible.value = !visible.value)}
>
<g-rect loc={[0, 0, 120, 32]} fill fillStyle="#2f6fed" />
<text loc={[12, 8]} text="显示 / 隐藏" fillStyle="#ffffff" />
</container>
<container
loc={[150, 20, 120, 32]}
onClick={() => (cached.value = !cached.value)}
>
<g-rect loc={[0, 0, 120, 32]} fill fillStyle="#3a2f5f" />
<text loc={[12, 8]} text="切换缓存" fillStyle="#ffffff" />
</container>
<text loc={[20, 64]} text={cacheText.value} fillStyle="#8fb6ff" />
{/* hidden 控制显示,cache / nocache 控制是否复用离屏画布 */}
<container
loc={[20, 96, 260, 200]}
hidden={!visible.value}
cache={cached.value}
nocache={!cached.value}
>
<g-rect loc={[0, 0, 260, 200]} fill fillStyle="#101820" />
{Array.from({ length: 8 }, (_, index) => (
<container key={index} loc={[12, 12 + index * 22, 236, 18]}>
<g-rect
loc={[0, 0, 236, 18]}
fill
fillStyle={index % 2 === 0 ? '#26364d' : '#1d2b45'}
/>
<text
loc={[8, 2]}
text={`静态内容 ${index + 1}`}
fillStyle="#e8f0ff"
/>
</container>
))}
</container>
<text
loc={[20, 300]}
text="hidden 保留状态;cache 只在内容稳定时才有收益。"
fillStyle="#8fb6ff"
/>
<Renderer />
</container>
);
});
@@ -0,0 +1,25 @@
import { defineComponent } from 'vue';
// 三个同尺寸矩形对比不同的 alpha
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="alpha 对照" fillStyle="#cfe0ff" />
<g-rect loc={[40, 88, 120, 120]} fillStyle="#4f8cff" alpha={1} />
<text loc={[40, 226]} text="alpha 1" fillStyle="#8b98a8" />
<g-rect loc={[180, 88, 120, 120]} fillStyle="#4f8cff" alpha={0.6} />
<text loc={[180, 226]} text="alpha 0.6" fillStyle="#8b98a8" />
<g-rect
loc={[320, 88, 120, 120]}
fillStyle="#4f8cff"
alpha={0.25}
/>
<text loc={[320, 226]} text="alpha 0.25" fillStyle="#8b98a8" />
</container>
);
});
@@ -0,0 +1,42 @@
import { Texture } from '@motajs/render';
import { defineComponent } from 'vue';
// 演示用纹理:16×16 的棋盘格,放大后更容易看出抗锯齿差异
function createPixelTexture() {
const canvas = document.createElement('canvas');
canvas.width = 16;
canvas.height = 16;
const ctx = canvas.getContext('2d')!;
for (let y = 0; y < 16; y++) {
for (let x = 0; x < 16; x++) {
ctx.fillStyle = (x + y) % 2 === 0 ? '#f2b84b' : '#2f6fed';
ctx.fillRect(x, y, 1, 1);
}
}
return new Texture(canvas);
}
const demoTexture = createPixelTexture();
// 同一张纹理放大显示,对照默认抗锯齿与 noanti
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="同一张纹理放大到 160×160"
fillStyle="#cfe0ff"
/>
<image image={demoTexture} loc={[56, 76, 160, 160]} />
<text loc={[56, 250]} text="默认" fillStyle="#8b98a8" />
<image image={demoTexture} noanti loc={[264, 76, 160, 160]} />
<text loc={[264, 250]} text="noanti" fillStyle="#8b98a8" />
</container>
);
});
@@ -0,0 +1,24 @@
import { defineComponent } from 'vue';
// 带 cursor 的区域:鼠标移入后光标变成手型
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="cursor 属性" fillStyle="#cfe0ff" />
<text
loc={[24, 56]}
text="把鼠标移到下面的区域上"
fillStyle="#8b98a8"
/>
<g-rect
loc={[40, 100, 400, 140]}
fillStyle="#2f6fed"
cursor="pointer"
/>
<text loc={[40, 258]} text='cursor="pointer"' fillStyle="#8b98a8" />
</container>
);
});
@@ -0,0 +1,55 @@
import { Texture } from '@motajs/render';
import { defineComponent } from 'vue';
// 演示用纹理:带几种颜色,便于看出灰度与亮度变化
function createDemoTexture() {
const canvas = document.createElement('canvas');
canvas.width = 64;
canvas.height = 64;
const ctx = canvas.getContext('2d')!;
ctx.fillStyle = '#2a3550';
ctx.fillRect(0, 0, 64, 64);
ctx.fillStyle = '#2f6fed';
ctx.fillRect(0, 0, 64, 24);
ctx.fillStyle = '#f2b84b';
ctx.beginPath();
ctx.arc(32, 42, 14, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = '#7ee787';
ctx.fillRect(44, 44, 20, 20);
ctx.fillStyle = '#ffffff';
ctx.fillRect(6, 40, 10, 10);
return new Texture(canvas);
}
const demoTexture = createDemoTexture();
// 同一张图分别使用正常、模糊与灰度滤镜
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="filter 对照" fillStyle="#cfe0ff" />
<image image={demoTexture} loc={[48, 84, 120, 120]} />
<text loc={[48, 218]} text="正常" fillStyle="#8b98a8" />
<image
image={demoTexture}
loc={[180, 84, 120, 120]}
filter="blur(3px)"
/>
<text loc={[180, 218]} text="blur(3px)" fillStyle="#8b98a8" />
<image
image={demoTexture}
loc={[312, 84, 120, 120]}
filter="grayscale(1) brightness(0.7)"
/>
<text loc={[312, 218]} text="灰度 + 亮度" fillStyle="#8b98a8" />
</container>
);
});
@@ -0,0 +1,18 @@
import { defineComponent } from 'vue';
// 两个重叠矩形:先写的蓝色 zIndex 更高,盖在黄色上面
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="zIndex 对照" fillStyle="#cfe0ff" />
<g-rect loc={[80, 88, 200, 140]} fillStyle="#2f6fed" zIndex={2} />
<g-rect loc={[180, 148, 200, 140]} fillStyle="#f2b84b" />
<text loc={[24, 296]} text="蓝色 zIndex 2" fillStyle="#8b98a8" />
<text loc={[300, 296]} text="黄色 zIndex 0" fillStyle="#8b98a8" />
</container>
);
});
@@ -0,0 +1,37 @@
import { computed, defineComponent, ref } from 'vue';
// computed 从 count 派生 doubled,不需要另外维护一份状态
export default defineComponent(() => {
const count = ref(0);
const doubled = computed(() => count.value * 2);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[40, 36]}
text="count 变化后 doubled 自动重算"
fillStyle="#cfe0ff"
/>
<g-rect
loc={[40, 96, 180, 56]}
fillStyle="#2f6fed"
onClick={() => count.value++}
/>
<text loc={[64, 114]} text="点我 +1" fillStyle="#e8f0ff" noevent />
<text
loc={[260, 104]}
text={`count = ${count.value}`}
fillStyle="#ffffff"
/>
<text
loc={[260, 140]}
text={`doubled = ${doubled.value}`}
fillStyle="#f2b84b"
/>
</container>
);
});
@@ -0,0 +1,31 @@
import { defineComponent, ref } from 'vue';
// 计数器:点击按钮只改 count,文字由响应式自动更新
export default defineComponent(() => {
const count = ref(0);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[40, 36]}
text="点击按钮改变 count"
fillStyle="#cfe0ff"
/>
<g-rect
loc={[40, 96, 180, 56]}
fillStyle="#2f6fed"
onClick={() => count.value++}
/>
<text loc={[64, 114]} text="点我 +1" fillStyle="#e8f0ff" noevent />
<text
loc={[260, 112]}
text={`count = ${count.value}`}
fillStyle="#ffffff"
/>
</container>
);
});
@@ -0,0 +1,42 @@
import { defineComponent, reactive } from 'vue';
// reactive 代理对象:逐字段修改,标题与开关一起更新
export default defineComponent(() => {
const panel = reactive({
open: true,
title: '背包'
});
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[40, 36]}
text="点击切换 open 与 title"
fillStyle="#cfe0ff"
/>
<g-rect
loc={[40, 96, 180, 56]}
fillStyle="#2f6fed"
onClick={() => {
panel.open = !panel.open;
panel.title = panel.open ? '背包' : '道具';
}}
/>
<text loc={[64, 114]} text="切换" fillStyle="#e8f0ff" noevent />
<text
loc={[260, 104]}
text={`open = ${panel.open}`}
fillStyle="#ffffff"
/>
<text
loc={[260, 140]}
text={`title = ${panel.title}`}
fillStyle="#f2b84b"
/>
</container>
);
});
@@ -0,0 +1,36 @@
import { defineComponent, ref, watch } from 'vue';
// watch 监听 count,变化后把新旧值写进 log
export default defineComponent(() => {
const count = ref(0);
const log = ref('还没有变化');
watch(count, (next, prev) => {
log.value = `count:${prev} → ${next}`;
});
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[40, 36]}
text="count 变化后 watch 写日志"
fillStyle="#cfe0ff"
/>
<g-rect
loc={[40, 96, 180, 56]}
fillStyle="#2f6fed"
onClick={() => count.value++}
/>
<text loc={[64, 114]} text="点我 +1" fillStyle="#e8f0ff" noevent />
<text
loc={[260, 112]}
text={`log = ${log.value}`}
fillStyle="#7ee787"
/>
</container>
);
});
@@ -0,0 +1,55 @@
import { defineComponent } from 'vue';
// 八种图形放在一起:矩形、圆、椭圆、直线、三次贝塞尔、二次贝塞尔、路径、圆角矩形
export default defineComponent(() => {
const badge = new Path2D();
badge.moveTo(300, 205);
badge.lineTo(345, 230);
badge.lineTo(333, 280);
badge.lineTo(267, 280);
badge.lineTo(255, 230);
badge.closePath();
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 14]} text="八种图形" fillStyle="#e8f0ff" />
<g-rect loc={[20, 72, 80, 62]} fillStyle="#2f6fed" />
<g-circle circle={[180, 103, 34]} fillStyle="#58c4dd" />
<g-ellipse ellipse={[300, 103, 50, 32]} fillStyle="#c58af9" />
<g-line
line={[370, 133, 460, 75]}
strokeStyle="#7ee787"
lineWidth={4}
/>
<g-bezier
curve={[20, 275, 45, 205, 80, 280, 105, 212]}
strokeStyle="#f2b84b"
lineWidth={4}
/>
<g-quad
curve={[140, 270, 180, 205, 220, 270]}
strokeStyle="#58c4dd"
lineWidth={4}
/>
<g-path path={badge} fillStyle="#7ee787" />
<g-rectr
loc={[370, 215, 80, 62]}
circle={[24]}
fillStyle="#f2b84b"
/>
<text loc={[44, 146]} text="矩形" fillStyle="#cfe0ff" />
<text loc={[170, 146]} text="圆" fillStyle="#cfe0ff" />
<text loc={[285, 146]} text="椭圆" fillStyle="#cfe0ff" />
<text loc={[405, 146]} text="直线" fillStyle="#cfe0ff" />
<text loc={[20, 292]} text="三次贝塞尔" fillStyle="#cfe0ff" />
<text loc={[140, 292]} text="二次贝塞尔" fillStyle="#cfe0ff" />
<text loc={[290, 292]} text="路径" fillStyle="#cfe0ff" />
<text loc={[380, 292]} text="圆角矩形" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,129 @@
import { defineComponent } from 'vue';
// 三次贝塞尔:curve 依次是起点、两个控制点、终点
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="三次贝塞尔:白点 = 控制点,虚线 = 控制多边形"
fillStyle="#e8f0ff"
/>
{/* 控制多边形:起点 → cp1 → cp2 → 终点 */}
<g-line
line={[30, 110, 70, 85]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[70, 85, 135, 90]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[135, 90, 205, 120]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[255, 110, 300, 60]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[300, 60, 395, 65]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[395, 65, 450, 120]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[30, 235, 125, 215]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[125, 215, 110, 255]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[110, 255, 205, 235]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[255, 235, 330, 205]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[330, 205, 380, 265]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[380, 265, 450, 235]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-bezier
curve={[30, 110, 70, 85, 135, 90, 205, 120]}
strokeStyle="#f2b84b"
lineWidth={4}
/>
<g-bezier
curve={[255, 110, 300, 60, 395, 65, 450, 120]}
strokeStyle="#f2b84b"
lineWidth={4}
/>
<g-bezier
curve={[30, 235, 125, 215, 110, 255, 205, 235]}
strokeStyle="#f2b84b"
lineWidth={4}
/>
<g-bezier
curve={[255, 235, 330, 205, 380, 265, 450, 235]}
strokeStyle="#f2b84b"
lineWidth={4}
/>
{/* 每个控制点用白色小圆点标出 */}
<g-circle circle={[70, 85, 4]} fillStyle="#ffffff" />
<g-circle circle={[135, 90, 4]} fillStyle="#ffffff" />
<g-circle circle={[300, 60, 4]} fillStyle="#ffffff" />
<g-circle circle={[395, 65, 4]} fillStyle="#ffffff" />
<g-circle circle={[125, 215, 4]} fillStyle="#ffffff" />
<g-circle circle={[110, 255, 4]} fillStyle="#ffffff" />
<g-circle circle={[330, 205, 4]} fillStyle="#ffffff" />
<g-circle circle={[380, 265, 4]} fillStyle="#ffffff" />
<text loc={[30, 145]} text="控制点靠近" fillStyle="#cfe0ff" />
<text loc={[270, 145]} text="控制点拉远" fillStyle="#cfe0ff" />
<text loc={[30, 292]} text="控制点交叉" fillStyle="#cfe0ff" />
<text loc={[270, 292]} text="S 形" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,48 @@
import { defineComponent } from 'vue';
// 圆:用 circle 简写给出圆心与半径
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="圆:半径、圆心与 start / end"
fillStyle="#e8f0ff"
/>
<g-circle circle={[80, 100, 30]} fillStyle="#58c4dd" />
<g-circle circle={[210, 100, 55]} fillStyle="#58c4dd" />
<g-circle circle={[350, 100, 80]} fillStyle="#58c4dd" />
<text loc={[65, 190]} text="r=30" fillStyle="#cfe0ff" />
<text loc={[188, 190]} text="r=55" fillStyle="#cfe0ff" />
<text loc={[323, 190]} text="r=80" fillStyle="#cfe0ff" />
<g-circle circle={[90, 255, 35, 0, Math.PI]} fillStyle="#58c4dd" />
<g-circle
circle={[240, 255, 35, Math.PI / 2, Math.PI * 1.5]}
stroke
strokeStyle="#58c4dd"
lineWidth={4}
/>
<g-circle
circle={[390, 255, 35, 0, Math.PI * 1.5]}
fill
stroke
fillStyle="#58c4dd"
strokeStyle="#e8f0ff"
lineWidth={3}
/>
<text loc={[15, 298]} text="fill 0°→180°" fillStyle="#cfe0ff" />
<text loc={[155, 298]} text="stroke 90°→270°" fillStyle="#cfe0ff" />
<text
loc={[310, 298]}
text="fill+stroke 0°→270°"
fillStyle="#cfe0ff"
/>
</container>
);
});
@@ -0,0 +1,55 @@
import { defineComponent } from 'vue';
// 椭圆:用 ellipse 简写给出圆心、横向半径与纵向半径
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="椭圆:rx / ry 与 start / end"
fillStyle="#e8f0ff"
/>
<g-ellipse ellipse={[100, 95, 70, 30]} fillStyle="#c58af9" />
<g-ellipse ellipse={[250, 95, 90, 42]} fillStyle="#c58af9" />
<g-ellipse ellipse={[400, 95, 55, 25]} fillStyle="#c58af9" />
<text loc={[55, 150]} text="rx=70 ry=30" fillStyle="#cfe0ff" />
<text loc={[200, 150]} text="rx=90 ry=42" fillStyle="#cfe0ff" />
<text loc={[355, 150]} text="rx=55 ry=25" fillStyle="#cfe0ff" />
<g-ellipse
ellipse={[90, 230, 60, 35, 0, Math.PI]}
fillStyle="#c58af9"
/>
<g-ellipse
ellipse={[240, 230, 60, 35, Math.PI, Math.PI * 2]}
stroke
strokeStyle="#c58af9"
lineWidth={4}
/>
<g-ellipse
ellipse={[390, 230, 60, 35, 0, Math.PI]}
fill
stroke
fillStyle="#c58af9"
strokeStyle="#e8f0ff"
lineWidth={3}
/>
<text loc={[30, 298]} text="fill 0°→180°" fillStyle="#cfe0ff" />
<text
loc={[172, 298]}
text="stroke 180°→360°"
fillStyle="#cfe0ff"
/>
<text
loc={[320, 298]}
text="fill+stroke 0°→180°"
fillStyle="#cfe0ff"
/>
</container>
);
});
@@ -0,0 +1,43 @@
import { defineComponent } from 'vue';
// 直线:用 line 简写给出两个端点,默认描边
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="直线:端点、线宽、虚线与颜色"
fillStyle="#e8f0ff"
/>
<g-line
line={[40, 80, 210, 80]}
strokeStyle="#7ee787"
lineWidth={2}
/>
<g-line
line={[260, 80, 440, 80]}
strokeStyle="#58c4dd"
lineWidth={14}
/>
<g-line
line={[40, 185, 210, 185]}
strokeStyle="#f2b84b"
lineWidth={4}
lineDash={[18, 12]}
/>
<g-line
line={[260, 240, 440, 170]}
strokeStyle="#c58af9"
lineWidth={6}
/>
<text loc={[40, 96]} text="细 lineWidth=2" fillStyle="#cfe0ff" />
<text loc={[260, 110]} text="粗 lineWidth=14" fillStyle="#cfe0ff" />
<text loc={[40, 203]} text="虚线 lineDash" fillStyle="#cfe0ff" />
<text loc={[260, 254]} text="斜线,改端点" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,40 @@
import { defineComponent } from 'vue';
// 绘制模式:同一个矩形分别用 fill、stroke、fill + stroke 与 strokeAndFill
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 16]} text="四种绘制模式" fillStyle="#e8f0ff" />
<text loc={[40, 48]} text="fill" fillStyle="#cfe0ff" />
<text loc={[260, 48]} text="stroke" fillStyle="#cfe0ff" />
<text loc={[40, 180]} text="fill + stroke" fillStyle="#cfe0ff" />
<text loc={[260, 180]} text="strokeAndFill" fillStyle="#cfe0ff" />
<g-rect loc={[40, 84, 180, 80]} fillStyle="#2f6fed" />
<g-rect
loc={[260, 84, 180, 80]}
stroke
strokeStyle="#7ee787"
lineWidth={10}
/>
<g-rect
loc={[40, 218, 180, 80]}
fill
stroke
fillStyle="#2f6fed"
strokeStyle="#f2b84b"
lineWidth={14}
/>
<g-rect
loc={[260, 218, 180, 80]}
strokeAndFill
fillStyle="#2f6fed"
strokeStyle="#f2b84b"
lineWidth={14}
/>
</container>
);
});
@@ -0,0 +1,45 @@
import { defineComponent } from 'vue';
// 路径:path 接收一个 Path2D,默认填充
export default defineComponent(() => {
const polyline = new Path2D();
polyline.moveTo(40, 230);
polyline.lineTo(85, 140);
polyline.lineTo(125, 215);
polyline.lineTo(160, 150);
const polygon = new Path2D();
polygon.moveTo(195, 230);
polygon.lineTo(285, 230);
polygon.lineTo(240, 135);
polygon.closePath();
const arc = new Path2D();
arc.moveTo(455, 180);
arc.arc(390, 180, 65, 0, Math.PI * 1.5);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="路径:折线、闭合填充与圆弧"
fillStyle="#e8f0ff"
/>
<g-path
path={polyline}
stroke
strokeStyle="#58c4dd"
lineWidth={3}
/>
<g-path path={polygon} fillStyle="#7ee787" />
<g-path path={arc} stroke strokeStyle="#f2b84b" lineWidth={3} />
<text loc={[50, 285]} text="折线" fillStyle="#cfe0ff" />
<text loc={[205, 285]} text="闭合填充" fillStyle="#cfe0ff" />
<text loc={[374, 285]} text="圆弧" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,101 @@
import { defineComponent } from 'vue';
// 二次贝塞尔:curve 依次是起点、控制点、终点
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="二次贝塞尔:白点 = 控制点,虚线 = 控制多边形"
fillStyle="#e8f0ff"
/>
{/* 控制多边形:起点 → 控制点 → 终点 */}
<g-line
line={[30, 110, 120, 65]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[120, 65, 210, 110]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[255, 110, 345, 155]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[345, 155, 450, 110]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[100, 270, 85, 250]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[85, 250, 210, 270]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[260, 270, 395, 250]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-line
line={[395, 250, 370, 270]}
strokeStyle="#8a94a6"
lineWidth={1}
lineDash={[4, 4]}
/>
<g-quad
curve={[30, 110, 120, 65, 210, 110]}
strokeStyle="#58c4dd"
lineWidth={4}
/>
<g-quad
curve={[255, 110, 345, 155, 450, 110]}
strokeStyle="#58c4dd"
lineWidth={4}
/>
<g-quad
curve={[100, 270, 85, 250, 210, 270]}
strokeStyle="#58c4dd"
lineWidth={4}
/>
<g-quad
curve={[260, 270, 395, 250, 370, 270]}
strokeStyle="#58c4dd"
lineWidth={4}
/>
{/* 每个控制点用白色小圆点标出 */}
<g-circle circle={[120, 65, 4]} fillStyle="#ffffff" />
<g-circle circle={[345, 155, 4]} fillStyle="#ffffff" />
<g-circle circle={[85, 250, 4]} fillStyle="#ffffff" />
<g-circle circle={[395, 250, 4]} fillStyle="#ffffff" />
<text loc={[30, 145]} text="控制点在上" fillStyle="#cfe0ff" />
<text loc={[270, 145]} text="控制点在下" fillStyle="#cfe0ff" />
<text loc={[30, 292]} text="控制点在左" fillStyle="#cfe0ff" />
<text loc={[270, 292]} text="控制点在右" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,26 @@
import { defineComponent } from 'vue';
// 矩形:用 loc 简写给出左上角与宽高
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="矩形:改 loc 对比位置与宽高"
fillStyle="#e8f0ff"
/>
<g-rect loc={[50, 70, 70, 55]} fillStyle="#2f6fed" />
<g-rect loc={[250, 70, 170, 55]} fillStyle="#2f6fed" />
<g-rect loc={[50, 170, 70, 95]} fillStyle="#2f6fed" />
<g-rect loc={[250, 170, 170, 95]} fillStyle="#2f6fed" />
<text loc={[50, 135]} text="小 70×55" fillStyle="#cfe0ff" />
<text loc={[250, 135]} text="宽 170×55" fillStyle="#cfe0ff" />
<text loc={[50, 275]} text="高 70×95" fillStyle="#cfe0ff" />
<text loc={[250, 275]} text="大 170×95" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,50 @@
import { defineComponent } from 'vue';
// 圆角矩形:circle 给圆形圆角,ellipse 给椭圆圆角
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 20]}
text="圆角矩形:不同圆角写法对比"
fillStyle="#e8f0ff"
/>
<g-rectr
loc={[60, 60, 130, 90]}
circle={[24]}
fillStyle="#2f6fed"
/>
<g-rectr
loc={[290, 60, 130, 90]}
circle={[36, 0, 36, 0]}
fillStyle="#58c4dd"
/>
<g-rectr
loc={[60, 192, 130, 90]}
ellipse={[50, 24]}
fillStyle="#c58af9"
/>
<g-rectr
loc={[290, 192, 130, 90]}
circle={[90]}
fillStyle="#f2b84b"
/>
<text loc={[60, 163]} text="1 项 circle=[24]" fillStyle="#cfe0ff" />
<text
loc={[270, 163]}
text="4 项 [36,0,36,0]"
fillStyle="#cfe0ff"
/>
<text loc={[60, 294]} text="ellipse=[50,24]" fillStyle="#cfe0ff" />
<text
loc={[290, 294]}
text="大半径 circle=[90]"
fillStyle="#cfe0ff"
/>
</container>
);
});
@@ -0,0 +1,127 @@
import { defineComponent } from 'vue';
// 描边:线宽、虚线、端点与拐角四组对比
export default defineComponent(() => {
const joinMiter = new Path2D();
joinMiter.moveTo(275, 210);
joinMiter.lineTo(300, 268);
joinMiter.lineTo(325, 210);
const joinRound = new Path2D();
joinRound.moveTo(345, 210);
joinRound.lineTo(370, 268);
joinRound.lineTo(395, 210);
const joinBevel = new Path2D();
joinBevel.moveTo(415, 210);
joinBevel.lineTo(440, 268);
joinBevel.lineTo(465, 210);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[24, 16]}
text="描边:线宽、虚线、端点与拐角"
fillStyle="#e8f0ff"
/>
{/* 线宽 */}
<text loc={[30, 48]} text="线宽 lineWidth" fillStyle="#cfe0ff" />
<g-line
line={[30, 80, 200, 80]}
strokeStyle="#7ee787"
lineWidth={2}
/>
<g-line
line={[30, 110, 200, 110]}
strokeStyle="#7ee787"
lineWidth={6}
/>
<g-line
line={[30, 140, 200, 140]}
strokeStyle="#7ee787"
lineWidth={12}
/>
<text loc={[214, 72]} text="2" fillStyle="#cfe0ff" />
<text loc={[214, 102]} text="6" fillStyle="#cfe0ff" />
<text loc={[214, 132]} text="12" fillStyle="#cfe0ff" />
{/* 虚线 */}
<text loc={[240, 48]} text="虚线 lineDash" fillStyle="#cfe0ff" />
<g-line
line={[340, 80, 456, 80]}
strokeStyle="#58c4dd"
lineWidth={3}
lineDash={[8, 6]}
/>
<g-line
line={[340, 110, 456, 110]}
strokeStyle="#58c4dd"
lineWidth={3}
lineDash={[2, 6]}
/>
<g-line
line={[340, 140, 456, 140]}
strokeStyle="#58c4dd"
lineWidth={3}
lineDash={[16, 6, 2, 6]}
/>
<text loc={[240, 72]} text="8,6" fillStyle="#cfe0ff" />
<text loc={[240, 102]} text="2,6" fillStyle="#cfe0ff" />
<text loc={[240, 132]} text="16,6,2,6" fillStyle="#cfe0ff" />
{/* 端点 */}
<text loc={[30, 168]} text="端点 lineCap" fillStyle="#cfe0ff" />
<g-line
line={[105, 210, 210, 210]}
strokeStyle="#f2b84b"
lineWidth={16}
lineCap="butt"
/>
<g-line
line={[105, 245, 210, 245]}
strokeStyle="#f2b84b"
lineWidth={16}
lineCap="round"
/>
<g-line
line={[105, 280, 210, 280]}
strokeStyle="#f2b84b"
lineWidth={16}
lineCap="square"
/>
<text loc={[30, 202]} text="butt" fillStyle="#cfe0ff" />
<text loc={[30, 237]} text="round" fillStyle="#cfe0ff" />
<text loc={[30, 272]} text="square" fillStyle="#cfe0ff" />
{/* 拐角 */}
<text loc={[260, 168]} text="拐角 lineJoin" fillStyle="#cfe0ff" />
<g-path
path={joinMiter}
stroke
strokeStyle="#c58af9"
lineWidth={14}
lineJoin="miter"
/>
<g-path
path={joinRound}
stroke
strokeStyle="#c58af9"
lineWidth={14}
lineJoin="round"
/>
<g-path
path={joinBevel}
stroke
strokeStyle="#c58af9"
lineWidth={14}
lineJoin="bevel"
/>
<text loc={[277, 296]} text="miter" fillStyle="#cfe0ff" />
<text loc={[347, 296]} text="round" fillStyle="#cfe0ff" />
<text loc={[417, 296]} text="bevel" fillStyle="#cfe0ff" />
</container>
);
});
@@ -0,0 +1,25 @@
import { defineComponent } from 'vue';
// 静态界面演示:容器、背景、标题、矩形、圆、分隔线与层级
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
{/* 深色底:用一块和容器等大的矩形铺出来 */}
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
{/* 标题 */}
<text loc={[24, 24]} text="背包" fillStyle="#e8f0ff" />
{/* 矩形与圆 */}
<g-rect loc={[24, 64, 160, 64]} fillStyle="#2f6fed" />
<g-circle circle={[280, 96, 32]} fillStyle="#58c4dd" />
{/* 分隔线 */}
<g-line line={[24, 168, 456, 168]} strokeStyle="#7aa7ff" />
{/* 层级:第一个 zIndex 更大,重叠处在上面 */}
<g-rect loc={[320, 120, 120, 72]} fillStyle="#f2b84b" zIndex={2} />
<g-rect loc={[368, 152, 120, 72]} fillStyle="#58c4dd" />
</container>
);
});
@@ -0,0 +1,208 @@
import { computed, defineComponent, onUnmounted } from 'vue';
import {
GameUI,
IUIDefaultPropsBase,
IUIInstance,
UIController
} from '@motajs/system';
// 策略演示:四个面板分别放在左右两个控制器里
interface PanelLoc {
x: number;
y: number;
width: number;
height: number;
color: string;
label: string;
}
// 生成一个固定位置的演示面板,两个策略各用两份
const makePanel = (options: PanelLoc) => {
const { x, y, width, height, color, label } = options;
return defineComponent(() => {
return () => (
<container loc={[x, y, width, height]}>
<g-rect loc={[0, 0, width, height]} fill fillStyle={color} />
<g-rect
loc={[0, 0, width, height]}
stroke
strokeStyle="#ffffff"
/>
<text loc={[12, 12]} text={label} fillStyle="#ffffff" />
</container>
);
});
};
// 每个面板都是一个独立 GameUI,打开时按策略压栈
const leftBottomUI = new GameUI(
'strategy-left-bottom',
makePanel({
x: 20,
y: 110,
width: 200,
height: 130,
color: '#2f6fed',
label: '底层 A'
})
);
const leftTopUI = new GameUI(
'strategy-left-top',
makePanel({
x: 70,
y: 160,
width: 200,
height: 130,
color: '#3a2f5f',
label: '上层 B'
})
);
const rightBottomUI = new GameUI(
'strategy-right-bottom',
makePanel({
x: 260,
y: 110,
width: 200,
height: 130,
color: '#2f6fed',
label: '底层 A'
})
);
const rightTopUI = new GameUI(
'strategy-right-top',
makePanel({
x: 310,
y: 160,
width: 200,
height: 130,
color: '#3a2f5f',
label: '上层 B'
})
);
const leftController = new UIController<IUIDefaultPropsBase>();
leftController.setPropsBaseCreator((instance, ctrl) => ({
instance,
controller: ctrl
}));
// 左边:只显示最后一个
leftController.lastOnly();
const rightController = new UIController<IUIDefaultPropsBase>();
rightController.setPropsBaseCreator((instance, ctrl) => ({
instance,
controller: ctrl
}));
// 右边:显示全部
rightController.showAll();
const LeftRenderer = defineComponent(() => {
return () => leftController.render();
});
const RightRenderer = defineComponent(() => {
return () => rightController.render();
});
export default defineComponent(() => {
let leftBottom: IUIInstance | null = null;
let leftTop: IUIInstance | null = null;
let rightBottom: IUIInstance | null = null;
let rightTop: IUIInstance | null = null;
const leftCount = computed(() => leftController.stack.length);
const rightCount = computed(() => rightController.stack.length);
// 打开与关闭都直接调用对应控制器
const openLeftBottom = () => {
if (!leftBottom) {
leftBottom = leftController.open(leftBottomUI, {});
}
};
const openLeftTop = () => {
if (!leftTop) {
leftTop = leftController.open(leftTopUI, {});
}
};
const openRightBottom = () => {
if (!rightBottom) {
rightBottom = rightController.open(rightBottomUI, {});
}
};
const openRightTop = () => {
if (!rightTop) {
rightTop = rightController.open(rightTopUI, {});
}
};
const closeLeft = () => {
leftController.closeAll();
leftBottom = null;
leftTop = null;
};
const closeRight = () => {
rightController.closeAll();
rightBottom = null;
rightTop = null;
};
onUnmounted(() => {
leftController.closeAll();
rightController.closeAll();
});
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#141a22" />
<text
loc={[20, 16]}
text="只显示最后一个(lastOnly)"
fillStyle="#e8f0ff"
/>
<container loc={[20, 44, 80, 32]} onClick={openLeftBottom}>
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#2f6fed" />
<text loc={[12, 8]} text="打开 A" fillStyle="#ffffff" />
</container>
<container loc={[110, 44, 80, 32]} onClick={openLeftTop}>
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#3a2f5f" />
<text loc={[12, 8]} text="打开 B" fillStyle="#ffffff" />
</container>
<container loc={[200, 44, 80, 32]} onClick={closeLeft}>
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#7a3d3d" />
<text loc={[12, 8]} text="清空" fillStyle="#ffffff" />
</container>
<text
loc={[20, 84]}
text={`栈长度:${leftCount.value}`}
fillStyle="#8fb6ff"
/>
<text
loc={[260, 16]}
text="显示全部(showAll)"
fillStyle="#e8f0ff"
/>
<container loc={[260, 44, 80, 32]} onClick={openRightBottom}>
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#2f6fed" />
<text loc={[12, 8]} text="打开 A" fillStyle="#ffffff" />
</container>
<container loc={[350, 44, 80, 32]} onClick={openRightTop}>
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#3a2f5f" />
<text loc={[12, 8]} text="打开 B" fillStyle="#ffffff" />
</container>
<container loc={[260, 76, 80, 32]} onClick={closeRight}>
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#7a3d3d" />
<text loc={[12, 8]} text="清空" fillStyle="#ffffff" />
</container>
<text
loc={[360, 84]}
text={`栈长度:${rightCount.value}`}
fillStyle="#8fb6ff"
/>
<LeftRenderer />
<RightRenderer />
</container>
);
});
@@ -0,0 +1,12 @@
import { defineComponent } from 'vue';
// 最小 UI 模板的 live 版本:一个背景矩形加一行文字
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
{/* 背景矩形先铺满整块画布,避免文字落在透明区域 */}
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#1d2b45" />
<text loc={[24, 24]} text="我的第一个 UI" fillStyle="#e8f0ff" />
</container>
);
});
@@ -0,0 +1,42 @@
import { defineComponent } from 'vue';
// 三行文字分别用不同锚点,白点标出 loc 的位置
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[24, 20]} text="白点 = loc 的位置" fillStyle="#cfe0ff" />
{/* anc=[0, 0]:loc 是文字左上角 */}
<text loc={[40, 56]} text="anc=[0, 0]" fillStyle="#8b98a8" />
<text
loc={[160, 60]}
anc={[0, 0]}
text="左对齐"
fillStyle="#ffffff"
/>
<g-circle circle={[160, 60, 5]} fillStyle="#ffffff" />
{/* anc=[0.5, 0.5]:loc 是文字中心 */}
<text loc={[40, 146]} text="anc=[0.5, 0.5]" fillStyle="#8b98a8" />
<text
loc={[280, 150]}
anc={[0.5, 0.5]}
text="居中"
fillStyle="#58c4dd"
/>
<g-circle circle={[280, 150, 5]} fillStyle="#ffffff" />
{/* anc=[1, 0]:loc 是文字右边缘 */}
<text loc={[40, 246]} text="anc=[1, 0]" fillStyle="#8b98a8" />
<text
loc={[420, 250]}
anc={[1, 0]}
text="右对齐"
fillStyle="#f2b84b"
/>
<g-circle circle={[420, 250, 5]} fillStyle="#ffffff" />
</container>
);
});
@@ -0,0 +1,13 @@
import { defineComponent } from 'vue';
// 最基本的一行文字:内容写在 text,位置由 loc 决定
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[40, 60]} text="一行文字" fillStyle="#ffffff" />
<text loc={[40, 110]} text="第二行文字" fillStyle="#58c4dd" />
</container>
);
});
@@ -0,0 +1,41 @@
import { Font, FontWeight } from '@motajs/render';
import { defineComponent } from 'vue';
// 同内容不同字号、字重与斜体的对照
export default defineComponent(() => {
const small = new Font('Verdana', 14, 'px', FontWeight.Normal);
const bold = new Font('Verdana', 20, 'px', FontWeight.Bold);
const italic = new Font('Verdana', 24, 'px', FontWeight.Normal, true);
const title = new Font('Verdana', 32, 'px', FontWeight.Bold);
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text
loc={[32, 40]}
text="14px 常规文字"
font={small}
fillStyle="#ffffff"
/>
<text
loc={[32, 80]}
text="20px 粗体文字"
font={bold}
fillStyle="#58c4dd"
/>
<text
loc={[32, 124]}
text="24px 斜体文字"
font={italic}
fillStyle="#f2b84b"
/>
<text
loc={[32, 176]}
text="32px 粗体标题"
font={title}
fillStyle="#e8f0ff"
/>
</container>
);
});
@@ -0,0 +1,27 @@
import { defineComponent } from 'vue';
// 填充、描边颜色与描边宽度的对照
export default defineComponent(() => {
return () => (
<container loc={[0, 0, 480, 320]}>
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
<text loc={[32, 50]} text="白色填充" fillStyle="#ffffff" />
<text loc={[32, 104]} text="蓝色填充" fillStyle="#58c4dd" />
<text
loc={[32, 158]}
text="填充 + 描边 2"
fillStyle="#ffffff"
strokeStyle="#f2b84b"
strokeWidth={2}
/>
<text
loc={[32, 222]}
text="填充 + 描边 6"
fillStyle="#ffffff"
strokeStyle="#c58af9"
strokeWidth={6}
/>
</container>
);
});
+23 -2
View File
@@ -1,6 +1,16 @@
<template>
<div :style="{ background: props.background, overflow: 'hidden' }">
<canvas ref="canvasRef"></canvas>
<div
:style="{
background: props.background,
overflow: 'hidden',
display: 'flex',
justifyContent: 'center'
}"
>
<canvas
ref="canvasRef"
:style="{ display: 'block', flex: 'none' }"
></canvas>
</div>
</template>
@@ -82,3 +92,14 @@ onUnmounted(() => {
dispose = null;
});
</script>
<style>
.motajs-input-element {
left: 0;
top: 0;
position: fixed;
border: none;
z-index: 1000;
background-color: transparent;
}
</style>
+157
View File
@@ -12,6 +12,7 @@ const custom = [
'shader',
'comment',
'custom-container',
'container-custom',
'map-render',
'animate',
'damage',
@@ -252,6 +253,162 @@ export default defineConfig({
{
text: '怪物上下文与战斗深入',
link: '/advanced/ii/enemy-context-and-combat'
},
{
text: '自定义 UI 与渲染',
collapsed: true,
items: [
{
text: '起步',
collapsed: false,
items: [
{
text: 'UI 通用模板(TSX)',
link: '/advanced/ii/ui/ui-template'
},
{
text: 'UI 入门',
link: '/advanced/ii/ui/ui-basics'
},
{
text: '第一个静态界面',
link: '/advanced/ii/ui/first-static-ui'
}
]
},
{
text: '元素与布局',
collapsed: false,
items: [
{
text: '容器与坐标',
link: '/advanced/ii/ui/container-and-coordinates'
},
{
text: '基础图形',
link: '/advanced/ii/ui/basic-shapes'
},
{
text: '文字',
link: '/advanced/ii/ui/text'
},
{
text: '图片与纹理',
link: '/advanced/ii/ui/image-and-texture'
},
{
text: '自绘元素与自定义容器',
link: '/advanced/ii/ui/custom-and-container-custom'
},
{
text: '通用参数',
link: '/advanced/ii/ui/common-props'
},
{
text: '层级、变换与性能',
link: '/advanced/ii/ui/layer-transform-performance'
}
]
},
{
text: '交互与数据',
collapsed: false,
items: [
{
text: '响应式',
link: '/advanced/ii/ui/reactivity'
},
{
text: '事件与交互',
link: '/advanced/ii/ui/events'
},
{
text: '条件渲染与循环渲染',
link: '/advanced/ii/ui/conditional-and-list-rendering'
},
{
text: '按键与快捷键',
link: '/advanced/ii/ui/hotkey-in-ui'
}
]
},
{
text: '组件化',
collapsed: false,
items: [
{
text: '什么是组件',
link: '/advanced/ii/ui/what-is-component'
},
{
text: '内置组件:基础',
link: '/advanced/ii/ui/builtin-basic'
},
{
text: '内置组件:布局',
link: '/advanced/ii/ui/builtin-layout'
},
{
text: '内置组件:文本',
link: '/advanced/ii/ui/builtin-text'
},
{
text: '自定义组件',
link: '/advanced/ii/ui/custom-components'
}
]
},
{
text: 'UI 系统',
collapsed: false,
items: [
{
text: 'UI 系统',
link: '/advanced/ii/ui/ui-system'
}
]
},
{
text: '性能',
collapsed: false,
items: [
{
text: 'UI 性能',
link: '/advanced/ii/ui/ui-performance'
}
]
},
{
text: '完整示例',
collapsed: false,
items: [
{
text: '示例(一)目标与骨架',
link: '/advanced/ii/ui/inventory-example-1-skeleton'
},
{
text: '示例(二)道具网格',
link: '/advanced/ii/ui/inventory-example-2-grid'
},
{
text: '示例(三)详情区',
link: '/advanced/ii/ui/inventory-example-3-detail'
},
{
text: '示例(四)滚动与列表',
link: '/advanced/ii/ui/inventory-example-4-scroll'
},
{
text: '示例(五)交互与状态',
link: '/advanced/ii/ui/inventory-example-5-state'
},
{
text: '示例(六)动画、拆分与注册',
link: '/advanced/ii/ui/inventory-example-6-animation-and-register'
}
]
}
]
}
]
},
+6 -3
View File
@@ -12,7 +12,7 @@
- 认真阅读样板后,能把一部分简单系统和中等复杂度的系统读明白;
- 想把某个具体系统改成自己的规则,而不只是调用现成接口。
这一层不预设你是资深引擎开发者,也不要求通读引擎源码。它要求的是能跟着样板找到改动点,并判断改动会不会影响存档与录像。这里仍然只写数据端;引擎编写者的内容属于高级 III。
这一层不预设你是资深引擎开发者,也不要求通读引擎源码。它要求的是能跟着样板找到改动点,并判断改动会不会影响存档与录像。这一层的主体是数据端;另有自定义 UI 与渲染子分组(见侧边栏),面向要在画布上写界面的作者。
## 难度层定位
@@ -49,7 +49,9 @@
## 本层包含什么
本层一共十篇:这一页导览,加上九篇正文。
本层一共十篇(这一页导览 + 九篇数据端正文),另有「自定义 UI 与渲染」子分组 27 篇(见侧边栏)。
「自定义 UI 与渲染」子分组的入口从 [UI 通用模板](./ui/ui-template.md) 开始;先看 [UI 入门](./ui/ui-basics.md) 了解打开方式、TSX 写法与渲染树,再看 [第一个静态界面](./ui/first-static-ui.md) 把容器、文字、图片与图形拼成一块面板,之后回到模板动手写。Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端;上文的数据端前置只对数据端篇目成立。
| 序 | 篇目 | 它能让你做什么 | 前置 |
| --- | ----------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------- |
@@ -76,7 +78,8 @@
## 本层不覆盖什么
- **渲染端与编辑器**:渲染端表现、编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内,相关篇目只用占位说明归属。
- **编辑器与状态栏**:编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内,相关篇目只用占位说明归属;界面绘制与 UI 系统见子分组「自定义 UI 与渲染」。
- **引擎级性能**:高级 II 的《UI 性能》讲缓存与显示策略的取舍,引擎级性能仍属高级 III。
- **高级 III 的原理与架构**:双端分离约束、数据端分层、编辑器识别协议、录像深层原理与性能调优留给高级 III。
- **API 全量参考**:本层只讲改动链路与关键接口,不做签名清单。
+518
View File
@@ -0,0 +1,518 @@
# 基础图形
上一篇[《容器与坐标》](./container-and-coordinates.md)讲的是怎么把元素摆到位置上:坐标从哪里来、`loc` 与锚点怎么配合、容器嵌套后子元素怎么算。位置有了,这一篇开始画东西。界面里的图形元素一共八种:矩形 `g-rect`、圆 `g-circle`、椭圆 `g-ellipse`、直线 `g-line`、三次贝塞尔 `g-bezier`、二次贝塞尔 `g-quad`、路径 `g-path` 和圆角矩形 `g-rectr`。
在逐个看图形之前,先弄清所有图形共用的填充、描边与颜色规则,后面每种图形的用法都建立在这套规则上。每种图形都有一个用数组传参的简写,日常写 UI 用简写最省事;逐个属性写的普通写法只在需要拆分或复用单个值时再用,下面每节只提一句。每种图形配一个 live,最后再把八种放在一起。
## 通用规则:填充、描边与颜色
图形有两种绘制模式:填充和描边。`fill`、`stroke`、`strokeAndFill` 是模式开关,值都是布尔值,不是颜色;颜色分别写在 `fillStyle` 与 `strokeStyle` 里。写 `fill="#f00"` 不会把图形变成红色,要写 `fill fillStyle="#f00"`;默认填充的图形本来就不用写 `fill`。
每种图形有自己的默认模式:
| 图形 | 默认模式 |
| ---------------------------------------------------------- | -------- |
| `g-rect` / `g-circle` / `g-ellipse` / `g-rectr` / `g-path` | 填充 |
| `g-line` / `g-bezier` / `g-quad` | 描边 |
默认填充的图形只写 `fillStyle`;默认描边的图形只写 `strokeStyle`。需要同时填充和描边时,写 `fill` 与 `stroke`:渲染时先填充、后描边,所以**描边会覆盖 fill**,边框完整地画在填充之上。`strokeAndFill` 是另一套顺序——先描边、后填充,**fill 会覆盖描边**,描边的内半边被填充盖住,边框看起来更细;`strokeAndFill` 优先级最高,写它会忽略 `fill` 与 `stroke`。
这里有个容易踩的地方:默认填充的图形只要写了 `stroke`、又没写过 `fill`,模式就会切换成只描边,原来的填充不再生效。也就是说,默认填充只在「没写 `stroke`、也没写 `strokeAndFill`」时成立。想同时填充和描边,必须显式写 `fill` + `stroke`,或者直接用 `strokeAndFill`。
```tsx
// 默认填充的矩形只写 stroke:只画边框,不填充
<g-rect loc={[40, 40, 160, 100]} stroke strokeStyle="#58c4dd" lineWidth={4} />
// 想同时填充和描边:必须显式写 fill + stroke
<g-rect
loc={[240, 40, 160, 100]}
fill
stroke
fillStyle="#2f6fed"
strokeStyle="#e8f0ff"
lineWidth={4}
/>
```
这四种模式放在一起对照:
```tsx
// 默认填充:颜色用 fillStyle
<g-rect loc={[40, 40, 120, 80]} fillStyle="#2f6fed" />
// 默认描边:颜色用 strokeStyle
<g-line line={[40, 160, 200, 160]} strokeStyle="#7ee787" />
// 同时填充与描边:先填充后描边,描边盖住 fill
<g-circle
circle={[300, 100, 50]}
fill
stroke
fillStyle="#58c4dd"
strokeStyle="#e8f0ff"
lineWidth={4}
/>
// 先描边后填充:fill 盖住描边,strokeAndFill 优先级最高
<g-rect
loc={[260, 180, 120, 80]}
strokeAndFill
fillStyle="#f2b84b"
strokeStyle="#141a22"
lineWidth={6}
/>
```
<ClientOnly>
<RenderDemo :loader="modesLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
同一个矩形分别用四种模式,对照看边框和填充;重点对照 `fill` + `stroke` 与 `strokeAndFill` 的覆盖关系。
`fillRule` 只在填充路径时起作用,可选 `nonzero` 与 `evenodd`,具体在后面的路径一节展开。所有图形的默认颜色都是浅灰 `#ddd`;示例里通常显式写 `fillStyle` 或 `strokeStyle`。
### 描边细节
默认描边的图形,以及任何写了 `stroke` 的图形,都可以用下面这些属性控制描边:
| 属性 | 作用 | 常见值 |
| ---------------- | ------------------------------------------ | --------------------------- |
| `lineWidth` | 线宽,默认 `2` | `2` / `6` / `12` |
| `lineDash` | 虚线样式,数组按「实线长度、空白长度」交替 | `[18, 10]` |
| `lineDashOffset` | 虚线起始偏移,改变虚线从哪里开始 | `0` / `12` |
| `lineCap` | 端点样式,只影响线段两端 | `butt` / `round` / `square` |
| `lineJoin` | 拐角样式,只影响线段连接处 | `miter` / `round` / `bevel` |
| `miterLimit` | 尖角限制,`miter` 拐角过长时会被截断 | 默认 `10` |
`lineDash` 的数组会按「画一段、空一段」交替;写 `[18, 10]` 就是画 18、空 10。超过两项时继续交替,例如 `[16, 6, 2, 6]` 是长线、空白、短线、空白,常用来画点划线。`lineDashOffset` 把整个虚线图案向后平移,可以做流动的虚线。
`lineCap` 只改变两个端点,`lineJoin` 只改变拐角,两者互不影响。`miterLimit` 只在 `lineJoin="miter"` 时有意义,尖角被拉得太长时会被切成斜角。
```tsx
<g-line
line={[80, 80, 400, 80]}
strokeStyle="#7ee787"
lineWidth={6}
lineDash={[18, 10]}
lineDashOffset={4}
lineCap="round"
/>
<g-path
path={arrow}
stroke
strokeStyle="#58c4dd"
lineWidth={6}
lineJoin="miter"
miterLimit={8}
/>
```
<ClientOnly>
<RenderDemo :loader="strokeLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 分四组对比:线宽、虚线、端点与拐角。
这些属性对所有描边图形通用:默认描边的直线、贝塞尔曲线能直接用,矩形、圆、椭圆、路径写了 `stroke` 之后也能用。例如给矩形加虚线描边:
```tsx
<g-rect
loc={[40, 40, 180, 100]}
stroke
strokeStyle="#58c4dd"
lineWidth={6}
lineDash={[12, 8]}
/>
```
## 矩形 g-rect
矩形用 `loc` 简写,四个值依次是左上角 `x`、左上角 `y`、宽度、高度。矩形默认填充,颜色用 `fillStyle`。也可以把四个值拆成 `x`、`y`、`width`、`height` 分别写,效果一样。
```tsx
<g-rect loc={[80, 80, 240, 140]} fillStyle="#2f6fed" />
```
<ClientOnly>
<RenderDemo :loader="rectLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 里放了四组参数,分别对比 `loc` 不同时的位置与宽高。
矩形默认锚点在左上角,所以前两个值是左上角的位置。想改锚点时,可以把 `loc` 写成六个值,最后两项是 `anchorX`、`anchorY`;也可以单独写 `anchorX` / `anchorY`。例如把锚点改成 `0.5` 后,前两个值就变成矩形中心。
```tsx
// 锚点在中心:前两个值是矩形中心坐标
<g-rect loc={[240, 160, 120, 80, 0.5, 0.5]} fillStyle="#2f6fed" />
```
`g-rect` 本身没有圆角参数,需要圆角时用后面的 `g-rectr`。
## 圆 g-circle
圆用 `circle` 简写,三个值依次是圆心 `x`、圆心 `y`、半径。圆默认填充,颜色用 `fillStyle`。也可以写 `x`、`y`、`radius`,效果一样。
```tsx
<g-circle circle={[240, 170, 80]} fillStyle="#58c4dd" />
```
<ClientOnly>
<RenderDemo :loader="circleLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 上排放三个整圆对比半径,下排三个圆弧分别用 fill、stroke、fill+stroke 三种模式,`start` / `end` 只控制角度;标签上写的是度数,代码里按弧度写。
`circle` 还能写五个值:`[圆心 x, 圆心 y, 半径, 起始角度, 终止角度]`,这时画的是从起始角到终止角的圆弧。`start` / `end` 的单位是**弧度**,不是度数;`0` 指向右侧,角度增大沿顺时针方向。live 标签用度数只是为了好读,代码里仍要换算成弧度:
| 度数 | 弧度 |
| ------ | ------- |
| `0°` | `0` |
| `90°` | `π / 2` |
| `180°` | `π` |
| `270°` | `1.5π` |
| `360°` | `2π` |
圆弧也按填充 / 描边两种模式画:默认填充,`start` 与 `end` 之间的圆弧和两端连线围成的区域会被填满,颜色用 `fillStyle`;只想看弧线时写 `stroke`,颜色改用 `strokeStyle`;两者都要就同时写 `fill` 和 `stroke`,`fillStyle` 与 `strokeStyle` 分别给色。
```tsx
// 完整圆
<g-circle circle={[120, 100, 60]} fillStyle="#58c4dd" />
// 圆弧 0° → 180°:默认填充,弧与两端连线围成的区域被填满
<g-circle circle={[320, 100, 60, 0, Math.PI]} fillStyle="#58c4dd" />
// 同一个圆弧只描边:写 stroke,颜色改用 strokeStyle
<g-circle
circle={[320, 100, 60, 0, Math.PI]}
stroke
strokeStyle="#58c4dd"
lineWidth={4}
/>
// 填充与描边都要:同时写 fill 和 stroke,两种颜色分别给
<g-circle
circle={[320, 100, 60, 0, Math.PI]}
fill
stroke
fillStyle="#58c4dd"
strokeStyle="#e8f0ff"
lineWidth={3}
/>
```
## 椭圆 g-ellipse
椭圆用 `ellipse` 简写,四个值依次是圆心 `x`、圆心 `y`、横向半径 `rx`、纵向半径 `ry`。椭圆默认填充。也可以写 `x`、`y`、`radiusX`、`radiusY`。
```tsx
<g-ellipse ellipse={[240, 170, 130, 70]} fillStyle="#c58af9" />
```
<ClientOnly>
<RenderDemo :loader="ellipseLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 上排放三个整椭圆对比 `rx` / `ry`,下排三个部分椭圆分别用 fill、stroke、fill+stroke 三种模式,`start` / `end` 只控制角度;标签上写的是度数,代码里按弧度写。
`ellipse` 还能写六个值:`[圆心 x, 圆心 y, 横向半径, 纵向半径, 起始角度, 终止角度]`,用来画部分椭圆。角度规则与圆相同:`start` / `end` 用弧度,不是度数,`0` 指向右侧,角度增大沿顺时针方向;换算见上面的度数对照表。部分椭圆也按填充 / 描边两种模式画:默认填充,圆弧与两端连线围成的区域会被填满,颜色用 `fillStyle`;只想看弧线时写 `stroke`,颜色改用 `strokeStyle`;两者都要就同时写 `fill` 和 `stroke`,`fillStyle` 与 `strokeStyle` 分别给色。
```tsx
// 完整椭圆
<g-ellipse ellipse={[120, 100, 70, 40]} fillStyle="#c58af9" />
// 部分椭圆 180° → 360°:默认填充
<g-ellipse
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
fillStyle="#c58af9"
/>
// 同一个部分椭圆只描边:写 stroke,颜色改用 strokeStyle
<g-ellipse
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
stroke
strokeStyle="#c58af9"
lineWidth={4}
/>
// 填充与描边都要:同时写 fill 和 stroke,两种颜色分别给
<g-ellipse
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
fill
stroke
fillStyle="#c58af9"
strokeStyle="#e8f0ff"
lineWidth={3}
/>
```
## 直线 g-line
直线用 `line` 简写,四个值依次是两个端点 `x1`、`y1`、`x2`、`y2`。直线默认描边,`strokeStyle` 给颜色,`lineWidth` 给线宽。也可以逐个写 `x1`、`y1`、`x2`、`y2`。
```tsx
<g-line line={[80, 240, 400, 100]} strokeStyle="#7ee787" lineWidth={6} />
```
<ClientOnly>
<RenderDemo :loader="lineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 里放了四组参数,分别对比端点、`lineWidth`、`lineDash` 与颜色。
直线是最简单的描边图形,描边细节一节讲的 `lineDash`、`lineDashOffset`、`lineCap` 都能直接写在 `g-line` 上。`lineCap` 只改变两个端点,虚线则从起点开始按 `lineDash` 交替。
```tsx
<g-line
line={[80, 200, 400, 200]}
strokeStyle="#f2b84b"
lineWidth={10}
lineDash={[18, 10]}
lineCap="round"
/>
```
## 三次贝塞尔 g-bezier
三次贝塞尔用 `curve` 简写,八个值依次是起点 `sx`、`sy`,第一个控制点 `cp1x`、`cp1y`,第二个控制点 `cp2x`、`cp2y`,终点 `ex`、`ey`。曲线默认描边,`strokeStyle` 与 `lineWidth` 控制颜色和粗细。也可以逐个写这八个属性。
```tsx
<g-bezier
curve={[80, 240, 140, 70, 340, 250, 400, 100]}
strokeStyle="#f2b84b"
lineWidth={4}
/>
```
<ClientOnly>
<RenderDemo :loader="bezierLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 里放了四组曲线,分别对比控制点靠近、拉远、交叉与 S 形;白点是控制点,虚线是起点 → `cp1` → `cp2` → 终点的控制多边形。
起点与终点决定曲线两端,两个控制点决定中间的弯曲:第一个控制点主要拉住起点附近的走向,第二个控制点主要拉住终点附近的走向。控制点离端点越远,曲线被拉得越开;两个控制点分居曲线两侧时会出现 S 形。
## 二次贝塞尔 g-quad
二次贝塞尔用 `curve` 简写,六个值依次是起点 `sx`、`sy`,控制点 `cpx`、`cpy`,终点 `ex`、`ey`。曲线默认描边。也可以逐个写这六个属性。
```tsx
<g-quad
curve={[90, 230, 240, 80, 390, 230]}
strokeStyle="#58c4dd"
lineWidth={4}
/>
```
<ClientOnly>
<RenderDemo :loader="quadLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 里放了四组曲线,分别对比控制点在上、下、左、右;白点是控制点,虚线是起点 → 控制点 → 终点的控制多边形。
二次曲线只有一个控制点,它同时影响起点与终点两侧的走向,曲线在控制点方向达到最大弯曲。控制点离两个端点越远,弧线越鼓;做简单的弧线或装饰够用。
## 路径 g-path
路径用 `path` 属性,值是一个 `Path2D`。`Path2D` 是浏览器自带的全局构造器,直接 `new Path2D()` 即可,不需要 import。路径默认填充;只想画线时写 `stroke`。路径坐标相对元素自身,元素默认在父容器的原点,所以不写 `x` / `y` 时,坐标看起来就是从父容器原点开始。
```tsx
// Path2D 是浏览器全局对象,直接 new
const badge = new Path2D();
badge.moveTo(240, 80);
badge.lineTo(340, 140);
badge.lineTo(315, 255);
badge.lineTo(165, 255);
badge.lineTo(140, 140);
badge.closePath();
// 默认填充:给颜色即可
<g-path path={badge} fillStyle="#7ee787" />;
// 只想画轮廓:写 stroke
<g-path path={badge} stroke strokeStyle="#7ee787" lineWidth={3} />;
// 自交或多段重叠时,用 fillRule 指定填充规则
<g-path path={badge} fillStyle="#7ee787" fillRule="evenodd" />;
```
<ClientOnly>
<RenderDemo :loader="pathLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 里放了三个路径,分别对比折线、闭合填充与圆弧。
`moveTo` 决定从哪里开始,`lineTo` 连到下一个点,`closePath` 把最后一点连回起点。路径可以有多段;`arc` 画圆弧,`bezierCurveTo` 画三次贝塞尔。开放路径通常写 `stroke`,闭合路径适合填充;有自交或多段重叠时,用 `fillRule` 决定哪些区域算内部:`nonzero` 按环绕方向,`evenodd` 按奇偶,默认是 `nonzero`。
同一个 `Path2D` 可以交给多个 `g-path` 复用;但 `Path2D` 不能序列化,不能直接放进存档。需要保存路径时,保存构造它用到的点或参数,读档后重新构造。
## 圆角矩形 g-rectr
圆角矩形用 `g-rectr`。`g-rect` 没有圆角参数,需要圆角时换用 `g-rectr`。圆角用 `circle` 或 `ellipse` 简写:`circle` 给圆形圆角,`ellipse` 给椭圆圆角。
`circle` 可以写 1 到 4 项,按项数决定每个角用哪个半径:
- 1 项 `[r1]`:四个角都用 `r1`。
- 2 项 `[r1, r2]`:左上、右下用 `r1`,右上、左下用 `r2`。
- 3 项 `[r1, r2, r3]`:左上用 `r1`,右上和左下用 `r2`,右下用 `r3`。
- 4 项 `[r1, r2, r3, r4]`:依次对应左上、右上、右下、左下。
`ellipse` 每两个值为一组(横向半径、纵向半径),按组数决定每个角用哪一组:
- 2 项 `[rx1, ry1]`:四个角都用这一组。
- 4 项 `[rx1, ry1, rx2, ry2]`:左上、右下用第 1 组,右上、左下用第 2 组。
- 6 项 `[rx1, ry1, rx2, ry2, rx3, ry3]`:左上用第 1 组,右上和左下用第 2 组,右下用第 3 组。
- 8 项 `[rx1, ry1, rx2, ry2, rx3, ry3, rx4, ry4]`:依次对应左上、右上、右下、左下,每组两个值。
只想让某几个角是圆角时,把不需要的角写成 0。
```tsx
// 四个角同样圆
<g-rectr loc={[30, 70, 120, 90]} circle={[24]} fillStyle="#2f6fed" />
// 依次左上、右上、右下、左下
<g-rectr
loc={[180, 70, 120, 90]}
circle={[36, 0, 36, 0]}
fillStyle="#58c4dd"
/>
// 椭圆圆角:横向与纵向半径不同
<g-rectr
loc={[330, 70, 120, 90]}
ellipse={[48, 24]}
fillStyle="#c58af9"
/>
```
<ClientOnly>
<RenderDemo :loader="rectrLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这个 live 里放了四组圆角参数,分别对比一项半径、四项半径、椭圆圆角与大半径。
圆角矩形默认填充;圆角半径超过宽高一半时会被限制在宽高的一半以内,不会画到矩形外面。
## 所有图形的组合
把八种图形放进同一个标准 `container`,用 `FULL_LOC` 铺满整块 UI。下面是一段完整 TSX;路径先构造一次 `Path2D`,再交给 `g-path`。
```tsx
const badge = new Path2D();
badge.moveTo(300, 205);
badge.lineTo(345, 230);
badge.lineTo(333, 280);
badge.lineTo(267, 280);
badge.lineTo(255, 230);
badge.closePath();
<container loc={FULL_LOC}>
<g-rect loc={FULL_LOC} fillStyle="#141a22" />
<text loc={[24, 14]} text="八种图形" fillStyle="#e8f0ff" />
{/* 上排:矩形、圆、椭圆、直线 */}
<g-rect loc={[20, 72, 80, 62]} fillStyle="#2f6fed" />
<g-circle circle={[180, 103, 34]} fillStyle="#58c4dd" />
<g-ellipse ellipse={[300, 103, 50, 32]} fillStyle="#c58af9" />
<g-line line={[370, 133, 460, 75]} strokeStyle="#7ee787" lineWidth={4} />
{/* 下排:三次贝塞尔、二次贝塞尔、路径、圆角矩形 */}
<g-bezier
curve={[20, 275, 45, 205, 80, 280, 105, 212]}
strokeStyle="#f2b84b"
lineWidth={4}
/>
<g-quad
curve={[140, 270, 180, 205, 220, 270]}
strokeStyle="#58c4dd"
lineWidth={4}
/>
<g-path path={badge} fillStyle="#7ee787" />
<g-rectr loc={[370, 215, 80, 62]} circle={[24]} fillStyle="#f2b84b" />
{/* 每个图形的短标签 */}
<text loc={[44, 146]} text="矩形" fillStyle="#cfe0ff" />
<text loc={[170, 146]} text="圆" fillStyle="#cfe0ff" />
<text loc={[285, 146]} text="椭圆" fillStyle="#cfe0ff" />
<text loc={[405, 146]} text="直线" fillStyle="#cfe0ff" />
<text loc={[20, 292]} text="三次贝塞尔" fillStyle="#cfe0ff" />
<text loc={[140, 292]} text="二次贝塞尔" fillStyle="#cfe0ff" />
<text loc={[290, 292]} text="路径" fillStyle="#cfe0ff" />
<text loc={[380, 292]} text="圆角矩形" fillStyle="#cfe0ff" />
</container>;
```
<ClientOnly>
<RenderDemo :loader="allLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
这段代码里每种图形只出现一次,位置按 4×2 排开;换成自己的布局时,改各自的 `loc`、圆心或端点即可。
<script setup>
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
const modesLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-modes.tsx');
const strokeLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-stroke.tsx');
const rectLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-rect.tsx');
const circleLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-circle.tsx');
const ellipseLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-ellipse.tsx');
const lineLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-line.tsx');
const bezierLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-bezier.tsx');
const quadLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-quad.tsx');
const pathLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-path.tsx');
const rectrLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-rectr.tsx');
const allLoader = () =>
import('../../../.vitepress/components/demos/ui/shapes-all.tsx');
</script>
## 默认值与注意
- 圆与椭圆的默认锚点是 `0.5`,`x` / `y` 指圆心;矩形与容器的默认锚点是 `0`,`x` / `y` 指左上角。
- `curve` 数组长度写错不会报错,只会画出错误形状:三次贝塞尔要 8 个值,二次贝塞尔要 6 个值。
- `lineDash` 建议写偶数项;写奇数项时浏览器会自动复制一份再交替,容易看不出规律。
- 默认填充只在没写 `stroke` 时生效:给默认填充的图形加 `stroke` 会变成只描边,要同时填充和描边就显式写 `fill` + `stroke`。
下一篇[《文字》](./text.md)讲怎么在图形旁边写字:内容、字体、颜色与简单排版。
+396
View File
@@ -0,0 +1,396 @@
# 内置组件:基础
`@user/client-base` 里已经有一批常用的基础组件。它们和普通组件一样,在 TSX 里按名字使用,属性名写成 camelCase。下面每个组件都先说它解决什么问题,再给最小写法,常用参数跟着讲,最后接一个 live。
## Input
要接收用户文字输入,用 `Input`。
第一步:用 `v-model:value` 绑定一个字符串拿到输入内容,`loc` 给位置与大小,宽度决定输入区的宽度。
```tsx
import { ref } from 'vue';
import { Input } from '@user/client-base';
// setup
const name = ref('');
// 组件内容
<Input loc={[40, 56, 240, 32]} v-model:value={name.value} />;
```
输入框还没有内容时,想给一句提示,加 `placeholder`:
```tsx
<Input
loc={[40, 56, 240, 32]}
v-model:value={name.value}
placeholder="输入名字"
/>
```
需要多行编辑就加 `multiline`,这时输入框允许换行,高度由 `loc` 的第四项决定:
```tsx
const note = ref('');
<Input
loc={[40, 104, 320, 80]}
v-model:value={note.value}
multiline
placeholder="多行备注"
/>;
```
常用参数都在 `loc` 与外观上:`loc` 给位置和大小,宽度决定输入区宽度;`placeholder` 是空内容时的提示;`border` 是边框颜色,默认 `'#ddd'`;`borderWidth` 是边框宽度,默认 `1`;`circle` 是边框圆角,写法与 `g-rectr` 一致,例如 `[4]`;`pad` 是文字与边框之间的内边距,默认 `4`。
`value` 就是 `v-model:value` 绑定的那个值。想知道每次输入的内容加 `onInput`,想只在确认时取值加 `onChange`,两者都收到当前字符串。
全部参数:
| 属性 | 作用 | 默认或常用值 |
| ------------- | ---------------------------------------- | ------------ |
| `loc` | 位置与大小,宽度决定输入区宽度 | 必填 |
| `value` | 输入内容,配合 `v-model:value` 双向绑定 | `''` |
| `placeholder` | 空内容时的提示文字 | 无 |
| `multiline` | 多行输入,高度由 `loc` 的第四项决定 | `false` |
| `border` | 边框颜色 | `'#ddd'` |
| `borderWidth` | 边框宽度 | `1` |
| `circle` | 边框圆角,写法同 `g-rectr` | 无 |
| `pad` | 文字与边框之间的内边距 | `4` |
| `font` | 输入文字的字体,排版参数同 `TextContent` | 默认字体 |
| `fillStyle` | 文字颜色 | 白色 |
| `onInput` | 每次输入都触发,收到当前字符串 | 无 |
| `onChange` | 确认输入时触发,收到当前字符串 | 无 |
<ClientOnly>
<RenderDemo :loader="inputLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
单行占位、填入内容与多行输入三种状态。
## Icons
要显示现成的图标,直接导入图标组件,按名字用,不用自己画。
每个图标只接受 `loc`:前两项是位置,后两项是宽高。
| 属性 | 作用 | 默认或常用值 |
| ----- | ---------------- | ------------ |
| `loc` | 图标的位置与大小 | 必填 |
```tsx
import { PlayIcon, PauseIcon, RollbackIcon } from '@user/client-base';
// 组件内容
<container loc={FULL_LOC}>
<PlayIcon loc={[40, 40, 32, 32]} />
<PauseIcon loc={[88, 40, 32, 32]} />
<RollbackIcon loc={[136, 40, 32, 32]} />
</container>;
```
内置图标共 17 个,都从 `@user/client-base` 导入:
`RollbackIcon`、`RetweetIcon`、`ViewMapIcon`、`DanmakuIcon`、`ReplayIcon`、
`NumpadIcon`、`PlayIcon`、`PauseIcon`、`DoubleArrow`、`StepForward`、
`SoundVolume`、`Fullscreen`、`ExitFullscreen`、`ArrowLeftTailless`、
`ArrowRightTailless`、`ArrowUpTailless`、`ArrowDownTailless`。
图标内部的线条样式不在组件参数里展开,需要改的时候按 API 列表里的参数查找。
<ClientOnly>
<RenderDemo :loader="iconsLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
九个图标按 `loc` 排在网格里,名字写在图标下方。
## Arrow
要画一条带箭头的线,用 `Arrow`。
`arrow` 依次是起点 `x1`、`y1` 和终点 `x2`、`y2`;不用写 `loc`,位置由两端决定。
```tsx
import { Arrow } from '@user/client-base';
// 组件内容
<Arrow arrow={[40, 40, 400, 120]} />;
```
箭头头部想大一点,改 `head`,默认 `8`:
```tsx
<Arrow arrow={[40, 40, 400, 120]} head={18} />
```
想改线条和箭头的颜色,加 `color`:
```tsx
<Arrow arrow={[40, 40, 400, 120]} head={18} color="#f2b84b" />
```
| 属性 | 作用 | 默认或常用值 |
| ------- | ----------------------------------------- | ------------ |
| `arrow` | 起点与终点,依次是 `x1`、`y1`、`x2`、`y2` | 必填 |
| `head` | 箭头头部的大小 | `8` |
| `color` | 线条与箭头的颜色 | 描边默认色 |
<ClientOnly>
<RenderDemo :loader="arrowLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
三条箭头分别把 `head` 改成 `8`、`18`、`30`,颜色也各不相同。
## Selection
要画一个选中框,用 `Selection`。
`Selection` 只负责画框,不处理点击;点击和选中状态放在外层容器上自己维护。
```tsx
import { ref } from 'vue';
import { Selection } from '@user/client-base';
// setup
const selected = ref(0);
// 组件内容
<container loc={[40, 40, 220, 32]} onClick={() => (selected.value = 1)}>
<Selection loc={[0, 0, 220, 32]} color="#2f6fed" border="#7aa2ff" />
<text loc={[12, 8]} text="被选中的项" fillStyle="#ffffff" />
</container>;
```
`loc` 是框的位置与大小,通常和外层容器一样大;`color` 是框内填充色,`border` 是边框颜色。框会自己闪烁,想改闪烁的深浅用 `alphaRange`,先低后高,默认 `[0.25, 0.55]`。
```tsx
<Selection
loc={[0, 0, 220, 32]}
color="#2f6fed"
border="#7aa2ff"
alphaRange={[0.4, 0.8]}
/>
```
需要现成的选中素材时,改用 `winskin`,不再写颜色。
| 属性 | 作用 | 默认或常用值 |
| ------------ | ---------------------------- | -------------- |
| `loc` | 框的位置与大小 | 必填 |
| `color` | 框内填充色 | 无 |
| `border` | 边框颜色 | 无 |
| `winskin` | 换成现成的选中素材 | 无 |
| `alphaRange` | 闪烁的不透明度范围,先低后高 | `[0.25, 0.55]` |
<ClientOnly>
<RenderDemo :loader="selectionLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
两组 `color` 与 `border` 画出的选中框,第二组用 `alphaRange` 调大了闪烁深浅,最后一行没有选中框。
## Progress
要显示进度,用 `Progress`。
`loc` 前两项是位置,第三项是进度条长度;`progress` 是完成比例,`0` 是空、`1` 是满。
```tsx
import { ref } from 'vue';
import { Progress } from '@user/client-base';
// setup
const progress = ref(0.6);
// 组件内容
<Progress loc={[40, 40, 300, 10]} progress={progress.value} />;
```
默认已完成部分是绿色、未完成部分是灰色;想换颜色,用 `success` 给已完成部分、`background` 给未完成部分:
```tsx
<Progress
loc={[40, 40, 300, 10]}
progress={progress.value}
success="#7ee787"
background="#26364d"
/>
```
| 属性 | 作用 | 默认或常用值 |
| ------------ | ---------------------------- | ------------ |
| `loc` | 进度条的位置与宽度 | 必填 |
| `progress` | 完成比例,`0` 是空,`1` 是满 | 必填 |
| `success` | 已完成部分的颜色 | `green` |
| `background` | 未完成部分的颜色 | `gray` |
| `lineWidth` | 线条宽度 | `2` |
<ClientOnly>
<RenderDemo :loader="progressLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
`progress` 分别取 `0.3`、`0.6` 与 `1`。
## Background
要画一块背景框,用 `Background`。
`loc` 给位置与大小,`color` 是填充色,`border` 是边框颜色。
```tsx
import { Background } from '@user/client-base';
// 组件内容
<Background loc={[24, 24, 432, 272]} color="#1d2b45" border="#3a5a8c" />;
```
想用现成的背景素材,就只写 `winskin`,不再写 `color` / `border`:给了 `winskin` 就画素材,否则按颜色画圆角矩形。
```tsx
<Background loc={[24, 24, 432, 272]} winskin="winskin.png" />
```
| 属性 | 作用 | 默认或常用值 |
| --------- | ------------------ | ------------ |
| `loc` | 背景的位置与大小 | 必填 |
| `color` | 填充色 | 无 |
| `border` | 边框颜色 | 无 |
| `winskin` | 换成现成的背景素材 | 无 |
<ClientOnly>
<RenderDemo :loader="backgroundLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
同一块背景换两组 `color` 与 `border`。
## Slider
要让用户拖拽调数值,用 `Slider`。
`loc` 给位置与大小,`value` 是当前值;拖动时用 `v-model:value` 双向绑定。
```tsx
import { ref } from 'vue';
import { Slider } from '@user/client-base';
// setup
const volume = ref(40);
// 组件内容
<Slider loc={[40, 80, 240, 24]} v-model:value={volume.value} />;
```
`min` / `max` 给范围,`step` 给每次变化的最小差值:
```tsx
<Slider
loc={[40, 80, 240, 24]}
v-model:value={volume.value}
min={0}
max={100}
step={5}
/>
```
右侧默认显示当前值;不想显示就写 `showValue={false}`:
```tsx
<Slider
loc={[40, 80, 240, 24]}
v-model:value={volume.value}
min={0}
max={100}
step={5}
showValue={false}
/>
```
移动端拖动滑动条不方便,建议在它旁边再放两个按钮,分别增减数值:
```tsx
const decrease = () => (volume.value = Math.max(0, volume.value - 5));
const increase = () => (volume.value = Math.min(100, volume.value + 5));
// 组件内容
<container loc={FULL_LOC}>
<Slider
loc={[40, 80, 240, 24]}
v-model:value={volume.value}
min={0}
max={100}
step={5}
/>
<container loc={[40, 120, 64, 28]} onClick={decrease}>
<g-rectr loc={[0, 0, 64, 28]} circle={[4]} fillStyle="#2f6fed" />
<text loc={[32, 14]} anc={[0.5, 0.5]} text="-" fillStyle="#ffffff" />
</container>
<container loc={[116, 120, 64, 28]} onClick={increase}>
<g-rectr loc={[0, 0, 64, 28]} circle={[4]} fillStyle="#3a2f5f" />
<text loc={[32, 14]} anc={[0.5, 0.5]} text="+" fillStyle="#ffffff" />
</container>
</container>;
```
全部参数:
| 属性 | 作用 | 默认或常用值 |
| ------------- | ------------------------------------- | --------------- |
| `loc` | 位置与大小 | 必填 |
| `value` | 当前值,配合 `v-model:value` 双向绑定 | `min` |
| `min` | 最小值 | `0` |
| `max` | 最大值 | `0` |
| `step` | 每次变化的最小差值 | `1` |
| `showValue` | 右侧是否显示当前值 | `true` |
| `valueWidth` | 右侧数值区域的宽度 | `40` |
| `font` | 右侧数值的字体 | `12` 号默认字体 |
| `lineWidth` | 滑动条的线宽 | `2` |
| `padding` | 线两端距容器边缘的距离 | `4` |
| `filledStyle` | 控制点左侧(已选部分)的颜色 | `'#0ff'` |
| `emptyStyle` | 控制点右侧(未选部分)与描边的颜色 | `'#888'` |
| `radius` | 控制点的半径 | `4` |
<ClientOnly>
<RenderDemo :loader="sliderLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
拖动滑动条或点两侧按钮,右侧数值会跟着变。
<script setup>
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
const inputLoader = () =>
import('../../../.vitepress/components/demos/ui/builtin-input-demo.tsx');
const iconsLoader = () =>
import('../../../.vitepress/components/demos/ui/builtin-icons-demo.tsx');
const arrowLoader = () =>
import('../../../.vitepress/components/demos/ui/builtin-arrow-demo.tsx');
const selectionLoader = () =>
import('../../../.vitepress/components/demos/ui/builtin-selection-demo.tsx');
const progressLoader = () =>
import('../../../.vitepress/components/demos/ui/builtin-progress-demo.tsx');
const backgroundLoader = () =>
import('../../../.vitepress/components/demos/ui/builtin-background-demo.tsx');
const sliderLoader = () =>
import('../../../.vitepress/components/demos/ui/builtin-slider-demo.tsx');
</script>
Loaded 100 of 127 files, more files were not shown because too many files have changed in this diff. Show more