diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index e4b3262..102633e 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -591,6 +591,8 @@ Plans: - [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 标记待审阅;文档审阅计划完成,带待审阅项) +- [x] 10-55-PLAN.md — 渲染指南迁移(只收画屏幕 / 写 UI 的 27 篇 → `docs/render-guide/` 两分区:basics 10 / advanced 17,不建 internals;导航 / 侧边栏 / 导览与链接迁移;逐篇前置知识;示例 1-6 仍待审阅) +**10-55 增量说明:** 本计划只追加自身条目,`**Plans:**` 计数行不因本批改动(计数收口另行处理);`10-06` / `10-11` / `10-12` 保持未勾选;普通教程中渲染相关内容收敛未在本计划执行。 **说明:** 每篇中级教程遵循 `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 "..."` 执行。 diff --git a/.planning/STATE.md b/.planning/STATE.md index 2a3974a..05ad0bc 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,10 +4,10 @@ milestone: v1.0 current_phase: 10 current_phase_name: 文档重构 status: executing -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 标记待审阅 +stopped_at: Phase 10 进行中:10-55 渲染指南迁移已收尾(27 篇两分区,basics 10 / advanced 17,不建 internals;示例 1-6 仍待审阅);10-06/10-11/10-12 待补 +last_updated: "2026-11-16T10:22:19.468Z" +last_activity: 2026-11-16 +last_activity_desc: 10-55 渲染指南迁移收尾;27 篇两分区迁移与前置知识完成,示例 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-54 文档审阅计划已收尾(非示例文档完成,示例 1-6 待审阅);10-06 / 10-11 / 10-12 待补 +Plan: 第一批(中级 24 篇)、第二批(高级 I 7 篇)、第三批(高级 II 10 篇)、第四批(高级 I 补写 Mover/FaceHandler 2 篇)已收尾;10-42 文档内嵌渲染 demo POC 已完成并经用户验证;10-55 渲染指南迁移已收尾(27 篇迁入 basics 10 / advanced 17,不建 internals;示例 1-6 待审阅);10-06 / 10-11 / 10-12 待补 Status: In Progress -Last activity: 2026-11-15 — 10-54 用户审阅计划收尾;非示例文档完成,示例 1-6 标记待审阅 +Last activity: 2026-11-16 — 10-55 渲染指南迁移收尾;27 篇两分区迁移与前置知识完成,示例 1-6 待审阅 -Progress: Phase 10 · 29/32 plans(中级 + 高级 I 9 篇 + 高级 II 已收尾;总览 / 初级 / 高级 III / API / Agent 参考仍待推进)(另:10-42 文档内嵌渲染 demo POC 已完成并经用户验证,10-54 文档审阅计划已收尾但示例 1-6 待审阅,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);另:渲染指南已建立并完成 27 篇迁移与前置知识(只收画屏幕 / 写 UI,系统文档仍留在普通教程) ## Performance Metrics @@ -269,6 +269,7 @@ Recent decisions affecting current work: - 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` +- Phase 10 增量 10-55(2026-11-16):渲染指南迁移收尾;画屏幕 / 写 UI 的 27 篇迁入 docs/render-guide/ 两分区(basics 10 / advanced 17,不建 internals),导航 / 侧边栏 / 两份导览与链接迁移完成,27 篇各有基于真实依赖的 ## 前置知识;示例 1-6 仍待审阅;未改正文 / demo / 源码,未做普通教程渲染内容收敛,POC 保留不动,未 commit;详见 10-55-SUMMARY.md ### Pending Todos diff --git a/.planning/phases/10-docs-restructure/10-55-DEFERRED-ITEMS.md b/.planning/phases/10-docs-restructure/10-55-DEFERRED-ITEMS.md new file mode 100644 index 0000000..e4c44ef --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-55-DEFERRED-ITEMS.md @@ -0,0 +1,10 @@ +# Deferred Items — 10-docs-restructure + +## 10-55 执行期间发现(2026-11-16) + +- **类型检查:`docs/.vitepress/components/demos/ui/container-custom-demo.tsx(17,41): error TS2554: Expected 1 arguments, but got 2.`** + - 发现于:Task 4 类型门禁。 + - 原因:工作树中与本计划无关的未提交改动(`packages-user/client-base/src/map/element.ts` 的 `renderContent` 调用改为 1 个参数)与 demo 中按两参数写入的 `renderContent(canvas, transform)` 不一致。 + - 范围判断:demo 文件本身未被 10-55 修改(`git status` 为空);10-55 未改 `packages/` / `packages-user/`,按范围边界不修。 + - 影响:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径报错从 0 变为 1;其余 218 条报错均位于 `packages/` / `packages-user/`。 + - 待办:由用户确认包改动与 demo 的预期签名后,另行修复 demo 或包;10-55 不处理。 diff --git a/.planning/phases/10-docs-restructure/10-55-INVENTORY.md b/.planning/phases/10-docs-restructure/10-55-INVENTORY.md new file mode 100644 index 0000000..1e2452f --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-55-INVENTORY.md @@ -0,0 +1,290 @@ +# 10-55 渲染指南迁移清单 + +## 指南范围 + +只收画屏幕 / 写 UI 的 27 篇自定义 UI 文档;数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统仍留在中级/高级教程,**不迁入本指南、不新增系统文档**。本节为后续映射与门禁的范围依据。 + +## 用户裁决(Task 0) + +用户已确认修正后的计划(名称 / 范围更正):指南名为「渲染指南」(不是「渲染端指南」),只收画屏幕 / 写 UI 的材料,无关系统留在中级 / 高级教程。逐项裁决如下,均按默认: + +1. **路径**:`docs/render-guide/`(用户批准按默认)。 +2. **顶部导航名**:`渲染指南`,追加在「中级教程」「高级教程」之后,链接 `/render-guide/`(用户批准按默认;用户特别确认名称为「渲染指南」)。 +3. **两分区**:目录 `basics/`、`advanced/`,侧边栏显示名 `渲染基础`、`渲染进阶`(用户批准按默认;后经用户结构修正为两分区)。 +4. **页面映射**:27 行映射按 全表执行,basics 10 / advanced 17;分区归属、侧边栏顺序与审阅状态均按默认(用户批准按默认;后经用户结构修正,`ui-system` / `ui-performance` 归入 advanced)。 +5. **示例待审阅口径**:`inventory-example-1..6` 保持「待审阅」,本计划只迁移、补前置知识,不审阅、不改写正文;不把待审阅状态写进文档正文(D-97)(用户批准按默认)。 +6. **基线计数与审阅谱系**:页面基线固定 27(25 只是 10-54 历史记录值,不采用);19 篇继承 10-54 的已审阅状态(含改名继承,由用户确认);`ui-basics`、`first-static-ui` 默认 `待审阅`;6 篇示例待审阅(用户批准按默认;用户确认新增两页仍为待审阅)。 +7. **普通教程渲染端内容**:本计划只盘点,不改写正文;收敛改写另开计划(用户批准按默认)。 +8. **demo 位置与收尾**:demo 保留在 `docs/.vitepress/components/demos/ui/`,不移动;本计划不 commit;修改方式为派发子代理执行(用户批准按默认)。 +9. **POC 页处置**:`docs/poc/render-demo.md` 保留不动(用户批准按默认)。 + +用户未提出路径、导航名、分区归属、侧边栏顺序或审阅状态的修改要求。 + +## 基线 + +- BASE-HEAD:2a4b3220ed9ecc01b2f92eabd375185eb686a01a +- 页面基线:27 +- 页面实测:27 篇(`basic-shapes.md`、`builtin-basic.md`、`builtin-layout.md`、`builtin-text.md`、`common-props.md`、`conditional-and-list-rendering.md`、`container-and-coordinates.md`、`custom-and-container-custom.md`、`custom-components.md`、`events.md`、`first-static-ui.md`、`hotkey-in-ui.md`、`image-and-texture.md`、`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`、`layer-transform-performance.md`、`reactivity.md`、`text.md`、`ui-basics.md`、`ui-performance.md`、`ui-system.md`、`ui-template.md`、`what-is-component.md`) +- 10-54 记录值:25 篇(19 已审阅 + 6 待审阅)/ 24 demo +- 新增页面审阅状态:ui-basics=待审阅;first-static-ui=待审阅 +- 用户确认新增页面为已审阅:否 +- POC 处置:保留不动 +- 指南范围:仅画屏幕 / 写 UI(27 篇);数据端 / 存档 / 插件 / 编辑器等系统文档不迁入、不新增 +- demo 基线:文件 67;被正文引用 65;带 live(renderDemo.vue) 24 +- demo 目录:docs/.vitepress/components/demos/ui/ +- docs 快照哈希:363b822c90b84761eff38b4ca518837eae609d0a1c6d8f1b7d5f62f38cb6c853 +- 配置快照哈希:212dc5960e3a9ff5d04b0f08e9616cf0dfae268856e92a8654022930ef6bcbbe +- 停止点:10-55 只做迁移 / 前置知识 / 结构门禁;不重写正文、不移动 demo、不审阅示例、不 commit + +快照哈希口径:27 篇按相对路径排序,逐文件 SHA-256 后拼 `相对路径:hash`,以 LF 连接,再取 SHA-256。 + +## 页面映射 + +本表是链接迁移与侧边栏生成的唯一事实来源。 + +| 序 | 源路径 | 目标路径 | 分区 | 侧边栏标题 | 审阅状态 | demo 引用数 | 内部链接数 | +| --- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ | -------- | -------------------------- | -------- | ----------- | ---------- | +| 1 | docs/advanced/ii/ui/ui-template.md | docs/render-guide/basics/ui-template.md | basics | UI 通用模板(TSX) | 已审阅 | 0 | 10 | +| 2 | docs/advanced/ii/ui/ui-basics.md | docs/render-guide/basics/ui-basics.md | basics | UI 入门 | 待审阅 | 1 | 8 | +| 3 | docs/advanced/ii/ui/first-static-ui.md | docs/render-guide/basics/first-static-ui.md | basics | 第一个静态界面 | 待审阅 | 1 | 6 | +| 4 | docs/advanced/ii/ui/container-and-coordinates.md | docs/render-guide/basics/container-and-coordinates.md | basics | 容器与坐标 | 已审阅 | 2 | 2 | +| 5 | docs/advanced/ii/ui/basic-shapes.md | docs/render-guide/basics/basic-shapes.md | basics | 基础图形 | 已审阅 | 11 | 2 | +| 6 | docs/advanced/ii/ui/text.md | docs/render-guide/basics/text.md | basics | 文字 | 已审阅 | 4 | 1 | +| 7 | docs/advanced/ii/ui/image-and-texture.md | docs/render-guide/basics/image-and-texture.md | basics | 图片与纹理 | 已审阅 | 2 | 0 | +| 8 | docs/advanced/ii/ui/custom-and-container-custom.md | docs/render-guide/basics/custom-and-container-custom.md | basics | 自绘元素与自定义容器 | 已审阅 | 2 | 1 | +| 9 | docs/advanced/ii/ui/common-props.md | docs/render-guide/basics/common-props.md | basics | 通用参数 | 已审阅 | 5 | 0 | +| 10 | docs/advanced/ii/ui/layer-transform-performance.md | docs/render-guide/basics/layer-transform-performance.md | basics | 层级、变换与性能 | 已审阅 | 3 | 1 | +| 11 | docs/advanced/ii/ui/reactivity.md | docs/render-guide/advanced/reactivity.md | advanced | 响应式 | 已审阅 | 4 | 2 | +| 12 | docs/advanced/ii/ui/events.md | docs/render-guide/advanced/events.md | advanced | 事件与交互 | 已审阅 | 4 | 1 | +| 13 | docs/advanced/ii/ui/conditional-and-list-rendering.md | docs/render-guide/advanced/conditional-and-list-rendering.md | advanced | 条件渲染与循环渲染 | 已审阅 | 3 | 0 | +| 14 | docs/advanced/ii/ui/hotkey-in-ui.md | docs/render-guide/advanced/hotkey-in-ui.md | advanced | 按键与快捷键 | 已审阅 | 0 | 0 | +| 15 | docs/advanced/ii/ui/what-is-component.md | docs/render-guide/advanced/what-is-component.md | advanced | 什么是组件 | 已审阅 | 1 | 0 | +| 16 | docs/advanced/ii/ui/builtin-basic.md | docs/render-guide/advanced/builtin-basic.md | advanced | 内置组件:基础 | 已审阅 | 7 | 0 | +| 17 | docs/advanced/ii/ui/builtin-layout.md | docs/render-guide/advanced/builtin-layout.md | advanced | 内置组件:布局 | 已审阅 | 4 | 0 | +| 18 | docs/advanced/ii/ui/builtin-text.md | docs/render-guide/advanced/builtin-text.md | advanced | 内置组件:文本 | 已审阅 | 2 | 0 | +| 19 | docs/advanced/ii/ui/custom-components.md | docs/render-guide/advanced/custom-components.md | advanced | 自定义组件 | 已审阅 | 1 | 0 | +| 20 | docs/advanced/ii/ui/inventory-example-1-skeleton.md | docs/render-guide/advanced/inventory-example-1-skeleton.md | advanced | 示例(一)目标与骨架 | 待审阅 | 1 | 3 | +| 21 | docs/advanced/ii/ui/inventory-example-2-grid.md | docs/render-guide/advanced/inventory-example-2-grid.md | advanced | 示例(二)道具网格 | 待审阅 | 1 | 1 | +| 22 | docs/advanced/ii/ui/inventory-example-3-detail.md | docs/render-guide/advanced/inventory-example-3-detail.md | advanced | 示例(三)详情区 | 待审阅 | 1 | 0 | +| 23 | docs/advanced/ii/ui/inventory-example-4-scroll.md | docs/render-guide/advanced/inventory-example-4-scroll.md | advanced | 示例(四)滚动与列表 | 待审阅 | 1 | 0 | +| 24 | docs/advanced/ii/ui/inventory-example-5-state.md | docs/render-guide/advanced/inventory-example-5-state.md | advanced | 示例(五)交互与状态 | 待审阅 | 1 | 0 | +| 25 | docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | docs/render-guide/advanced/inventory-example-6-animation-and-register.md | advanced | 示例(六)动画、拆分与注册 | 待审阅 | 1 | 4 | +| 26 | docs/advanced/ii/ui/ui-system.md | docs/render-guide/advanced/ui-system.md | advanced | UI 系统 | 已审阅 | 2 | 0 | +| 27 | docs/advanced/ii/ui/ui-performance.md | docs/render-guide/advanced/ui-performance.md | advanced | UI 性能 | 已审阅 | 0 | 4 | + +分区计数:basics 10 / advanced 17 / internals 0(有效分区 2)。demo 引用合计 65,内部链接合计 46,与基线实测一致。 + +## 页面谱系与审阅状态 + +10-54 的 25 篇清单来自旧页集,`5db2cef` 之后的页面集已改名或合并;旧稿从未入库,git 无法独立证明逐篇谱系,因此下面 19 篇的「已审阅」以用户在 Task 0 的确认(含改名继承)为准。 + +### 同名继承(11 篇) + +- `ui-template.md` → 10-54 `ui-template.md`(同名)→ 已审阅 +- `container-and-coordinates.md` → 10-54 `container-and-coordinates.md`(同名)→ 已审阅 +- `basic-shapes.md` → 10-54 `basic-shapes.md`(同名)→ 已审阅 +- `text.md` → 10-54 `text.md`(同名)→ 已审阅 +- `image-and-texture.md` → 10-54 `image-and-texture.md`(同名)→ 已审阅 +- `layer-transform-performance.md` → 10-54 `layer-transform-performance.md`(同名)→ 已审阅 +- `reactivity.md` → 10-54 `reactivity.md`(同名)→ 已审阅 +- `events.md` → 10-54 `events.md`(同名)→ 已审阅 +- `hotkey-in-ui.md` → 10-54 `hotkey-in-ui.md`(同名)→ 已审阅 +- `conditional-and-list-rendering.md` → 10-54 `conditional-and-list-rendering.md`(同名)→ 已审阅 +- `ui-performance.md` → 10-54 `ui-performance.md`(同名;10-53 已按「日常优化习惯」重写)→ 已审阅 + +### 改名 / 合并继承(8 篇) + +- `common-props.md` → 10-54 `props.md`(改名)→ 已审阅 +- `what-is-component.md` → 10-54 `component-tsx.md`(改名)→ 已审阅 +- `custom-components.md` → 10-54 `component-tsx.md` / `slots-and-attrs.md`(合并改名)→ 已审阅 +- `builtin-basic.md` → 10-54 `builtin-text-and-input.md`(拆分继承)→ 已审阅 +- `builtin-layout.md` → 10-54 `builtin-list-and-containers.md`(拆分改名)→ 已审阅 +- `builtin-text.md` → 10-54 `builtin-text-and-input.md`(拆分继承)→ 已审阅 +- `ui-system.md` → 10-54 `ui-controller-and-stack.md`(改名)→ 已审阅 +- `custom-and-container-custom.md` → 10-54 `replace-builtin-ui.md`(改名)→ 已审阅 + +### 新增页(2 篇) + +- `ui-basics.md` → 10-54 无对应(`5db2cef` 后新增)→ 待审阅 +- `first-static-ui.md` → 10-54 无对应(`5db2cef` 后新增)→ 待审阅 + +### 示例(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` → 待审阅 + +计数:已审阅 19 + 新增待审阅 2 + 示例待审阅 6 = 27。 + +## 链接迁移清单 + +### 内部 Markdown 链接 + +规划时实测 46 处,逐条如下;目标规则为同分区保持 `./x.md`、跨分区改为 `../<目标分区>/x.md`,链接文字与锚点不变。 + +| 源文件 | 原链接 | 迁移后链接 | +| ----------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- | +| docs/advanced/ii/ui/basic-shapes.md | ./container-and-coordinates.md | ./container-and-coordinates.md | +| docs/advanced/ii/ui/basic-shapes.md | ./text.md | ./text.md | +| docs/advanced/ii/ui/container-and-coordinates.md | ./first-static-ui.md | ./first-static-ui.md | +| docs/advanced/ii/ui/container-and-coordinates.md | ./basic-shapes.md | ./basic-shapes.md | +| docs/advanced/ii/ui/custom-and-container-custom.md | ./reactivity.md | ../advanced/reactivity.md | +| docs/advanced/ii/ui/events.md | ./basic-shapes.md | ../basics/basic-shapes.md | +| docs/advanced/ii/ui/first-static-ui.md | ./container-and-coordinates.md | ./container-and-coordinates.md | +| docs/advanced/ii/ui/first-static-ui.md | ./basic-shapes.md | ./basic-shapes.md | +| docs/advanced/ii/ui/first-static-ui.md | ./text.md | ./text.md | +| docs/advanced/ii/ui/first-static-ui.md | ./image-and-texture.md | ./image-and-texture.md | +| docs/advanced/ii/ui/first-static-ui.md | ./layer-transform-performance.md | ./layer-transform-performance.md | +| docs/advanced/ii/ui/first-static-ui.md | ./events.md | ../advanced/events.md | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | ./container-and-coordinates.md#渲染树根容器与子元素 | ../basics/container-and-coordinates.md#渲染树根容器与子元素 | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | ./layer-transform-performance.md#渲染树层级与绘制顺序 | ../basics/layer-transform-performance.md#渲染树层级与绘制顺序 | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | ./ui-system.md | ./ui-system.md | +| docs/advanced/ii/ui/inventory-example-2-grid.md | ./custom-components.md#props | ./custom-components.md#props | +| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | ./ui-template.md#gameui-是一个对象不是名字 | ../basics/ui-template.md#gameui-是一个对象不是名字 | +| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | ./ui-system.md#keep | ./ui-system.md#keep | +| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | ./layer-transform-performance.md | ../basics/layer-transform-performance.md | +| docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | ./ui-system.md#隐藏与显示 | ./ui-system.md#隐藏与显示 | +| docs/advanced/ii/ui/layer-transform-performance.md | ./common-props.md#zindex | ./common-props.md#zindex | +| docs/advanced/ii/ui/reactivity.md | ./events.md | ./events.md | +| docs/advanced/ii/ui/reactivity.md | ./custom-components.md#props | ./custom-components.md#props | +| docs/advanced/ii/ui/text.md | ./builtin-text.md | ../advanced/builtin-text.md | +| docs/advanced/ii/ui/ui-basics.md | ./ui-system.md | ../advanced/ui-system.md | +| docs/advanced/ii/ui/ui-basics.md | ./conditional-and-list-rendering.md | ../advanced/conditional-and-list-rendering.md | +| docs/advanced/ii/ui/ui-basics.md | ./container-and-coordinates.md | ./container-and-coordinates.md | +| docs/advanced/ii/ui/ui-basics.md | ./basic-shapes.md | ./basic-shapes.md | +| docs/advanced/ii/ui/ui-basics.md | ./text.md | ./text.md | +| docs/advanced/ii/ui/ui-basics.md | ./events.md | ../advanced/events.md | +| docs/advanced/ii/ui/ui-basics.md | ./custom-components.md | ../advanced/custom-components.md | +| docs/advanced/ii/ui/ui-basics.md | ./ui-system.md(第二处) | ../advanced/ui-system.md | +| docs/advanced/ii/ui/ui-performance.md | ./builtin-layout.md | ./builtin-layout.md | +| docs/advanced/ii/ui/ui-performance.md | ./layer-transform-performance.md#缓存与脏更新 | ../basics/layer-transform-performance.md#缓存与脏更新 | +| docs/advanced/ii/ui/ui-performance.md | ./common-props.md | ../basics/common-props.md | +| docs/advanced/ii/ui/ui-performance.md | ./conditional-and-list-rendering.md | ./conditional-and-list-rendering.md | +| docs/advanced/ii/ui/ui-template.md | ./ui-basics.md | ./ui-basics.md | +| docs/advanced/ii/ui/ui-template.md | ./container-and-coordinates.md | ./container-and-coordinates.md | +| docs/advanced/ii/ui/ui-template.md | ./basic-shapes.md | ./basic-shapes.md | +| docs/advanced/ii/ui/ui-template.md | ./text.md | ./text.md | +| docs/advanced/ii/ui/ui-template.md | ./image-and-texture.md | ./image-and-texture.md | +| docs/advanced/ii/ui/ui-template.md | ./reactivity.md | ../advanced/reactivity.md | +| docs/advanced/ii/ui/ui-template.md | ./events.md | ../advanced/events.md | +| docs/advanced/ii/ui/ui-template.md | ./custom-components.md | ../advanced/custom-components.md | +| docs/advanced/ii/ui/ui-template.md | ./ui-system.md | ../advanced/ui-system.md | +| docs/advanced/ii/ui/ui-template.md | ./inventory-example-1-skeleton.md | ../advanced/inventory-example-1-skeleton.md | + +合计 46 处,与实测一致;无跨出 `docs/advanced/ii/ui/` 的外部链接(27 篇内 `](../...)` 形式为 0)。 + +### demo 导入 + +27 篇中所有 `.vitepress/components` 导入均为 `../../../.vitepress/...`(相对 `docs/advanced/ii/ui/`),迁移后统一改为 `../../.vitepress/...`。逐篇条数(demo + RenderDemo): + +| 目标页 | demo 导入 | renderDemo 导入 | +| ------------------------------------------------------ | --------- | --------------- | +| basics/ui-template.md | 0 | 0 | +| basics/ui-basics.md | 1 | 1 | +| basics/first-static-ui.md | 1 | 1 | +| basics/container-and-coordinates.md | 2 | 1 | +| basics/basic-shapes.md | 11 | 1 | +| basics/text.md | 4 | 1 | +| basics/image-and-texture.md | 2 | 1 | +| basics/custom-and-container-custom.md | 2 | 1 | +| basics/common-props.md | 5 | 1 | +| basics/layer-transform-performance.md | 3 | 1 | +| advanced/reactivity.md | 4 | 1 | +| advanced/events.md | 4 | 1 | +| advanced/conditional-and-list-rendering.md | 3 | 1 | +| advanced/hotkey-in-ui.md | 0 | 0 | +| advanced/what-is-component.md | 1 | 1 | +| advanced/builtin-basic.md | 7 | 1 | +| advanced/builtin-layout.md | 4 | 1 | +| advanced/builtin-text.md | 2 | 1 | +| advanced/custom-components.md | 1 | 1 | +| advanced/inventory-example-1-skeleton.md | 1 | 1 | +| advanced/inventory-example-2-grid.md | 1 | 1 | +| advanced/inventory-example-3-detail.md | 1 | 1 | +| advanced/inventory-example-4-scroll.md | 1 | 1 | +| advanced/inventory-example-5-state.md | 1 | 1 | +| advanced/inventory-example-6-animation-and-register.md | 1 | 1 | +| advanced/ui-system.md | 2 | 1 | +| advanced/ui-performance.md | 0 | 0 | + +合计 demo 65 + renderDemo 24 = 89 处。demo 文件本身不移动、不改名、不修改。 + +### 导航 / 导览 + +- `docs/.vitepress/config.ts`:移除 `sidebar['/advanced/']` 中整个「自定义 UI 与渲染」分组(27 条 `/advanced/ii/ui/` 链接);`nav` 追加 `{ text: '渲染指南', link: '/render-guide/' }`;新增 `sidebar['/render-guide/']`(渲染基础 10 条 / 渲染进阶 17 条)。高级 II 数据端 9 条正文链接 + 导览 1 条保留,高级 III 分组与 `/intermediate/` 逐字保留。 +- `docs/advanced/ii/index.md`: + - L15「这一层的主体是数据端;另有自定义 UI 与渲染子分组(见侧边栏),面向要在画布上写界面的作者。」→ 指向 `../../render-guide/`。 + - L52「本层一共十篇……另有「自定义 UI 与渲染」子分组 27 篇(见侧边栏)。」→ 改为指向渲染指南。 + - L54 整段(原含 3 处 `./ui/...` 链接)→ 改为「渲染端的阅读入口与三级路径见[渲染指南](../../render-guide/);本层不再重复。」 + - L81「界面绘制与 UI 系统见子分组「自定义 UI 与渲染」。」→ 指向 `../../render-guide/`。 + - L82「高级 II 的《UI 性能》……」→ 改为链接 `../../render-guide/advanced/ui-performance`。 +- `docs/advanced/index.md`: + - L38「高级 II 已收录「自定义 UI 与渲染」子分组……」→ 指向 `../render-guide/`(保留编辑器占位句)。 + - L39「高级 II 的《UI 性能》……」→ 改为链接 `../render-guide/advanced/ui-performance`。 + - 「三层结构」表不新增「自定义 UI 与渲染」短语。 + +## 普通教程渲染端内容盘点(只盘点、不改写) + +只记录现状,不提出改写方案、不改文件;这些系统文档不迁入本指南,也不新增到 `docs/render-guide/`。 + +| 篇目 | 涉及内容 | 是否应在后续收敛为指引链接 | +| ----------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------- | +| docs/intermediate/data-vs-render.md | 全文讲「数据端算 / 渲染端画」分工、渲染端只负责画与转达操作(L1–L20 起) | 否。这是双端分工的总前提,不属于绘制方法。 | +| docs/intermediate/src-tour.md | `## src/client:渲染端`(约 L29–L40)列出渲染端入口、初始化、插件目录 | 部分。可补指向渲染指南的入口句,但目录本身属于工程导览。 | +| docs/intermediate/data-state-overview.md | `emitTip` 一行「通知渲染端提示」(L78) | 否。只是一条接口归属说明。 | +| docs/intermediate/hooks.md | `onTip` 一行「通知渲染端进行一次提示」(L69) | 否。同上。 | +| docs/advanced/i/index.md | L15 与 L75「渲染端尚未完工,当前只写数据端内容,渲染端部分只用占位标记指出归属」 | 是。渲染指南落地后应把这段占位改成指向渲染指南的入口(本计划不改)。 | +| docs/advanced/i/face-handler.md | L7「本篇只讲数据端……由渲染端读取后完成」;`` | 部分。渲染端消费侧可指向指南,但本篇是数据端接口文档。 | +| docs/advanced/i/mover.md | L5「画面上的位移、动画与速度表现由渲染端读取这些状态后完成」;L101 起 tp/jump 语义 | 否。位移状态属于数据端。 | +| docs/advanced/i/plugin-system.md | 渲染端插件接口、目录与注册(L5、L26–L86) | 否。插件系统不是绘制方法。 | +| docs/advanced/i/replay-consistency.md | L57 / L117 强调标记只在数据端、渲染端不参与回放 | 否。录像一致性属于数据端约束。 | +| docs/advanced/i/saveable-content.md | L24「临时动画、提示、界面状态」不存 | 否。存档取舍。 | +| docs/advanced/ii/index.md | L15 / L52 / L54 / L81 / L82 旧「自定义 UI 与渲染」子分组表述与 3 处 `./ui/` 链接 | 是。本计划在 Task 2 改写为渲染指南入口。 | +| docs/advanced/ii/adding-hero-attribute.md | L15「显示 / 编辑器与渲染端」、L392「渲染端 · 状态栏」占位 | 否。属性接入的占位项。 | +| docs/advanced/ii/custom-replay-command.md | L133「渲染端的播放表现按渲染端教程处理」与 `` | 部分。可把「渲染端教程」改为渲染指南链接,但属正文改写,本计划不改。 | +| docs/advanced/ii/pathfinding.md | L319「渲染端如何表现寻路移动不在本篇范围内」+ TODO | 部分。同上。 | +| docs/advanced/iii/index.md | L92「渲染端的结构、动画与输入处理;这里只讲数据端」 | 是。可在渲染指南落地后补入口句(本计划不改)。 | +| docs/advanced/iii/core-state.md | L158 表格「纯展示、输入或动画 → 渲染端,不在数据端四层」 | 否。分层原则说明。 | +| docs/advanced/iii/loading-system.md | L273–L283 加载进度由界面读取、渲染端可复用加载器 | 否。加载系统文档。 | +| docs/advanced/ii/ui/\*(27 篇) | 全部画屏幕 / 写 UI 内容 | 本计划迁入渲染指南,不在普通教程保留副本。 | + +## 待确认项 + +无。Task 0 的 9 项裁决、路径、导航名、两分区、27 篇基线、审阅谱系、示例口径与 POC 处置均已确认,可进入 Task 2。 + +## 前置知识依据 + +| 目标页 | 实际写入的前置 | 依据(阅读顺序 / 正文引用 / 交叉链接) | +| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| docs/render-guide/basics/ui-template.md | 无 | 本页是模板入口,正文只要求基础 TS/JS,无更早的 UI 页可前置 | +| docs/render-guide/basics/ui-basics.md | 无 | 本页是起步第一篇,正文自带打开方式与 TSX 基础,无更早的 UI 页可前置 | +| docs/render-guide/basics/first-static-ui.md | docs/render-guide/basics/ui-basics.md | 阅读顺序:原 `docs/advanced/ii/index.md` 起步段规定「先看 UI 入门,再看第一个静态界面」 | +| docs/render-guide/basics/container-and-coordinates.md | docs/render-guide/basics/first-static-ui.md | 交叉链接:正文开头「上一篇《第一个静态界面》」 | +| docs/render-guide/basics/basic-shapes.md | docs/render-guide/basics/container-and-coordinates.md | 交叉链接:正文开头「上一篇《容器与坐标》」 | +| docs/render-guide/basics/text.md | docs/render-guide/basics/container-and-coordinates.md、docs/render-guide/basics/basic-shapes.md | 阅读顺序:容器与坐标 → 基础图形 → 文字(基础图形篇末「下一篇《文字》」衔接);正文以图形的填充/描边规则作对照 | +| docs/render-guide/basics/image-and-texture.md | docs/render-guide/basics/container-and-coordinates.md | 阅读顺序:元素与布局组内位于容器与坐标之后;正文用 `loc` 与容器坐标定位 | +| docs/render-guide/basics/custom-and-container-custom.md | docs/render-guide/basics/container-and-coordinates.md、docs/render-guide/basics/basic-shapes.md | 正文引用:用 `loc`、`container`、`g-rect` 说明自绘尺寸与子元素;正文直接链到《响应式》解释 `bindings` | +| docs/render-guide/basics/common-props.md | docs/render-guide/basics/container-and-coordinates.md、docs/render-guide/basics/basic-shapes.md | 正文引用:以 `loc`、`container`、`g-rect`、`hidden` 为例说明通用属性 | +| docs/render-guide/basics/layer-transform-performance.md | docs/render-guide/basics/container-and-coordinates.md、docs/render-guide/basics/common-props.md | 交叉链接:正文链到 `./common-props.md#zindex`;正文以渲染树父子坐标为变换与缓存的前提 | +| docs/render-guide/advanced/reactivity.md | docs/render-guide/basics/ui-basics.md、docs/render-guide/basics/first-static-ui.md | 阅读顺序:交互与数据位于起步之后;正文使用起步页的模板与 `container` 结构 | +| docs/render-guide/advanced/events.md | docs/render-guide/basics/container-and-coordinates.md、docs/render-guide/advanced/reactivity.md | 正文引用:用 `container`、`g-rect`、`loc` 搭按钮,并用 `ref` 收集交互日志;响应式篇明示「后面事件与交互会专门讲」 | +| docs/render-guide/advanced/conditional-and-list-rendering.md | docs/render-guide/advanced/reactivity.md、docs/render-guide/advanced/events.md | 正文引用:条件与循环都靠 `ref` 状态与 `onClick` 切换 | +| docs/render-guide/advanced/hotkey-in-ui.md | docs/render-guide/advanced/reactivity.md、docs/render-guide/advanced/events.md | 正文引用:以「按键与元素事件」对照元素事件,并用共享 `ref` 与 `onClick` 协同 | +| docs/render-guide/advanced/what-is-component.md | docs/render-guide/basics/ui-basics.md | 正文引用:本页讲组件与 props;UI 入门已讲组件作为标签的使用方式 | +| docs/render-guide/advanced/builtin-basic.md | docs/render-guide/advanced/what-is-component.md | 正文引用:内置组件按组件与 props 写法使用(如 `v-model:value`) | +| docs/render-guide/advanced/builtin-layout.md | docs/render-guide/advanced/what-is-component.md、docs/render-guide/advanced/builtin-basic.md | 正文引用:以组件与 `ref` / `v-model` 使用区域组件;阅读顺序:组件化组内基础先于布局 | +| docs/render-guide/advanced/builtin-text.md | docs/render-guide/advanced/what-is-component.md、docs/render-guide/advanced/builtin-basic.md | 正文引用:以组件与 props 使用文本组件;阅读顺序:组件化组内基础先于文本 | +| docs/render-guide/advanced/custom-components.md | docs/render-guide/advanced/what-is-component.md、docs/render-guide/advanced/builtin-basic.md | 正文引用:开头「前面的页面已经能用容器、文字、图形与内置组件拼出整块 UI」,并重复 props 三步声明 | +| docs/render-guide/advanced/inventory-example-1-skeleton.md | docs/render-guide/basics/first-static-ui.md、docs/render-guide/basics/container-and-coordinates.md | 阅读顺序:示例是起步与零件篇之后的一批;正文链到容器与层级页说明骨架坐标与层级 | +| docs/render-guide/advanced/inventory-example-2-grid.md | docs/render-guide/advanced/inventory-example-1-skeleton.md、docs/render-guide/basics/basic-shapes.md | 交叉链接:正文「上一篇的左侧只有一块占位」;正文用 `g-rect` 与 `loc` 排网格 | +| docs/render-guide/advanced/inventory-example-3-detail.md | docs/render-guide/advanced/inventory-example-2-grid.md、docs/render-guide/basics/text.md、docs/render-guide/basics/common-props.md | 交叉链接:正文链到 `../basics/common-props.md` 并用 `hidden`;阅读顺序:承接上一篇网格 | +| docs/render-guide/advanced/inventory-example-4-scroll.md | docs/render-guide/advanced/inventory-example-3-detail.md、docs/render-guide/advanced/builtin-layout.md | 正文引用:把示例(二)的普通网格换成 `Scroll`,`Scroll` 由内置组件:布局讲解 | +| docs/render-guide/advanced/inventory-example-5-state.md | docs/render-guide/advanced/inventory-example-4-scroll.md、docs/render-guide/advanced/reactivity.md、docs/render-guide/advanced/events.md | 阅读顺序:承接前五步;正文用 `ref`、`emit` 与 `onClick` 接交互与状态 | +| docs/render-guide/advanced/inventory-example-6-animation-and-register.md | docs/render-guide/advanced/inventory-example-5-state.md、docs/render-guide/advanced/custom-components.md、docs/render-guide/advanced/ui-system.md | 交叉链接:正文链到 `./ui-system.md#keep` 与 `../basics/ui-template.md`;正文讲组件拆分与 `GameUI` 注册 | +| docs/render-guide/advanced/ui-system.md | docs/render-guide/advanced/events.md | 阅读顺序:旧侧边栏交互与数据 → UI 系统;正文以组件状态与按键作用域为操作对象;用户结构修正后不再前置 `custom-components` | +| docs/render-guide/advanced/ui-performance.md | docs/render-guide/basics/layer-transform-performance.md、docs/render-guide/advanced/ui-system.md | 交叉链接:正文链到 `./layer-transform-performance.md#缓存与脏更新` 等四页;阅读顺序:旧侧边栏性能在 UI 系统之后 | + +未调整任何拟写前置:27 行均能在 10-55-PLAN 拟写表与上述依据之间对应,无需删除或改写条目。 diff --git a/.planning/phases/10-docs-restructure/10-55-PLAN.md b/.planning/phases/10-docs-restructure/10-55-PLAN.md new file mode 100644 index 0000000..d46e0f1 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-55-PLAN.md @@ -0,0 +1,551 @@ +--- +phase: 10-docs-restructure +plan: 55 +type: execute +wave: 13 +depends_on: + - 10-54 +files_modified: + - .planning/phases/10-docs-restructure/10-55-INVENTORY.md + - .planning/phases/10-docs-restructure/10-55-USER-REVIEW.md + - .planning/phases/10-docs-restructure/10-55-SUMMARY.md + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - .planning/ROADMAP.md + - .planning/STATE.md + - docs/.vitepress/config.ts + - docs/advanced/ii/index.md + - docs/advanced/index.md + - docs/render-guide/index.md + - docs/render-guide/basics/ui-template.md + - docs/render-guide/basics/ui-basics.md + - docs/render-guide/basics/first-static-ui.md + - docs/render-guide/basics/container-and-coordinates.md + - docs/render-guide/basics/basic-shapes.md + - docs/render-guide/basics/text.md + - docs/render-guide/basics/image-and-texture.md + - docs/render-guide/basics/custom-and-container-custom.md + - docs/render-guide/basics/common-props.md + - docs/render-guide/basics/layer-transform-performance.md + - docs/render-guide/advanced/reactivity.md + - docs/render-guide/advanced/events.md + - docs/render-guide/advanced/conditional-and-list-rendering.md + - docs/render-guide/advanced/hotkey-in-ui.md + - docs/render-guide/advanced/what-is-component.md + - docs/render-guide/advanced/builtin-basic.md + - docs/render-guide/advanced/builtin-layout.md + - docs/render-guide/advanced/builtin-text.md + - docs/render-guide/advanced/custom-components.md + - docs/render-guide/advanced/inventory-example-1-skeleton.md + - docs/render-guide/advanced/inventory-example-2-grid.md + - docs/render-guide/advanced/inventory-example-3-detail.md + - docs/render-guide/advanced/inventory-example-4-scroll.md + - docs/render-guide/advanced/inventory-example-5-state.md + - docs/render-guide/advanced/inventory-example-6-animation-and-register.md + - docs/render-guide/advanced/ui-system.md + - docs/render-guide/advanced/ui-performance.md +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 132000 + raw_tokens: 78000 + tasks: 7 + confidence: low +must_haves: + truths: + - "Task 0 已获用户「可以执行」,且最终路径(默认 `docs/render-guide/`)、顶部导航名(默认 `渲染指南`)、两分区映射、页面基线计数与示例待审阅口径均已确认;确认前零文件移动(D-112、D-13)" + - "`docs/render-guide/` 内部分为 `basics/`、`advanced/` 两个分区(`ui-system` / `ui-performance` 归 advanced;不创建 internals),新增 `index.md` 说明两级定位与阅读路径;两区合计收录当前树全部 27 篇 UI 文档(25 篇仅为历史记录值,不采用)" + - "旧路径 `docs/advanced/ii/ui/` 不再存在;docs 与 `docs/.vitepress/config.ts` 中不再有 `/advanced/ii/ui/` 或 `./ui/` 形式的目标链接;`docs/advanced/ii/index.md` 与 `docs/advanced/index.md` 改为指向新指南" + - "指南范围只含画屏幕 / 写 UI 的 27 篇;数据端、存档与录像、插件系统、编辑器等系统文档不迁入、不新增;`docs/render-guide/` 仅 `basics/`、`advanced/` 两个目录 + 28 个 Markdown(27 篇 + index),不创建 `internals/`" + - "所有被移动文档的 `./x.md` 内部链接按新分区重算、demo 与 `renderDemo.vue` 的导入深度由 `../../../.vitepress` 改为 `../../.vitepress`;移动不改正文(除链接/导入路径与新增 `## 前置知识` 节)" + - "每篇移入文档(含 6 篇示例)都有且仅有一个 `## 前置知识` 节,内容来自真实依赖(现有阅读顺序、实际交叉链接或正文引用),不编造前置" + - "`inventory-example-1..6` 六篇在计划与记录中保持「待审阅」;`ui-basics` / `first-static-ui` 默认也记「待审阅」,除非用户明确确认其已审阅;本计划不审阅、不改写这些页面的正文" + - "demo 保留在 `docs/.vitepress/components/demos/ui/`,不移动;demo 目录文件数、被正文引用数与 live 数在移动前后不变(规划时实测 67 个文件、65 个被引用、24 篇带 live)" + - "两份导览中不再出现「自定义 UI 与渲染」与「高级 II 的《UI 性能》」,改写后的表述指向 `docs/render-guide/`;高级 II 数据端 10 条、高级 III 分组、中级 25 条链接保留" + - "新指南正文不写审阅状态、迁移过程或修复复盘(D-97);`## 边界与注意` 只写使用边界;27 篇原有代码块在迁移与前置知识新增后逐字不变" + - "审阅谱系:19 篇按用户确认继承 10-54 状态,`ui-basics` / `first-static-ui` 默认待审阅,6 篇示例待审阅;Task 6 SUMMARY 必须写明最终状态与依据" + - "门禁全绿:prettier `--check`、`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错、`pnpm docs:build` green 且 0 dead link、导航与侧边栏无死链/无孤儿页" + - "最终用户审阅循环(结构/链接)逐轮记录在 `10-55-USER-REVIEW.md`,直到用户明确确认;未确认前不写 SUMMARY、不改 ROADMAP/STATE" + - "ROADMAP 只追加 `10-55-PLAN.md` 条目与本批增量说明,`**Plans:**` 计数行与 `10-06`/`10-11`/`10-12` 未勾选行、`**10-42 增量说明:**` 行逐字不变;STATE 计数保持基线;本计划不 commit" + artifacts: + - ".planning/phases/10-docs-restructure/10-55-INVENTORY.md(27 行页面映射、链接/导航迁移清单、渲染相关内容盘点、基线计数与哈希)" + - ".planning/phases/10-docs-restructure/10-55-USER-REVIEW.md(结构/链接审阅逐轮记录与用户确认)" + - ".planning/phases/10-docs-restructure/10-55-SUMMARY.md(迁移结果、门禁、未做事项、HEAD 与提交状态)" + - "docs/render-guide/index.md(两级定位、阅读路径、页面目录)" + - "docs/render-guide/basics/*.md、advanced/*.md(迁移后的 27 篇;advanced 含 `ui-system` / `ui-performance`)" + - "docs/.vitepress/config.ts(新增顶部导航与 `/render-guide/` 侧边栏;移除 `/advanced/ii/ui/` 分组)" + key_links: + - "页面映射表是链接迁移的唯一事实来源:目标分区决定 `./` 链接应保持同级还是改为 `../
/`" + - "文档上移一层后 demo 与 RenderDemo 导入必须由 `../../../.vitepress` 变为 `../../.vitepress`,否则构建与 live 全部失败" + - "侧边栏与导航必须与磁盘文件双向一致:侧边栏每条都能落到文件,磁盘每篇都出现在侧边栏" + - "新指南入口必须可从顶部导航与高级 II 导览两处到达,否则读者从旧入口会 404" + - "示例待审阅状态只写在计划/记录里,不写进文档正文(D-97);不得因迁移把示例当作已审阅" + - "基线固定为当前树 27 篇;10-54 的 25 篇 / 24 demo 只是历史记录。19 篇继承需用户确认谱系,`ui-basics` / `first-static-ui` 默认待审阅;不得静默把任何页面标成已审阅" +--- + + +本计划只做 D-112 的结构落地,不重写文档内容: + +- D-112 要求把**画屏幕 / 写 UI** 的内容从普通中级/高级教程中独立出来,新建「渲染指南」专页,内部按渲染基础 / 渲染进阶两层组织(UI 系统与 UI 性能归渲染进阶,不设渲染底层),并给每篇补「前置知识」。**本指南只收画屏幕与写 UI 的材料;与绘制屏幕关系不紧密的系统(数据端、存档与录像、插件系统、编辑器等)仍留在中级/高级教程,不得搬入本指南,也不得借本次迁移新增系统文档。** 本计划负责这一步的迁移、导航与前置知识;普通教程中与渲染相关内容的收敛(只讲主要逻辑)会牵动多篇正文改写,本计划只在 Task 1 盘点、不在本计划内改写,由用户在 Task 0 决定是否另开计划。 +- 迁移需要同时改动路径、内部链接、demo 导入、侧边栏、导航与两份导览;这些改动彼此耦合,分开做会出现中间态死链,因此放在同一计划的 Task 2。 +- 「前置知识」是新增章节而非内容重写,单独放在 Task 3,便于用剥离比对证明正文未变。 +- 六个示例文档与两篇新增页(`ui-basics` / `first-static-ui`)仍待审阅;本计划只迁移与补前置知识,不把它们当作已审阅。 +- 上下文控制:Task 1 只读 27 篇与配置产出映射表;Task 2/3 按 D-115 必须全量阅读现有文档,各自独立派发;Task 4 只读门禁输出与映射表;Task 5 只做用户结构/链接复验;Task 6 只做记账。 + + + +按 D-112 新建「渲染指南」(默认 `docs/render-guide/`),**只收画屏幕 / 写 UI 的现有 27 篇自定义 UI 文档**,从 `docs/advanced/ii/ui/` 迁入 `basics/`、`advanced/` 两个分区(`ui-system` / `ui-performance` 归 `advanced`,不创建 `internals/`),迁移全部内部链接、demo 导入、侧边栏、顶部导航与两份导览,并给每篇补基于真实依赖的「前置知识」;**与绘制屏幕关系不紧密的系统(数据端、存档与录像、插件、编辑器等)不迁入、不新增文档,仍留在中级/高级教程**;随后跑结构/构建门禁,交用户做结构/链接审阅循环,最后追加记账。 + +Purpose: 画屏幕与写 UI 的内容集中且深,继续散落在高级 II 子分组里既不便分层阅读,也让普通教程被迫承担原理解释。独立指南只服务「画屏幕 / 写 UI」并按深度分层,才能让不同基础的作者各取所需;无关系统仍留在普通教程(D-112)。 +Output: 新指南两区与导览页、迁移后的 27 篇、更新后的导航/侧边栏/两份导览、迁移清单与审阅记录、门禁结论。**不重写正文、不移动 demo、不审阅示例、不 commit。** + +**Phase 10 计数约定(本计划遵守):** 本阶段为伞阶段 + 增量派发,计划条目只追加;`**Plans:**` 计数行保持 `29/32 completed` 不动,计数收口另行处理(沿用 10-42 之后的约定);`10-06` / `10-11` / `10-12` 三行保持未勾选,`**10-42 增量说明:**` 行逐字不变。10-55 只在自己的条目与本批增量说明里出现。 + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@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-54-PLAN.md +@.planning/phases/10-docs-restructure/10-54-SUMMARY.md +@.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md +@docs/.vitepress/config.ts +@docs/advanced/ii/index.md +@docs/advanced/index.md + +**流程约定:** +- 只修改本计划 `files_modified` 内文件;不改前序计划与 SUMMARY、不改 `packages/` / `packages-user/` / `src/`、不改 demo、不改既有 JSDoc / 注释。 +- **Task 0 是硬关卡**:先汇报路径/导航名、两分区映射、示例待审阅口径、链接/导航迁移范围与基线计数,等用户明确回复「可以执行」四个字;未收到前不得移动任何文件。 +- 修改方式为**派发子代理执行**;派发前先声明本次是子代理执行及其范围(AGENTS.md)。 +- **D-115 强制**:任何文档修改子代理在动手前必须按文档站阅读顺序完整读完目标之外的全部现有文档,并在回报中列出已读范围与对结构/风格的判断;未完成不得修改。 +- **D-112 硬约束**:新指南分两级;每篇补 `## 前置知识`;普通中级/高级教程只讲主要逻辑(本计划盘点、不改写)。 +- **D-97 硬约束**:不把迁移说明、待审阅状态、修复复盘写进文档正文。 +- **计数用语**:本计划以当前树 **27 篇** 为唯一基线;「25 篇」只是 `10-54-SUMMARY.md` 的历史记录值,不得作为本计划的迁移或验收基线。Task 0 若用户坚持 25 篇,停止并重新规划,不在本计划内开分支。 +- `pnpm` 在 PowerShell 5.1 下经 `cmd /c "..."` 执行;文件为 CRLF + UTF-8。 +- 不调用 `opencode` 命令;不 commit(D-90,由用户确认后自行提交)。 + +**当前事实(规划时实测,执行时以 Task 1 复核为准):** +- `docs/advanced/ii/ui/` 共 **27** 篇 Markdown(`Get-ChildItem ... -Filter *.md` 计数),工作树干净且全部已跟踪(HEAD 有同名文件)。 +- `docs/.vitepress/components/demos/ui/` 共 **67** 个文件;27 篇正文以 `../../.../demos/ui/*.tsx` 形式引用其中 **65** 个唯一文件(`perf-demo.tsx`、`template-demo.tsx` 当前未被引用);有 **24** 篇正文 import `renderDemo.vue`(即有 24 个 live 入口)。 +- `docs/.vitepress/config.ts` 中 `/advanced/ii/ui/` 侧边栏链接 **27** 条;顶部 `nav` 目前只有「中级教程」「高级教程」两项;侧边栏仅定义 `'/intermediate/'` 与 `'/advanced/'` 两个键。 +- 27 篇正文内 `./x.md` 形式的相对链接(含锚点)共 **46** 处;demo 导入 **65** 处、`renderDemo.vue` 导入 **24** 处,全部使用 `../../../.vitepress/...` 前缀(相对 `docs/advanced/ii/ui/`)。 +- `docs/advanced/ii/index.md` 有 **3** 处 `./ui/...` 链接,以及 **5 处**会被本计划改写的旧表述(L15 子分组句、L52「子分组 27 篇」、L54 入口段、L81「界面绘制与 UI 系统见子分组」、L82「高级 II 的《UI 性能》」);`docs/advanced/index.md` 有 **2 处**(L38「高级 II 已收录子分组」、L39「高级 II 的《UI 性能》」)。行号按当前 HEAD,执行时以原文匹配为准。 +- `docs/tsconfig.json` 的 `include` 覆盖 `./.vitepress/**/*.ts|vue|tsx`,不含 `docs/**/*.md`;文档移动不影响该配置。 +- 现有门禁命令基线(10-54 记录):`prettier --check` 通过;`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"` green 且 0 dead link。 +- **计数口径(Task 0 只确认,不再选 25):** `10-54-SUMMARY.md` 记录 25 篇(19 已审阅 + 6 示例待审阅)/ 24 demo;当前树 27 篇 / 67 demo 文件 / 24 live。`5db2cef` 重写了页面集:10-54 的 25 篇中有 8 个旧 slug 已不在树中(`curves-and-paths` / `props` / `component-tsx` / `slots-and-attrs` / `builtin-text-and-input` / `builtin-list-and-containers` / `ui-controller-and-stack` / `replace-builtin-ui`);连同 10-48 删除的 `ui-template-ts` / `component-ts`,共 10 个旧名已消失。当前 27 篇按「19 继承 + 2 新增 + 6 示例」计:19 篇继承 10-54 的已审阅状态(含改名继承,由用户确认),**2 篇新增(`ui-basics`、`first-static-ui`)默认 `待审阅`**,6 篇示例保持 `待审阅`。旧稿从未入库,git 无法独立证明逐篇谱系,因此 19 篇的继承以用户确认为准。 +- **POC 页(待裁决):** `docs/poc/render-demo.md` 存在且不在 nav/sidebar;ROADMAP `**10-42 增量说明:**` 约定正式渲染指南落地时由用户决定其删除或迁移。本计划不默认改动它,Task 0 要求用户给出处置。 + +**拟迁移映射(Task 0 待用户确认;执行以 `10-55-INVENTORY.md` 为准):** + +| 序 | 源路径 | 目标路径 | 分区 | 侧边栏标题 | 审阅状态 | +|----|--------|----------|------|------------|----------| +| 1 | docs/advanced/ii/ui/ui-template.md | docs/render-guide/basics/ui-template.md | basics | UI 通用模板(TSX) | 已审阅(10-54 继承,须确认) | +| 2 | docs/advanced/ii/ui/ui-basics.md | docs/render-guide/basics/ui-basics.md | basics | UI 入门 | 待审阅(5db2cef 后新增,默认) | +| 3 | docs/advanced/ii/ui/first-static-ui.md | docs/render-guide/basics/first-static-ui.md | basics | 第一个静态界面 | 待审阅(5db2cef 后新增,默认) | +| 4 | docs/advanced/ii/ui/container-and-coordinates.md | docs/render-guide/basics/container-and-coordinates.md | basics | 容器与坐标 | 已审阅(10-54 继承,须确认) | +| 5 | docs/advanced/ii/ui/basic-shapes.md | docs/render-guide/basics/basic-shapes.md | basics | 基础图形 | 已审阅(10-54 继承,须确认) | +| 6 | docs/advanced/ii/ui/text.md | docs/render-guide/basics/text.md | basics | 文字 | 已审阅(10-54 继承,须确认) | +| 7 | docs/advanced/ii/ui/image-and-texture.md | docs/render-guide/basics/image-and-texture.md | basics | 图片与纹理 | 已审阅(10-54 继承,须确认) | +| 8 | docs/advanced/ii/ui/custom-and-container-custom.md | docs/render-guide/basics/custom-and-container-custom.md | basics | 自绘元素与自定义容器 | 已审阅(10-54 继承,须确认) | +| 9 | docs/advanced/ii/ui/common-props.md | docs/render-guide/basics/common-props.md | basics | 通用参数 | 已审阅(10-54 继承,须确认) | +| 10 | docs/advanced/ii/ui/layer-transform-performance.md | docs/render-guide/basics/layer-transform-performance.md | basics | 层级、变换与性能 | 已审阅(10-54 继承,须确认) | +| 11 | docs/advanced/ii/ui/reactivity.md | docs/render-guide/advanced/reactivity.md | advanced | 响应式 | 已审阅(10-54 继承,须确认) | +| 12 | docs/advanced/ii/ui/events.md | docs/render-guide/advanced/events.md | advanced | 事件与交互 | 已审阅(10-54 继承,须确认) | +| 13 | docs/advanced/ii/ui/conditional-and-list-rendering.md | docs/render-guide/advanced/conditional-and-list-rendering.md | advanced | 条件渲染与循环渲染 | 已审阅(10-54 继承,须确认) | +| 14 | docs/advanced/ii/ui/hotkey-in-ui.md | docs/render-guide/advanced/hotkey-in-ui.md | advanced | 按键与快捷键 | 已审阅(10-54 继承,须确认) | +| 15 | docs/advanced/ii/ui/what-is-component.md | docs/render-guide/advanced/what-is-component.md | advanced | 什么是组件 | 已审阅(10-54 继承,须确认) | +| 16 | docs/advanced/ii/ui/builtin-basic.md | docs/render-guide/advanced/builtin-basic.md | advanced | 内置组件:基础 | 已审阅(10-54 继承,须确认) | +| 17 | docs/advanced/ii/ui/builtin-layout.md | docs/render-guide/advanced/builtin-layout.md | advanced | 内置组件:布局 | 已审阅(10-54 继承,须确认) | +| 18 | docs/advanced/ii/ui/builtin-text.md | docs/render-guide/advanced/builtin-text.md | advanced | 内置组件:文本 | 已审阅(10-54 继承,须确认) | +| 19 | docs/advanced/ii/ui/custom-components.md | docs/render-guide/advanced/custom-components.md | advanced | 自定义组件 | 已审阅(10-54 继承,须确认) | +| 20 | docs/advanced/ii/ui/inventory-example-1-skeleton.md | docs/render-guide/advanced/inventory-example-1-skeleton.md | advanced | 示例(一)目标与骨架 | 待审阅 | +| 21 | docs/advanced/ii/ui/inventory-example-2-grid.md | docs/render-guide/advanced/inventory-example-2-grid.md | advanced | 示例(二)道具网格 | 待审阅 | +| 22 | docs/advanced/ii/ui/inventory-example-3-detail.md | docs/render-guide/advanced/inventory-example-3-detail.md | advanced | 示例(三)详情区 | 待审阅 | +| 23 | docs/advanced/ii/ui/inventory-example-4-scroll.md | docs/render-guide/advanced/inventory-example-4-scroll.md | advanced | 示例(四)滚动与列表 | 待审阅 | +| 24 | docs/advanced/ii/ui/inventory-example-5-state.md | docs/render-guide/advanced/inventory-example-5-state.md | advanced | 示例(五)交互与状态 | 待审阅 | +| 25 | docs/advanced/ii/ui/inventory-example-6-animation-and-register.md | docs/render-guide/advanced/inventory-example-6-animation-and-register.md | advanced | 示例(六)动画、拆分与注册 | 待审阅 | +| 26 | docs/advanced/ii/ui/ui-system.md | docs/render-guide/advanced/ui-system.md | advanced | UI 系统 | 已审阅(10-54 继承,须确认) | +| 27 | docs/advanced/ii/ui/ui-performance.md | docs/render-guide/advanced/ui-performance.md | advanced | UI 性能 | 已审阅(10-54 继承,须确认) | + +审阅状态口径:19 篇「10-54 继承」含改名继承,须用户在 Task 0 逐页确认(默认维持已审阅,可降为待审阅);`ui-basics` / `first-static-ui` 在 10-54 的 25 篇清单中没有对应 slug,默认 `待审阅`,除非用户明确确认它们已审阅;6 篇示例始终 `待审阅`。 + +分区侧边栏标题:`basics` = 渲染基础,`advanced` = 渲染进阶(含 `ui-system` / `ui-performance`);**不设渲染底层,不创建 `internals/`**;侧边栏组内顺序按上表序号。 + + + + + + Task 0: 汇报渲染指南路径 / 指南范围 / 导航名 / 两分区 / 示例口径 / 迁移范围,等待「可以执行」 + .planning/phases/10-docs-restructure/10-55-PLAN.md(只读;本任务不写任何文件) + .planning/phases/10-docs-restructure/10-CONTEXT.md(D-112、D-113、D-115、D-09、D-13、D-97)、.planning/phases/10-docs-restructure/10-54-SUMMARY.md、.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md、.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/ 下 27 篇文件名 + 向用户做四段汇报并停下等待。**本任务不创建、不移动、不修改任何文件。** + +**要做什么**——①按 D-112 新建「渲染指南」,**只把 `docs/advanced/ii/ui/` 下画屏幕 / 写 UI 的 27 篇自定义 UI 文档迁入两级分区;无关系统不迁入、不新增**;②新增指南导览页,说明两级定位与阅读路径;③迁移全部内部链接、demo 导入、顶部导航、侧边栏与两份导览;④给每篇补基于真实依赖的 `## 前置知识`;⑤跑结构/构建门禁;⑥交用户审阅结构/链接并逐条修订,直到用户确认;⑦追加 SUMMARY 与 ROADMAP/STATE 记账。 + +**为什么**——D-112 要求把画屏幕 / 写 UI 的内容独立成指南并按渲染基础 / 渲染进阶两层组织(`ui-system` / `ui-performance` 归渲染进阶,不设渲染底层);本指南只讲绘制屏幕与 UI 编写,数据端、存档与录像、插件、编辑器等与绘制屏幕关系不紧密的系统仍留在中级/高级教程,普通教程只保留主要渲染逻辑。当前这些 UI 文档挤在高级 II 子分组,既难分层阅读,也让普通教程承担原理讲解。 + +**大致怎么做**——Task 1 建立迁移清单与基线(含 27 行映射、链接/导航迁移项、普通教程渲染端内容盘点);Task 2 用 `git mv` 迁移并改链接/导入/导航;Task 3 逐篇补 `## 前置知识`;Task 4 跑门禁与计数核对;Task 5 用户结构/链接审阅循环;Task 6 收尾记账。**Task 0 未获「可以执行」前,Task 1..6 全部不得开始。** + +**影响范围**——新增 `docs/render-guide/` 及 28 个 Markdown(27 篇迁移 + 1 篇新导览);删除 `docs/advanced/ii/ui/` 目录;修改 `docs/.vitepress/config.ts`(nav + sidebar)、`docs/advanced/ii/index.md`、`docs/advanced/index.md`;新增/追加 4 个规划记录文件并追加 ROADMAP/STATE。**不动** demo(`docs/.vitepress/components/demos/ui/`)、`packages/`、`packages-user/`、`src/`、前序计划与 SUMMARY、既有注释。 + +**请用户裁决以下 9 项(默认值已给出,可直接说「按默认」):** +1. **路径**:默认 `docs/render-guide/`(连字符英文,符合 dev.md);备选 `docs/render/`、`docs/ui-guide/`。目录与文件名属 D-13 命名,须先获批。 +2. **顶部导航名**:默认 `渲染指南`,追加在「中级教程」「高级教程」之后,链接 `/render-guide/`;备选 `UI 渲染指南`、`UI 与渲染`。**指南只讲画屏幕 / 写 UI;无关系统留在中级/高级教程。** +3. **两分区名称**:默认目录 `basics/`、`advanced/`(`ui-system` / `ui-performance` 归 `advanced`),侧边栏显示名 `渲染基础`、`渲染进阶`;**不设渲染底层、不创建 `internals/`**;D-112 的两级名称为渲染基础 / 渲染进阶。 +4. **页面映射**:汇报时必须**逐行展示** `` 中的「拟迁移映射」全表(27 行,basics 10 / advanced 17 / internals 0(不建目录)),不得只给分区计数;请确认分区归属、侧边栏顺序与审阅状态:19 篇继承(含改名继承,默认已审阅)+ 2 篇新增(`ui-basics`、`first-static-ui`,默认待审阅)+ 6 篇示例待审阅。若认为某篇归属或状态不对,请指出篇名。 +5. **示例待审阅口径**:`inventory-example-1..6` 保持「待审阅」,本计划只迁移、补前置知识,不审阅、不改写正文;不把待审阅状态写进文档正文(D-97)。请确认。 +6. **基线计数与审阅谱系(只确认 27,不提供 25 分支)**:当前树实测 **27 篇 / 67 个 demo 文件 / 65 个被引用 / 24 个 live**;`10-54-SUMMARY.md` 的 25 篇 / 24 demo 只是历史记录值。27 篇按「19 继承 + 2 新增 + 6 示例」计:19 篇继承 10-54 的已审阅状态(含改名继承;旧稿从未入库,git 无法独立证明谱系,需你确认);`ui-basics`、`first-static-ui` 在 10-54 清单中没有对应 slug,**默认记 `待审阅`**,除非你明确确认它们也已审阅;6 篇示例保持待审阅。**本计划不提供 25 篇迁移分支**:若你要求以 25 篇为基线,Task 0 即停止并重新规划。请裁决:19 篇继承是否成立;2 篇新增是否维持待审阅(推荐)。 +7. **普通教程渲染端内容**:D-112 要求普通中级/高级教程只讲主要逻辑。本计划只盘点(Task 1 列出涉及渲染的篇目与位置),不改写正文;请确认「收敛改写另开计划」,或要求并入本计划(会引入正文改写,需要额外的用户修订循环)。 +8. **demo 位置与收尾**:demo 保留在 `docs/.vitepress/components/demos/ui/`,不移动;本计划不 commit,账号为 `13194` 时 22:00 后停止派发子代理;修改方式为派发子代理执行。 +9. **POC 页处置**:`docs/poc/render-demo.md` 是 10-42 的临时验证页,不在 nav/sidebar;ROADMAP `**10-42 增量说明:**` 约定正式渲染指南落地时由你决定删除或迁移。默认**保留不动**(本计划不改、不删、不迁移);也可选择删除,或迁入 `docs/render-guide/` 作为示例页(后者涉及导航与术语,另行规划)。 + +**指南范围(请确认)**:只收画屏幕 / 写 UI 的 27 篇自定义 UI 文档;数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统仍留在中级/高级教程,**不迁入本指南、不新增系统文档**。 + +**链接 / 导航迁移范围(汇报时必须逐项列出)**:46 处文内相对链接(含锚点)、89 处导入(65 处 demo + 24 处 `renderDemo.vue`)、`config.ts` 的 27 条 `/advanced/ii/ui/` 侧边栏链接移除、新增 1 条顶部导航与 1 个 `/render-guide/` 侧边栏键(3 组)、`docs/advanced/ii/index.md` 的 5 处旧表述(L15 / L52 / L54 / L81 / L82)与 3 处 `./ui/...` 链接、`docs/advanced/index.md` 的 L38 / L39 两处表述;demo 目录 0 改动。 + +**请用户明确回复「可以执行」四个字**,并同时给出 1–9 项的裁决(可回「按默认」)。其它回复视为未批准,不得开始 Task 1。 + 是否按本计划建立渲染指南并迁移文档,以及指南范围(仅画屏幕 / 写 UI,系统文档不迁入)、最终路径、导航名、两分区映射、示例与新增页审阅状态、页面基线、普通教程收敛安排与 POC 页处置。 + + + + + + + + + + + + 尚无产物;本任务只汇报指南范围、路径/导航名、两分区映射、审阅谱系、示例口径、链接/导航迁移范围、计数口径与 POC 处置。 + 确认:①指南只含画屏幕 / 写 UI,系统文档不迁入;②路径与导航名;③两分区名称与 27 行映射;④19 继承 + 2 新增待审阅 + 6 示例待审阅;⑤基线固定 27(不提供 25 分支);⑥普通教程收敛是否另开计划;⑦POC 页保留不动;⑧demo 不移动、不 commit、子代理执行。 + 回复「可以执行」以继续(可附「按默认」或逐项裁决)。其它回复视为未批准。 + 用户已回复「可以执行」,且指南范围(仅画屏幕 / 写 UI,系统文档不迁入)、路径、导航名、两分区与映射、审阅谱系、示例与新增页状态、27 篇基线、普通教程收敛安排、POC 处置、demo 位置与不 commit 均已确定并记录在 `10-55-INVENTORY.md`(Task 1 写入)。用户未回复前不得创建或移动任何文件。 + + 用户已回复「可以执行」,且 9 项待裁决均已确定(含 19 继承 / 2 新增待审阅 / 27 篇基线与 POC 处置)。 + + 用户回复「可以执行」且 9 项已定案。 + + + + Task 1: 建立迁移清单、基线哈希与普通教程渲染端内容盘点 + .planning/phases/10-docs-restructure/10-55-INVENTORY.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + 用户已在 Task 0 回复「可以执行」并给出 9 项裁决;用户已确认 27 篇基线与审阅谱系。**迁移已应用时 `docs/advanced/ii/ui/` 可以不存在**:以 `10-55-INVENTORY.md` 与当前 `docs/render-guide/` 实际结构为基线。 + .planning/phases/10-docs-restructure/10-CONTEXT.md(D-112、D-115)、.planning/phases/10-docs-restructure/10-54-SUMMARY.md、.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/ 下全部 27 篇、docs/intermediate/ 与 docs/advanced/ 下除 `ii/ui/` 外的全部 Markdown(只盘点渲染端涉及处) + **本任务只写规划记录,不改 `docs/`、不改 demo、不改代码。** 必须完整读完 27 篇(源目录存在时读 `docs/advanced/ii/ui/`,已迁移时读 `docs/render-guide/` 对应页面;用于判定分区与真实依赖),并按文档站阅读顺序浏览 `docs/intermediate/` → `docs/advanced/i/` → `docs/advanced/ii/`(数据端)→ `docs/advanced/iii/` 的现有文档,用于「普通教程渲染端内容」盘点与全项目结构对齐。这是 D-115 要求的全量阅读,目的有二:一是了解项目整体结构、已讲概念与文档分工,避免写出与现有内容脱节的说明;二是对齐写作风格、详略、示例、标题、术语与表格形式,避免只读目标页造成风格偏差。回报必须列出已读文档范围与对结构与风格的实际判断。 + +**(1)新建 `.planning/phases/10-docs-restructure/10-55-INVENTORY.md`**(CRLF、UTF-8),写入以下小节: + +`# 10-55 渲染指南迁移清单` + +`## 指南范围`:只收画屏幕 / 写 UI 的 27 篇自定义 UI 文档;数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统仍留在中级/高级教程,**不迁入本指南、不新增系统文档**。本节为后续映射与门禁的范围依据。 + +`## 用户裁决(Task 0)`:逐条抄录 9 项裁决原话/结论;若用户回「按默认」,逐项写默认值并注明「用户批准按默认」。 + +`## 基线`,固定行格式: +- `- BASE-HEAD:` +- `- 页面基线:27`(固定;25 只是 10-54 历史记录值,不采用) +- `- 页面实测:<27 篇的文件名清单或计数>` +- `- 10-54 记录值:25 篇(19 已审阅 + 6 待审阅)/ 24 demo` +- `- 新增页面审阅状态:ui-basics=<已审阅|待审阅>;first-static-ui=<已审阅|待审阅>`(默认均 `待审阅`) +- `- 用户确认新增页面为已审阅:是|否`(默认 `否`) +- `- POC 处置:<保留不动|删除|迁入指南(另行规划)>`(默认 `保留不动`) +- `- 指南范围:仅画屏幕 / 写 UI(27 篇);数据端 / 存档 / 插件 / 编辑器等系统文档不迁入、不新增` +- `- demo 基线:文件 ;被正文引用 ;带 live(renderDemo.vue)`(文件 = `docs/.vitepress/components/demos/ui/` 下文件数;被正文引用 = 27 篇正文中 `demos/ui/*.tsx` 的唯一文件名数;带 live = 正文出现 `components/renderDemo.vue` 的篇数) +- `- demo 目录:docs/.vitepress/components/demos/ui/` +- `- docs 快照哈希:<对 27 篇按相对路径排序、逐文件 SHA-256,拼 `相对路径:hash` 后 LF 连接再取 SHA-256>` +- `- 配置快照哈希:` +- `- 停止点:10-55 只做迁移 / 前置知识 / 结构门禁;不重写正文、不移动 demo、不审阅示例、不 commit` + +`## 页面映射`:markdown 表,列固定为 `| 序 | 源路径 | 目标路径 | 分区 | 侧边栏标题 | 审阅状态 | demo 引用数 | 内部链接数 |`;**必须恰好 27 行**,源/目标路径用仓库相对路径(正斜杠),分区只能是 `basics` / `advanced`(`ui-system` / `ui-performance` 记 `advanced`;不设 `internals`),审阅状态只能是 `已审阅` 或 `待审阅`,6 篇示例必须写 `待审阅`。表前一句:「本表是链接迁移与侧边栏生成的唯一事实来源。」 + +`## 页面谱系与审阅状态`:逐条列 19 篇继承页(`当前页 → 10-54 旧名(同名 / 改名)→ 已审阅`)、2 篇新增页(`ui-basics`、`first-static-ui → 10-54 无对应 → 待审阅`)、6 篇示例(`→ 待审阅`)。任何无法对应到 10-54 已审阅篇目的页面,默认 `待审阅`,不得标为已审阅;用户确认新增页已审阅时,改写为 `已审阅` 并记录确认原话。 + +`## 链接迁移清单`:三段。 +1. **内部 Markdown 链接**:逐条列 `源文件 → 原链接 → 迁移后链接`(含锚点原样保留)。目标规则:同一分区保持 `./x.md`;跨分区改为 `../<目标分区>/x.md`;不得改写链接文字。规划时实测 46 处,执行时以实际扫描为准,多出或少于 46 要写原因。 +2. **demo 导入**:列出每个源文件的 `../../../.vitepress/components/demos/ui/*.tsx` 与 `../../../.vitepress/components/renderDemo.vue` 迁移后应变为 `../../.vitepress/...`;记录每篇导入条数(合计规划时为 65 + 24)。 +3. **导航 / 导览**:`docs/.vitepress/config.ts` 的 27 条 `/advanced/ii/ui/` 链接移除清单、新增 nav 与 `/render-guide/` 侧边栏计划;`docs/advanced/ii/index.md` 的 5 处旧表述(L15 / L52 / L54 / L81 / L82)与 3 处 `./ui/...` 目标;`docs/advanced/index.md` 的 L38 / L39 两处表述。 + +`## 普通教程渲染端内容盘点(只盘点、不改写)`:列出 `docs/intermediate/`、`docs/advanced/i/`、`docs/advanced/ii/`(数据端)、`docs/advanced/iii/` 中涉及渲染端/UI 的篇目与大致位置(章节标题或行号范围),至少覆盖 `docs/intermediate/data-vs-render.md`、`docs/intermediate/src-tour.md`、`docs/advanced/i/index.md`、`docs/advanced/index.md`、`docs/advanced/ii/index.md`;每条写「涉及内容 + 是否应在后续收敛为指引链接」。本节只记录,不提出改写方案、不改文件;**这些系统文档不迁入本指南,也不新增到 `docs/render-guide/`**。 + +`## 待确认项`:若 Task 0 有未定项(如新增页审阅状态未确认、POC 处置未定),列在此处并写「阻塞 Task 2」。 + +**(2)向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-55 渲染指南迁移`**,写入:用户确认原话、9 项裁决摘要、`BASE-HEAD`、页面基线与实测、新增页审阅状态与依据、POC 处置、demo 基线与目录、docs/配置快照哈希、`迁移范围:docs/advanced/ii/ui/ → docs/render-guide/{basics,advanced}/`、`示例口径:1..6 保持待审阅,不审阅正文`、`停止点:10-55 迁移前清单已建立`。 + +**(3)一致性自检**:页面映射必须为 27 行;分区计数必须为 10 / 17 / 0(basics / advanced / 不建 internals);19 行 `已审阅`(若用户确认新增页已审阅则 21 行)+ `ui-basics` / `first-static-ui` 与 `新增页面审阅状态` 一致 + 6 行示例 `待审阅`;`docs/.vitepress/components/demos/ui/` 文件数必须与基线一致。任一不符:停止并报告,不得进入 Task 2。 + + $ErrorActionPreference='Stop'; $inv='.planning/phases/10-docs-restructure/10-55-INVENTORY.md'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; if(-not(Test-Path -LiteralPath $inv)){ Write-Error 'MISSING-INVENTORY' }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $inv)); foreach($k in @('# 10-55 渲染指南迁移清单','## 指南范围','## 用户裁决(Task 0)','## 基线','## 页面映射','## 链接迁移清单','## 页面谱系与审阅状态','## 普通教程渲染端内容盘点(只盘点、不改写)','## 待确认项')){ if($t.IndexOf($k) -lt 0){ Write-Error "INV-MISSING $k" } }; $pb=[regex]::Match($t,'(?m)^- 页面基线:\s*(\d+)\s*$'); if(-not $pb.Success){ Write-Error 'NO-PAGE-BASELINE' }; if([int]$pb.Groups[1].Value -ne 27){ Write-Error 'PAGE-BASELINE-NOT-27' }; $rows=[regex]::Matches($t,'(?m)^\|\s*\d+\s*\|\s*docs/advanced/ii/ui/[a-z0-9-]+\.md\s*\|\s*docs/render-guide/(basics|advanced)/[a-z0-9-]+\.md\s*\|'); if($rows.Count -ne 27){ Write-Error ("MAPPING-ROWS:"+$rows.Count) }; $pending=[regex]::Matches($t,'(?m)^\|\s*\d+\s*\|[^\r\n]*inventory-example-[1-6][^\r\n]*\|\s*待审阅\s*\|'); if($pending.Count -ne 6){ Write-Error ("PENDING-ROWS:"+$pending.Count) }; if($t -match '(?m)^\|\s*\d+\s*\|[^\r\n]*inventory-example-[1-6][^\r\n]*\|\s*已审阅\s*\|'){ Write-Error 'EXAMPLE-MARKED-REVIEWED' }; foreach($k in @('- BASE-HEAD:','- demo 基线:','- demo 目录:docs/.vitepress/components/demos/ui/','- docs 快照哈希:','- 配置快照哈希:','- 停止点:10-55 只做迁移')){ if($t.IndexOf($k) -lt 0){ Write-Error "INV-MISSING $k" } }; if($t -notmatch '(?m)^- BASE-HEAD:[0-9a-f]{7,40}$'){ Write-Error 'BAD-BASE-HEAD' }; if($t -notmatch '(?m)^- docs 快照哈希:[0-9a-f]{64}$'){ Write-Error 'BAD-DOCS-HASH' }; $ns=[regex]::Match($t,'(?m)^- 新增页面审阅状态:ui-basics=(已审阅|待审阅);first-static-ui=(已审阅|待审阅)$'); if(-not $ns.Success){ Write-Error 'NO-NEW-STATUS' }; if($t -notmatch '(?m)^- 用户确认新增页面为已审阅:(是|否)$'){ Write-Error 'NO-NEW-CONFIRM' }; if($t -notmatch '(?m)^- POC 处置:(保留不动|删除|迁入指南(另行规划))$'){ Write-Error 'NO-POC-DISPOSITION' }; if($t -notmatch '(?m)^- 指南范围:仅画屏幕 / 写 UI(27 篇)'){ Write-Error 'NO-SCOPE-LINE' }; foreach($pair in @(@('ui-basics',$ns.Groups[1].Value),@('first-static-ui',$ns.Groups[2].Value))){ $pg=$pair[0]; $st=$pair[1]; if($t -notmatch ('(?m)^\|\s*\d+\s*\|[^\r\n]*'+[regex]::Escape($pg)+'\.md[^\r\n]*\|\s*'+$st+'\s*\|')){ Write-Error ("NEW-PAGE-STATUS-MISMATCH:"+$pg) } }; if($t -match '(?m)^- 用户确认新增页面为已审阅:否$'){ if($ns.Groups[1].Value -ne '待审阅' -or $ns.Groups[2].Value -ne '待审阅'){ Write-Error 'NEW-PAGES-NOT-PENDING' } }; $rev=[regex]::Matches($t,'(?m)^\|\s*\d+\s*\|[^\r\n]*\|\s*已审阅\s*\|').Count; if($t -match '(?m)^- 用户确认新增页面为已审阅:是$'){ if($rev -ne 21){ Write-Error ("REVIEWED-COUNT:"+$rev) } } else { if($rev -ne 19){ Write-Error ("REVIEWED-COUNT:"+$rev) } }; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np.IndexOf('## 10-55 渲染指南迁移') -lt 0){ Write-Error 'NOTES-MISSING-SECTION' }; if($np -notmatch '(?m)^停止点:10-55 迁移前清单已建立'){ Write-Error 'NOTES-MISSING-STOP' }; $demo=(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -File).Count; if($demo -le 0){ Write-Error 'NO-DEMOS' }; if($t.IndexOf('demos/ui/') -lt 0){ Write-Error 'NO-DEMO-SECTION' }; $ui=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -ErrorAction SilentlyContinue).Count; if($ui -gt 0 -and $ui -ne 27){ Write-Error ("PRE-MOVE-PAGE-COUNT:"+$ui) }; if($ui -eq 0){ $rg=@(Get-ChildItem -LiteralPath 'docs/render-guide' -Recurse -Filter *.md | Where-Object { $_.Name -ne 'index.md' }).Count; if($rg -ne 27){ Write-Error ("MOVED-PAGE-COUNT:"+$rg) } }; $docsOut=cmd /c "git status --porcelain -- docs" 2>&1; $docsExit=$LASTEXITCODE; if($docsExit -ne 0){ Write-Error 'GIT-STATUS-FAIL' }; if(($docsOut | Out-String).Trim().Length -gt 0 -and -not (Test-Path -LiteralPath 'docs/render-guide/index.md')){ Write-Error 'DOCS-MODIFIED-IN-INVENTORY' }; 'T1-OK' + non-zero exit, or output contains "MISSING-INVENTORY", "INV-MISSING", "NO-PAGE-BASELINE", "PAGE-BASELINE-NOT-27", "MAPPING-ROWS", "PENDING-ROWS", "EXAMPLE-MARKED-REVIEWED", "NO-NEW-STATUS", "NO-NEW-CONFIRM", "NO-POC-DISPOSITION", "NO-SCOPE-LINE", "NEW-PAGE-STATUS-MISMATCH", "NEW-PAGES-NOT-PENDING", "REVIEWED-COUNT", "BAD-BASE-HEAD", "BAD-DOCS-HASH", "NOTES-MISSING", "NO-DEMOS", "PRE-MOVE-PAGE-COUNT", "MOVED-PAGE-COUNT", "DOCS-MODIFIED-IN-INVENTORY"; or output lacks "T1-OK" + + `10-55-INVENTORY.md` 含 `## 指南范围`(仅画屏幕 / 写 UI,系统文档不迁入)、用户 9 项裁决、基线(BASE-HEAD / 页面基线 27 / 页面实测 / 10-54 记录值 / 新增页面审阅状态 / 用户确认新增页为已审阅 / POC 处置 / 指南范围 / demo 基线 / 快照哈希 / 停止点)、页面映射表(27 行、两区、19 已审阅 + 2 新增按确认值 + 6 示例待审阅)、`## 页面谱系与审阅状态`、链接迁移三段清单、普通教程渲染端内容盘点、待确认项;NOTES 追加 `## 10-55 渲染指南迁移` 与停止点;`docs/` 与 demo 未被修改;未 commit。 + 迁移清单、基线与盘点记录已就绪,可据此执行移动。 + + + + Task 2: 迁移 UI 文档(默认 27 篇)到两区 + 链接 / demo 导入 / 导航 / 侧边栏 / 导览迁移 + 新指南导览页 + docs/render-guide/index.md, docs/render-guide/basics/*.md, docs/render-guide/advanced/*.md, docs/.vitepress/config.ts, docs/advanced/ii/index.md, docs/advanced/index.md + Task 1 已写入 `10-55-INVENTORY.md` 的页面映射、链接迁移清单与基线;用户已确认路径、导航名与两分区;若迁移已应用(源不存在、目标存在),按清单核对目标结构;否则按清单迁移。 + .planning/phases/10-docs-restructure/10-55-INVENTORY.md(页面映射、链接迁移清单、用户裁决)、docs/.vitepress/config.ts(nav、`/intermediate/`、`/advanced/` 侧边栏全文)、docs/advanced/ii/index.md(含 5 处旧表述与 3 处 `./ui/` 链接)、docs/advanced/index.md(三层结构表与「边界与注意」L38 / L39)、docs/advanced/ii/ui/ 下全部 27 篇、docs/intermediate/ 与 docs/advanced/ 其余现有文档 + **本任务只做路径、链接、导入、导航与新导览页;不改正文、不改代码、不移动 demo、不补前置知识(留给 Task 3)。** + +**D-115(原文,强制):** 任何文档修改子代理在动手前,必须先按文档站阅读顺序完整读完目标文档之外的全部现有文档:中级 → 高级 I → 高级 II 现有数据端/其他已存在篇目 → 高级 III → 其他非目标文档;读完后才能读目标文档和相关源码。未完成全量阅读不得修改,不得以「只读了相关源码/目标页」代替。阅读目的有二:一是了解项目整体结构、已讲概念与文档分工,避免写出与现有内容脱节的说明;二是对齐文档的写作风格、详略、示例、标题、术语与表格形式,避免只读目标页造成风格偏差。不得只列阅读清单而不说明目的,也不得把「读文档」本身当成任务。回报必须列出已读文档范围及对结构与风格的实际判断;未列出、未读全或未说明目的的改动一律视为不合格,必须重做。派发子代理时,必须把这段原文完整写入子代理任务。 + +**(1)迁移文件(按 `10-55-INVENTORY.md` 的 `## 页面映射` 表逐行执行)** +- 先 `New-Item -ItemType Directory -Force` 建 `docs/render-guide/basics`、`docs/render-guide/advanced`;**不创建 `docs/render-guide/internals`**。 +- 用 `git mv <源> <目标>` 逐条迁移(27 条;禁止 `Move-Item`,保留历史);**源已不存在且目标已存在时跳过 `git mv`,只核对内容哈希与清单一致**;每迁移一篇立刻核对文件存在、内容哈希与迁移前一致。迁移后 `docs/advanced/ii/ui/` 必须为空并删除;本计划不保留任何未迁移页面。 +- 不得改文件名 slug,不得改 H1 标题以外的正文;发现源文件名与清单不一致:停止并报告。 + +**(2)内部 Markdown 链接** +按 `## 链接迁移清单` 的逐条映射改写 46 处 `./x.md` 链接(含 `#锚点`):同分区保持 `./x.md`,跨分区改为 `../<目标分区>/x.md`;链接文字、锚点与所在句子不得改动。迁移后逐篇扫一遍,不得留下指向已不存在同级文件的 `./x.md`。 + +**(3)demo 与 RenderDemo 导入** +27 篇中的 `import RenderDemo from '../../../.vitepress/components/renderDemo.vue';` 与全部 `import('../../../.vitepress/components/demos/ui/*.tsx')` 前缀改为 `../../.vitepress/...`;只改路径前缀,不改组件名、变量名、导入顺序或代码块外的其它文字。**demo 文件本身不得移动、不得重命名、不得修改。** 迁移后逐篇核对导入条数与清单一致(规划时 65 + 24)。 + +**(4)`docs/.vitepress/config.ts`** +- `nav` 追加 `{ text: '渲染指南', link: '/render-guide/' }`(放在「高级教程」之后;名称以 Task 0 裁决为准)。 +- 删除 `sidebar['/advanced/']` 中整个「自定义 UI 与渲染」分组(含 27 条链接;真实键名是 `'/advanced/'`,不存在 `/advanced/ii/` 键),高级 II 数据端 10 条与高级 III 分组逐字保留;`/intermediate/` 不动。 +- 新增 `sidebar['/render-guide/']`,按**两组**组织:`text: '渲染基础'`(basics 10 条)、`text: '渲染进阶'`(advanced 17 条,含 `ui-system` / `ui-performance`);**不建渲染底层组、不引用 `internals`**;每条 `text` 用清单的侧边栏标题、`link` 用 `/render-guide/<分区>/`;顺序按清单序号。 +- 除上述外不改 config(`custom` 数组、`vite`、`search`、`locales` 等逐字保留)。 + +**(5)两份导览(按当前原文匹配,不按行号盲改;只改下列 7 处)** +- `docs/advanced/ii/index.md`: + - L15:把「这一层的主体是数据端;另有自定义 UI 与渲染子分组(见侧边栏),面向要在画布上写界面的作者。」改为「这一层的主体是数据端;要在画布上写界面的作者见[渲染指南](../../render-guide/)。」 + - L52:把「本层一共十篇(这一页导览 + 九篇数据端正文),另有「自定义 UI 与渲染」子分组 27 篇(见侧边栏)。」改为「本层一共十篇(这一页导览 + 九篇数据端正文);画屏幕 / 写 UI 的内容已独立为[渲染指南](../../render-guide/)。」 + - L54:整段替换为「画屏幕 / 写 UI 的阅读入口与两级路径见[渲染指南](../../render-guide/);本层不再重复。」(原段中的 3 处 `./ui/...` 链接随之移除) + - L81:把「界面绘制与 UI 系统见子分组「自定义 UI 与渲染」。」改为「界面绘制与 UI 系统见[渲染指南](../../render-guide/)。」 + - L82:把「高级 II 的《UI 性能》讲缓存与显示策略的取舍,引擎级性能仍属高级 III。」改为「[《UI 性能》](../../render-guide/advanced/ui-performance)在渲染指南中讲缓存与显示策略的取舍,引擎级性能仍属高级 III。」 + - 其余内容(数据端目录表、三条阅读路径、其它边界条目、继续阅读 9 条)逐字保留。 +- `docs/advanced/index.md`: + - L38:把「高级 II 已收录「自定义 UI 与渲染」子分组,本层其它篇目仍以数据端为主;」改为「画屏幕 / 写 UI 的内容已独立为[渲染指南](../render-guide/);本层其它篇目仍以数据端为主;」(保留其后的编辑器占位句)。 + - L39:把「高级 II 的《UI 性能》讲缓存与显示策略的取舍,引擎级性能仍属高级 III。」改为「渲染指南的[《UI 性能》](../render-guide/advanced/ui-performance)讲缓存与显示策略的取舍,引擎级性能仍属高级 III。」 + - 「三层结构」表 L12 当前不含「自定义 UI 与渲染」,**不得**为它新增该短语;表格其它单元格逐字保留。 +- 不得新增死链;不得写「后续再讲 / 暂未完成」等元叙述(D-16、D-97)。 + +**(6)新建 `docs/render-guide/index.md`(单 H1)** +必须包含且只包含读者需要的信息,全部基于现有事实与清单: +1. H1 `# 渲染指南`;一段说明本指南**只讲画屏幕 / 写 UI** 与中级/高级教程的分工:数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统不在这里讲,仍见普通教程;普通教程只讲主要渲染逻辑(D-112)。**本指南只收现有 27 篇 UI 文档,不新增系统文档、不增列系统页面。** +2. `## 两级结构`:表格列出两区(`渲染基础` / `渲染进阶`)、定位与页面数(10 / 17);说明 `ui-system` / `ui-performance` 属渲染进阶,**不设渲染底层**。 +3. `## 适合谁`:分三种读者(完全没写过 UI / 写过基础界面想加交互与组件 / 想了解 UI 系统与性能),每条给出起点页链接。 +4. `## 阅读路径`:至少三条路径(从基础顺读;只想做界面;想改内置 UI 或做性能取舍),每条只由真实存在的页面组成;路径依据取自现有 `docs/advanced/ii/index.md` 的起步顺序与 phase-10 记录,不得编造。 +5. `## 页面目录`:三张分表(每区一张),列 `篇目 / 一句话说明 / 前置`;`篇目` 必须链接到本指南内页面(相对链接),`一句话说明` 取自该篇 H1 与开头一段的既有表述(不新增功能承诺),`前置` 与 Task 3 将写入的 `## 前置知识` 一致(Task 3 若据证据调整前置,必须同步回改本表)。 +6. `## 边界与注意`:只写画屏幕 / 写 UI 的使用边界(如 demo 在文档站内的展示限制、预览尺寸与真实画布的区别,取自现有文档已讲事实);**不得**写审阅状态、迁移过程、修复复盘或任何元叙述(D-97),不得写源码级叙述(D-80)。示例 1–6 的待审阅状态只存在于计划/清单,正文不出现,也不得写成「待审阅 / 未审阅 / 已修复」。 +- 新页必须满足:单 H1、标题均为名词短语(D-108)、无断链、无被禁写法。 + +**(7)回报与自检**:列出迁移的 27 组源/目标、改写的链接条数、导入条数、config 改动位置、两份导览改动句子、新导览页结构;并做一次本地构建确认无 dead link 后再进入 Task 3。 + + $ErrorActionPreference='Stop'; $inv='.planning/phases/10-docs-restructure/10-55-INVENTORY.md'; if(-not(Test-Path -LiteralPath $inv)){ Write-Error 'MISSING-INVENTORY' }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $inv)); $pb=[regex]::Match($t,'(?m)^- 页面基线:\s*(\d+)\s*$'); if(-not $pb.Success){ Write-Error 'NO-PAGE-BASELINE' }; $base=[int]$pb.Groups[1].Value; $rows=[regex]::Matches($t,'(?m)^\|\s*\d+\s*\|\s*(docs/advanced/ii/ui/[a-z0-9-]+\.md)\s*\|\s*(docs/render-guide/(?:basics|advanced)/[a-z0-9-]+\.md)\s*\|'); if($rows.Count -ne $base){ Write-Error ("MAPPING-ROWS:"+$rows.Count) }; foreach($r in $rows){ $src=$r.Groups[1].Value; $dst=$r.Groups[2].Value; if(Test-Path -LiteralPath $src){ Write-Error "SRC-STILL-EXISTS:$src" }; if(-not(Test-Path -LiteralPath $dst)){ Write-Error "DST-MISSING:$dst" } }; $leftUi=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -ErrorAction SilentlyContinue); if($leftUi.Count -gt 0){ Write-Error ('OLD-UI-LEFT:'+$leftUi.Count) }; $pages=@(Get-ChildItem -LiteralPath 'docs/render-guide' -Recurse -Filter *.md | Where-Object { $_.Name -ne 'index.md' }); if($pages.Count -ne $base){ Write-Error ("PAGE-COUNT:"+$pages.Count) }; if(-not(Test-Path -LiteralPath 'docs/render-guide/index.md')){ Write-Error 'NO-GUIDE-INDEX' }; $idx=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/render-guide/index.md')); if($idx -notmatch '(?m)^# 渲染指南\s*$'){ Write-Error 'NO-GUIDE-H1' }; foreach($k in @('## 两级结构','## 适合谁','## 阅读路径','## 页面目录','渲染基础','渲染进阶')){ if($idx.IndexOf($k) -lt 0){ Write-Error "GUIDE-MISSING $k" } }; $idxLinks=[regex]::Matches($idx,'\./(?:basics|advanced)/[a-z0-9-]+\.md') | ForEach-Object { $_.Value } | Sort-Object -Unique; if($idxLinks.Count -ne $base){ Write-Error ("GUIDE-LINKS:"+$idxLinks.Count) }; $cfg=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); if($cfg.IndexOf('渲染指南') -lt 0){ Write-Error 'NO-NAV-TEXT' }; if($cfg -notmatch "'/render-guide/'"){ Write-Error 'NO-NAV-LINK' }; if($cfg -match "'/advanced/ii/ui/"){ Write-Error 'OLD-SIDEBAR-KEY' }; $rl=[regex]::Matches($cfg,"'(/render-guide/(?:basics|advanced)/[a-z0-9-]+)'") | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique; if($rl.Count -ne $base){ Write-Error ("SIDEBAR-COUNT:"+$rl.Count) }; foreach($l in $rl){ $p='docs'+($l -replace '/','\')+'.md'; if(-not(Test-Path -LiteralPath $p)){ Write-Error "SIDEBAR-DEAD:$l" } }; foreach($f in $pages){ $rel='/render-guide/' + (($f.FullName.Substring((Get-Location).Path.Length+1) -replace '\\','/') -replace '^docs/render-guide/','' -replace '\.md$',''); if($rl -notcontains $rel){ Write-Error "ORPHAN:$rel" } }; $old=@(); $old+=@(Get-ChildItem -Path 'docs' -Recurse -Filter *.md | Select-String -Pattern '/advanced/ii/ui/|\./ui/'); $old+=@(Get-ChildItem -Path 'docs/.vitepress' -Filter *.ts -File | Select-String -Pattern '/advanced/ii/ui/|\./ui/'); if($old.Count -gt 0){ $old | ForEach-Object { Write-Error ("OLD-LINK:"+$_.Path+":"+$_.LineNumber) } }; $bad=@(Get-ChildItem -Path 'docs/render-guide' -Recurse -Filter *.md | Select-String -Pattern '\.\./\.\./\.\./\.vitepress/components'); if($bad.Count -gt 0){ Write-Error 'BAD-IMPORT-DEPTH' }; $deep=@(Get-ChildItem -Path 'docs/render-guide' -Recurse -Filter *.md | Select-String -Pattern '\.vitepress/components'); foreach($h in $deep){ if($h.Line -notmatch '\.\./\.\./\.vitepress/components'){ Write-Error ("IMPORT-NOT-2UP:"+$h.Path) } }; $aii=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); if($aii -match '\(\./ui/'){ Write-Error 'AII-OLD-UI-LINK' }; if($aii.IndexOf('../../render-guide/') -lt 0){ Write-Error 'AII-NO-GUIDE-LINK' }; $adv=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/index.md')); if($adv.IndexOf('../render-guide/') -lt 0){ Write-Error 'ADV-NO-GUIDE-LINK' }; foreach($bp in @('自定义 UI 与渲染','高级 II 的《UI 性能》')){ if($aii.IndexOf($bp) -ge 0){ Write-Error ("AII-STALE:"+$bp) }; if($adv.IndexOf($bp) -ge 0){ Write-Error ("ADV-STALE:"+$bp) } }; foreach($dl in @('custom-range','static-vs-dynamic-tiles','point-and-tile-events','equipment-system','custom-replay-command','pathfinding','adding-hero-attribute','adding-enemy-attribute','enemy-context-and-combat')){ if($aii.IndexOf(('./'+$dl+'.md')) -lt 0){ Write-Error ("AII-DATA-LINK-MISSING:"+$dl) } }; foreach($al in @('](./i/)','](./ii/)','](./iii/)')){ if($adv.IndexOf($al) -lt 0){ Write-Error ("ADV-LINK-MISSING:"+$al) } }; if($idx.IndexOf('## 边界与注意') -lt 0){ Write-Error 'GUIDE-NO-BOUNDARY' }; $cfgInt=[regex]::Matches($cfg,"'/intermediate/[a-z0-9-]+'") | ForEach-Object { $_.Value } | Sort-Object -Unique; if($cfgInt.Count -ne 25){ Write-Error ("CFG-INTERMEDIATE-COUNT:"+$cfgInt.Count) }; $intOut=cmd /c "git status --porcelain -- docs/intermediate" 2>&1; $intExit=$LASTEXITCODE; if($intExit -ne 0){ Write-Error 'GIT-STATUS-FAIL' }; if(($intOut | Out-String).Trim().Length -gt 0){ Write-Error 'INTERMEDIATE-MODIFIED' }; $d97=@(Get-ChildItem -Path 'docs/render-guide' -Recurse -Filter *.md | Select-String -Pattern '待审阅|未审阅|已修复|审阅记录'); if($d97.Count -gt 0){ Write-Error 'GUIDE-META-NARRATION' }; $demoOut=cmd /c "git status --porcelain -- docs/.vitepress/components/demos/ui" 2>&1; $demoExit=$LASTEXITCODE; $demoStatus=($demoOut | Out-String).Trim(); if($demoExit -ne 0){ Write-Error 'GIT-STATUS-FAIL' }; if($demoStatus.Length -gt 0){ Write-Error 'DEMOS-MODIFIED' }; $tmp=Join-Path $env:TEMP ('10-55-old-'+[guid]::NewGuid().ToString('N')+'.md'); function CodeBlocks([string]$x){ $ls=(($x -replace "`r`n","`n") -split "`n"); $in=$false; $buf=@(); $out=@(); foreach($l in $ls){ if($l -match '^```'){ if($in){ $out+=($buf -join "`n"); $buf=@() }; $in=-not $in; continue }; if($in){ $buf+=$l } }; ($out -join "`n===\n") }; function Strip([string]$x){ $x=$x.TrimStart([char]0xFEFF); $ls=(($x -replace "`r`n","`n") -split "`n"); $k=@(); $skip=$false; foreach($l in $ls){ if($l -match "^## 前置知识\s*$"){ $skip=$true; continue }; if($skip){ if($l.Trim() -eq '' -or $l -match '^- ' -or $l -match '^阅读本篇前' -or $l -match '^无——'){ continue }; $skip=$false }; if($l -match '^\s*import\b'){ continue }; if($l -match '^\s*import\('){ continue }; if($l -match '\.vitepress/components'){ continue }; if($l -match '\]\(\.{1,2}/'){ continue }; $k+=(($l -replace '\s+',' ').Trim()) }; $k=@($k | Where-Object { $_ -ne '' }); ($k -join "`n").Trim() }; foreach($r in $rows){ $src=$r.Groups[1].Value; $dst=$r.Groups[2].Value; cmd /c "git show HEAD:$src > `"$tmp`""; if($LASTEXITCODE -ne 0){ Write-Error "GIT-SHOW-FAIL:$src" }; $o=[IO.File]::ReadAllText($tmp,[Text.Encoding]::UTF8); $nw=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $dst),[Text.Encoding]::UTF8); if((Strip $o) -ne (Strip $nw)){ Write-Error "CONTENT-REWRITTEN:$dst" }; if((CodeBlocks $o) -ne (CodeBlocks $nw)){ Write-Error ("CODEBLOCK-CHANGED:"+$dst) } }; Remove-Item -LiteralPath $tmp -ErrorAction SilentlyContinue; $b=cmd /c "pnpm exec tsx docs/.vitepress/init.ts" 2>&1; if($LASTEXITCODE -ne 0){ $b | Write-Output; Write-Error 'INIT-FAIL' }; $bld=cmd /c "pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $bld | Write-Output; Write-Error 'BUILD-FAIL' }; if(($bld | Out-String) -match 'dead link'){ $bld | Write-Output; Write-Error 'DEAD-LINK' }; 'T2-OK' + non-zero exit, or output contains "MISSING-INVENTORY", "NO-PAGE-BASELINE", "MAPPING-ROWS", "SRC-STILL-EXISTS", "DST-MISSING", "OLD-UI-LEFT", "PAGE-COUNT", "NO-GUIDE-INDEX", "NO-GUIDE-H1", "GUIDE-MISSING", "GUIDE-LINKS", "NO-NAV-TEXT", "NO-NAV-LINK", "OLD-SIDEBAR-KEY", "SIDEBAR-COUNT", "SIDEBAR-DEAD", "ORPHAN", "OLD-LINK", "BAD-IMPORT-DEPTH", "IMPORT-NOT-2UP", "AII-OLD-UI-LINK", "AII-NO-GUIDE-LINK", "ADV-NO-GUIDE-LINK", "AII-STALE", "ADV-STALE", "AII-DATA-LINK-MISSING", "ADV-LINK-MISSING", "GUIDE-NO-BOUNDARY", "CFG-INTERMEDIATE-COUNT", "INTERMEDIATE-MODIFIED", "GUIDE-META-NARRATION", "DEMOS-MODIFIED", "GIT-STATUS-FAIL", "GIT-SHOW-FAIL", "CONTENT-REWRITTEN", "CODEBLOCK-CHANGED", "INIT-FAIL", "BUILD-FAIL", "DEAD-LINK"; or output lacks "T2-OK" + + 按清单迁移全部 27 篇到 `docs/render-guide/{basics,advanced}/`,旧目录删除;**指南只含画屏幕 / 写 UI 的 27 篇 + index,无系统文档、无额外目录、不创建 `internals/`**;46 处内部链接按分区重算;89 处导入前缀改为 `../../.vitepress/`(65 demo + 24 RenderDemo);config 有 nav `渲染指南` 与 `/render-guide/` 两组侧边栏、旧 UI 分组与 `/advanced/ii/ui/` 链接清零、`/intermediate/` 25 条不变;两份导览按 7 处指定原文改写,不再含 `自定义 UI 与渲染` 与 `高级 II 的《UI 性能》`,高级 II 数据端 9 条与高级 III 入口保留;新导览页含单 H1、两级结构、适合谁、阅读路径、全部页面链接、`## 边界与注意`,且正文无审阅元叙述(D-97);剥离链接/导入行后逐篇正文与 HEAD 逐字一致(无正文改写);demo 目录无改动;构建 green 且无 dead link。 + 27 篇完成迁移,链接、导入、导航与两份导览全部指向新指南,正文未改写、无审阅元叙述。 + + + + Task 3: 逐篇补 `## 前置知识`(全部移入文档,默认 27 篇,基于真实依赖) + docs/render-guide/basics/*.md, docs/render-guide/advanced/*.md, .planning/phases/10-docs-restructure/10-55-INVENTORY.md + Task 2 通过(迁移、链接、导入、导航与导览已改完;正文与 HEAD 逐字一致);`docs/render-guide/` 页面数等于基线。 + .planning/phases/10-docs-restructure/10-55-INVENTORY.md(页面映射、链接迁移清单)、docs/render-guide/index.md、docs/render-guide/ 下全部 27 篇、docs/advanced/ii/index.md(原起步顺序与阅读路径表述)、docs/intermediate/ 与 docs/advanced/ 其余现有文档 + **本任务只新增 `## 前置知识` 节并同步导览页的前置列;不改其它正文、不改代码块、不改 demo、不改待审阅状态。** + +**D-115(原文,强制):** 任何文档修改子代理在动手前,必须先按文档站阅读顺序完整读完目标文档之外的全部现有文档:中级 → 高级 I → 高级 II 现有数据端/其他已存在篇目 → 高级 III → 其他非目标文档;读完后才能读目标文档和相关源码。未完成全量阅读不得修改,不得以「只读了相关源码/目标页」代替。阅读目的有二:一是了解项目整体结构、已讲概念与文档分工,避免写出与现有内容脱节的说明;二是对齐文档的写作风格、详略、示例、标题、术语与表格形式,避免只读目标页造成风格偏差。不得只列阅读清单而不说明目的,也不得把「读文档」本身当成任务。回报必须列出已读文档范围及对结构与风格的实际判断;未列出、未读全或未说明目的的改动一律视为不合格,必须重做。派发子代理时,必须把这段原文完整写入子代理任务。 + +**(1)页面计划(逐篇执行,路径为迁移后目标路径)** + +| 目标页 | 拟写前置(按证据确认后落笔) | +|--------|------------------------------| +| basics/ui-template.md | 无(只需基础 TS/JS;本页是模板入口) | +| basics/ui-basics.md | 无(只需基础 TS/JS) | +| basics/first-static-ui.md | basics/ui-basics.md | +| basics/container-and-coordinates.md | basics/first-static-ui.md | +| basics/basic-shapes.md | basics/container-and-coordinates.md | +| basics/text.md | basics/container-and-coordinates.md、basics/basic-shapes.md | +| basics/image-and-texture.md | basics/container-and-coordinates.md | +| basics/custom-and-container-custom.md | basics/container-and-coordinates.md、basics/basic-shapes.md | +| basics/common-props.md | basics/container-and-coordinates.md、basics/basic-shapes.md | +| basics/layer-transform-performance.md | basics/container-and-coordinates.md、basics/common-props.md | +| advanced/reactivity.md | basics/ui-basics.md、basics/first-static-ui.md | +| advanced/events.md | basics/container-and-coordinates.md、advanced/reactivity.md | +| advanced/conditional-and-list-rendering.md | advanced/reactivity.md、advanced/events.md | +| advanced/hotkey-in-ui.md | advanced/reactivity.md、advanced/events.md | +| advanced/what-is-component.md | basics/ui-basics.md | +| advanced/builtin-basic.md | advanced/what-is-component.md | +| advanced/builtin-layout.md | advanced/what-is-component.md、advanced/builtin-basic.md | +| advanced/builtin-text.md | advanced/what-is-component.md、advanced/builtin-basic.md | +| advanced/custom-components.md | advanced/what-is-component.md、advanced/builtin-basic.md | +| advanced/inventory-example-1-skeleton.md | basics/first-static-ui.md、basics/container-and-coordinates.md | +| advanced/inventory-example-2-grid.md | advanced/inventory-example-1-skeleton.md、basics/basic-shapes.md | +| advanced/inventory-example-3-detail.md | advanced/inventory-example-2-grid.md、basics/text.md、basics/common-props.md | +| advanced/inventory-example-4-scroll.md | advanced/inventory-example-3-detail.md、advanced/builtin-layout.md | +| advanced/inventory-example-5-state.md | advanced/inventory-example-4-scroll.md、advanced/reactivity.md、advanced/events.md | +| advanced/inventory-example-6-animation-and-register.md | advanced/inventory-example-5-state.md、advanced/custom-components.md、advanced/ui-system.md | +| advanced/ui-system.md | advanced/events.md | +| advanced/ui-performance.md | basics/layer-transform-performance.md、advanced/ui-system.md | + +**证据规则(防编造)**:每个前置必须至少满足其一——①该页在现有 `docs/advanced/ii/index.md` 的起步顺序 / 阅读路径 / Part 顺序中位于目标页之前;②目标页正文实际引用了该页讲的概念、接口或示例;③目标页现有交叉链接指向该页。三条都不满足的,从该页前置中删去并在记录中写原因;不得为了「看起来完整」保留无依据前置。 + +**(2)写入格式**(每篇一次,位置固定为**紧邻第一个 `##` 的上一行**,即插入在首个 `##` 之前;若首个 `##` 之前已有代码块(如 `ui-template.md` 的模板代码),前置节放在该代码块之后、首个 `##` 之前,禁止插入代码块内部或 H1 之前;不得插在正文段落中间): +- 标题固定 `## 前置知识`(名词短语,D-108)。 +- 标题下一句:「阅读本篇前,建议先读完:」;无前置时写「无——只要掌握基础 TS/JS,并按本指南的阅读路径阅读即可。」 +- 有前置时用无序列表,每项为相对链接 + 页面标题(如 `- [UI 入门](./ui-basics.md)`;跨区用 `../advanced/reactivity.md`)。 +- 只列文档,不写解释性长句、不复制前置篇内容、不写「后面再讲」类元叙述(D-16、D-97),不写源码叙述(D-80)。 +- **示例 1–6 同样只新增本节**;正文、代码块、live 与待审阅状态一律不动。 + +**(3)同步 `docs/render-guide/index.md` 的「页面目录」前置列**:按实际写入结果更新,使导览与各篇一致。 + +**(4)向 `10-55-INVENTORY.md` 追加 `## 前置知识依据`**:表头 `| 目标页 | 实际写入的前置 | 依据(阅读顺序 / 正文引用 / 交叉链接) |`,27 行;`目标页` 列写仓库相对路径(如 `docs/render-guide/basics/text.md`,与页面映射一致),`实际写入的前置` 列写目标路径或「无」;删除或调整过拟写前置的,在依据列写明原因。 + +**(5)回报**:列出 27 篇实际前置、调整项及依据、导览同步结果、每篇只新增一节的证明(`## 前置知识` 计数)。 + + $ErrorActionPreference='Stop'; $inv='.planning/phases/10-docs-restructure/10-55-INVENTORY.md'; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $inv)); $pb=[regex]::Match($t,'(?m)^- 页面基线:\s*(\d+)\s*$'); if(-not $pb.Success){ Write-Error 'NO-PAGE-BASELINE' }; $base=[int]$pb.Groups[1].Value; $rows=[regex]::Matches($t,'(?m)^\|\s*\d+\s*\|\s*(docs/advanced/ii/ui/[a-z0-9-]+\.md)\s*\|\s*(docs/render-guide/(?:basics|advanced)/[a-z0-9-]+\.md)\s*\|'); if($rows.Count -ne $base){ Write-Error ("MAPPING-ROWS:"+$rows.Count) }; $pages=@(Get-ChildItem -LiteralPath 'docs/render-guide' -Recurse -Filter *.md | Where-Object { $_.Name -ne 'index.md' }); if($pages.Count -ne $base){ Write-Error ("PAGE-COUNT:"+$pages.Count) }; foreach($f in $pages){ $ft=[IO.File]::ReadAllText($f.FullName); $c=[regex]::Matches($ft,'(?m)^## 前置知识\s*$').Count; if($c -ne 1){ Write-Error ("PREREQ-COUNT:"+$f.Name+":"+$c) } }; $prereq=[regex]::Match($t,'(?ms)^## 前置知识依据\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; $pr=[regex]::Matches($prereq,'(?m)^\|\s*[^|]*docs/render-guide/[a-z]+/[a-z0-9-]+\.md[^|]*\|'); if($pr.Count -lt $base){ Write-Error ("PREREQ-EVIDENCE-ROWS:"+$pr.Count) }; if($t -notmatch '(?m)^\|\s*\d+\s*\|[^\r\n]*inventory-example-[1-6][^\r\n]*\|\s*待审阅\s*\|'){ Write-Error 'EXAMPLES-NOT-PENDING' }; $idx=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/render-guide/index.md')); $idxLinks=[regex]::Matches($idx,'\./(?:basics|advanced)/[a-z0-9-]+\.md') | ForEach-Object { $_.Value } | Sort-Object -Unique; if($idxLinks.Count -ne $base){ Write-Error ("GUIDE-LINKS:"+$idxLinks.Count) }; $tmp=Join-Path $env:TEMP ('10-55-old-'+[guid]::NewGuid().ToString('N')+'.md'); function CodeBlocks([string]$x){ $ls=(($x -replace "`r`n","`n") -split "`n"); $in=$false; $buf=@(); $out=@(); foreach($l in $ls){ if($l -match '^```'){ if($in){ $out+=($buf -join "`n"); $buf=@() }; $in=-not $in; continue }; if($in){ $buf+=$l } }; ($out -join "`n===\n") }; function Strip([string]$x){ $x=$x.TrimStart([char]0xFEFF); $ls=(($x -replace "`r`n","`n") -split "`n"); $k=@(); $skip=$false; foreach($l in $ls){ if($l -match "^## 前置知识\s*$"){ $skip=$true; continue }; if($skip){ if($l.Trim() -eq '' -or $l -match '^- ' -or $l -match '^阅读本篇前' -or $l -match '^无——'){ continue }; $skip=$false }; if($l -match '^\s*import\b'){ continue }; if($l -match '^\s*import\('){ continue }; if($l -match '\.vitepress/components'){ continue }; if($l -match '\]\(\.{1,2}/'){ continue }; $k+=(($l -replace '\s+',' ').Trim()) }; $k=@($k | Where-Object { $_ -ne '' }); ($k -join "`n").Trim() }; foreach($r in $rows){ $src=$r.Groups[1].Value; $dst=$r.Groups[2].Value; cmd /c "git show HEAD:$src > `"$tmp`""; if($LASTEXITCODE -ne 0){ Write-Error "GIT-SHOW-FAIL:$src" }; $o=[IO.File]::ReadAllText($tmp,[Text.Encoding]::UTF8); $nw=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $dst),[Text.Encoding]::UTF8); if((Strip $o) -ne (Strip $nw)){ Write-Error "CONTENT-REWRITTEN:$dst" }; if((CodeBlocks $o) -ne (CodeBlocks $nw)){ Write-Error ("CODEBLOCK-CHANGED:"+$dst) } }; Remove-Item -LiteralPath $tmp -ErrorAction SilentlyContinue; $demoOut=cmd /c "git status --porcelain -- docs/.vitepress/components/demos/ui" 2>&1; $demoExit=$LASTEXITCODE; $demoStatus=($demoOut | Out-String).Trim(); if($demoExit -ne 0){ Write-Error 'GIT-STATUS-FAIL' }; if($demoStatus.Length -gt 0){ Write-Error 'DEMOS-MODIFIED' }; 'T3-OK' + non-zero exit, or output contains "NO-PAGE-BASELINE", "MAPPING-ROWS", "PAGE-COUNT", "PREREQ-COUNT", "PREREQ-EVIDENCE-ROWS", "EXAMPLES-NOT-PENDING", "GUIDE-LINKS", "GIT-SHOW-FAIL", "CONTENT-REWRITTEN", "CODEBLOCK-CHANGED", "DEMOS-MODIFIED"; or output lacks "T3-OK" + + 27 篇各有且仅有一个 `## 前置知识`,前置只含真实依赖并以相对链接给出;`10-55-INVENTORY.md` 的 `## 前置知识依据` 覆盖全部页面并写明依据/调整原因;导览「页面目录」前置列与正文一致;示例 6 篇与 `ui-basics` / `first-static-ui` 按确认值保持待审阅,正文未改;剥离前置段/链接行/导入行后与 HEAD 逐字一致;代码块内容与 HEAD 逐字一致;demo 无改动。 + 27 篇前置知识补齐且有依据,正文除新增节外未变。 + + + + Task 4: 全量门禁(结构 / 链接 / 类型 / 构建 / 计数 / 示例待审阅) + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 2 与 Task 3 通过;`docs/render-guide/` 为最终结构;用户尚未开始 Task 5 审阅。 + .planning/phases/10-docs-restructure/10-55-INVENTORY.md(基线、映射、链接清单)、docs/render-guide/index.md、docs/.vitepress/config.ts、docs/advanced/ii/index.md、docs/advanced/index.md + **按固定顺序跑门禁,任一失败即停止并报告,不得跳过、不得放宽断言。** + +**(1)结构门禁**:页面数 = 27;`docs/render-guide/` 总计 28 个 `.md`(27 篇 + index),目录仅 `basics` / `advanced`(不建 `internals/`),**无系统文档**;`docs/render-guide/index.md` 存在;旧目录 `docs/advanced/ii/ui/` 不存在;docs 与 `docs/.vitepress/*.ts` 无 `/advanced/ii/ui/` 或 `./ui/` 链接;`docs/advanced/ii/index.md` 有 `../../render-guide/` 且不再含 `自定义 UI 与渲染` / `高级 II 的《UI 性能》`,9 个数据端 `./*.md` 链接仍在;`docs/advanced/index.md` 有 `../render-guide/` 且同样不含上述两条旧表述,`./i/`、`./ii/`、`./iii/` 链接仍在。 + +**(2)导航门禁**:`config.ts` nav 含 `渲染指南` 与 `/render-guide/`;sidebar 的 `/render-guide/` 链接数 = 页面基线且每一条能落到 `.md`;磁盘每篇都出现在侧边栏(无孤儿页);`'/advanced/'` 侧边栏中的旧「自定义 UI 与渲染」分组已移除、数据端 10 条与高级 III 分组仍在;`/intermediate/` 条目数不变。 + +**(3)导入与 live 门禁**:`docs/render-guide/**/*.md` 中所有 `.vitepress/components` 导入均为 `../../.vitepress/...`;不存在 `../../../.vitepress/components`;demo 目录 `git status --porcelain` 为空;demo 文件数 = 基线;正文引用 demo 的唯一文件数 = 基线;带 `renderDemo.vue` 的篇数 = 基线。 + +**(4)文档结构门禁**:27 篇各有且仅有一个 `## 前置知识`;示例 6 篇在清单中仍为 `待审阅`;`ui-basics` / `first-static-ui` 的映射状态与清单 `新增页面审阅状态` 一致(默认 `待审阅`);`10-54-SUMMARY.md`、`10-54-USER-REVIEW.md` 未被修改(`git status --porcelain` 为空);`docs/poc/render-demo.md` 未被修改;无 `## 前置知识` 以外的正文变化(复用 Task 3 的剥离比对与代码块比对,直接在本任务重跑);新指南正文无 `待审阅` / `未审阅` / `已修复` / `审阅记录`(D-97);`docs/intermediate/` 与 config 的 24 条中级链接未变。 + +**(5)格式门禁**:`cmd /c "pnpm exec prettier --check docs/render-guide docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md"` 退出码 0;若失败先 `--write` 再 `--check`,并把格式化前后差异限定在空白/表格宽度。 + +**(6)类型门禁**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,断言 `docs/` 路径报错 0;既有引擎报错条数只记录、不修(10-54 基线 11 条)。 + +**(7)构建门禁**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts"` 后 `cmd /c "pnpm docs:build"`,要求 exit 0、输出无 dead link、`build complete`;产物 `public/_docs/render-guide/**/*.html` 数量 = 页面基线 + 1。 + +**(8)记录**:向 `10-CUSTOM-UI-NOTES.md` 追加 `### 10-55 门禁`,写六类命令与结果、`docs/` 路径报错 0、既有引擎报错条数、构建耗时、页面/导入/demo 计数、示例待审阅结论、旧链接清零结论、`docs` 迁移后快照哈希。**不改 ROADMAP / STATE、不写 SUMMARY、不 commit。** + + $ErrorActionPreference='Stop'; $inv='.planning/phases/10-docs-restructure/10-55-INVENTORY.md'; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $inv)); $pb=[regex]::Match($t,'(?m)^- 页面基线:\s*(\d+)\s*$'); if(-not $pb.Success){ Write-Error 'NO-PAGE-BASELINE' }; $base=[int]$pb.Groups[1].Value; $dm=[regex]::Match($t,'(?m)^- demo 基线:文件\s*(\d+);被正文引用\s*(\d+);带 live(renderDemo\.vue)\s*(\d+)'); if(-not $dm.Success){ Write-Error 'NO-DEMO-BASELINE' }; $demoFiles=[int]$dm.Groups[1].Value; $demoRefs=[int]$dm.Groups[2].Value; $demoLive=[int]$dm.Groups[3].Value; $leftUi=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -ErrorAction SilentlyContinue); if($leftUi.Count -gt 0){ Write-Error ('OLD-UI-LEFT:'+$leftUi.Count) }; $pages=@(Get-ChildItem -LiteralPath 'docs/render-guide' -Recurse -Filter *.md | Where-Object { $_.Name -ne 'index.md' }); if($pages.Count -ne $base){ Write-Error ("PAGE-COUNT:"+$pages.Count) }; $idx=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/render-guide/index.md')); if($idx -notmatch '(?m)^# 渲染指南\s*$'){ Write-Error 'NO-GUIDE-H1' }; $cfg=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); if($cfg.IndexOf('渲染指南') -lt 0 -or $cfg -notmatch "'/render-guide/'"){ Write-Error 'NAV-MISSING' }; if($cfg -match "'/advanced/ii/ui/"){ Write-Error 'OLD-SIDEBAR-KEY' }; $rl=[regex]::Matches($cfg,"'(/render-guide/(?:basics|advanced)/[a-z0-9-]+)'") | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique; if($rl.Count -ne $base){ Write-Error ("SIDEBAR-COUNT:"+$rl.Count) }; foreach($l in $rl){ if(-not(Test-Path -LiteralPath ('docs'+($l -replace '/','\')+'.md'))){ Write-Error "SIDEBAR-DEAD:$l" } }; foreach($f in $pages){ $rel='/render-guide/' + (($f.FullName.Substring((Get-Location).Path.Length+1) -replace '\\','/') -replace '^docs/render-guide/','' -replace '\.md$',''); if($rl -notcontains $rel){ Write-Error "ORPHAN:$rel" } }; $old=@(); $old+=@(Get-ChildItem -Path 'docs' -Recurse -Filter *.md | Select-String -Pattern '/advanced/ii/ui/|\./ui/'); $old+=@(Get-ChildItem -Path 'docs/.vitepress' -Filter *.ts -File | Select-String -Pattern '/advanced/ii/ui/|\./ui/'); if($old.Count -gt 0){ $old | ForEach-Object { Write-Error ("OLD-LINK:"+$_.Path+":"+$_.LineNumber) } }; $deep=@(Get-ChildItem -Path 'docs/render-guide' -Recurse -Filter *.md | Select-String -Pattern '\.\./\.\./\.\./\.vitepress/components'); if($deep.Count -gt 0){ Write-Error 'BAD-IMPORT-DEPTH' }; foreach($f in $pages){ $ft=[IO.File]::ReadAllText($f.FullName); if([regex]::Matches($ft,'(?m)^## 前置知识\s*$').Count -ne 1){ Write-Error ("PREREQ-COUNT:"+$f.Name) } }; $pending=[regex]::Matches($t,'(?m)^\|\s*\d+\s*\|[^\r\n]*inventory-example-[1-6][^\r\n]*\|\s*待审阅\s*\|'); if($pending.Count -ne 6){ Write-Error ("PENDING-ROWS:"+$pending.Count) }; foreach($p in @('.planning/phases/10-docs-restructure/10-54-SUMMARY.md','.planning/phases/10-docs-restructure/10-54-USER-REVIEW.md')){ $stOut=cmd /c "git status --porcelain -- $p" 2>&1; $stExit=$LASTEXITCODE; $st=($stOut | Out-String).Trim(); if($stExit -ne 0){ Write-Error "GIT-STATUS-FAIL:$p" }; if($st.Length -gt 0){ Write-Error "10-54-MODIFIED:$p" } }; $demoOut=cmd /c "git status --porcelain -- docs/.vitepress/components/demos/ui" 2>&1; $demoExit=$LASTEXITCODE; $demoStatus=($demoOut | Out-String).Trim(); if($demoExit -ne 0){ Write-Error 'GIT-STATUS-FAIL' }; if($demoStatus.Length -gt 0){ Write-Error 'DEMOS-MODIFIED' }; $df=(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -File).Count; if($df -ne $demoFiles){ Write-Error ("DEMO-FILE-COUNT:"+$df) }; $allText=($pages | ForEach-Object { [IO.File]::ReadAllText($_.FullName) }) -join "`n"; $refs=[regex]::Matches($allText,'demos/ui/([a-z0-9-]+\.tsx)') | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique; if($refs.Count -ne $demoRefs){ Write-Error ("DEMO-REF-COUNT:"+$refs.Count) }; $live=($pages | Where-Object { [IO.File]::ReadAllText($_.FullName) -match 'components/renderDemo\.vue' }).Count; if($live -ne $demoLive){ Write-Error ("DEMO-LIVE-COUNT:"+$live) }; $pchk=cmd /c "pnpm exec prettier --check docs/render-guide docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md" 2>&1; if($LASTEXITCODE -ne 0){ $pchk | Write-Output; Write-Error 'PRETTIER-FAIL' }; $ts=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErrs=@($ts | Where-Object { $_ -match '^\s*docs[\\/].*error TS' }); if($docErrs.Count -ne 0){ $docErrs | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $init=cmd /c "pnpm exec tsx docs/.vitepress/init.ts" 2>&1; if($LASTEXITCODE -ne 0){ $init | Write-Output; Write-Error 'INIT-FAIL' }; $bld=cmd /c "pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $bld | Write-Output; Write-Error 'BUILD-FAIL' }; if(($bld | Out-String) -match 'dead link'){ $bld | Write-Output; Write-Error 'DEAD-LINK' }; $html=@(Get-ChildItem -LiteralPath 'public/_docs/render-guide' -Recurse -Filter *.html -ErrorAction SilentlyContinue); if($html.Count -ne ($base+1)){ Write-Error ("HTML-COUNT:"+$html.Count) }; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md')); if($np -notmatch "(?m)^### 10-55 门禁\s*$"){ Write-Error 'NOTES-NO-GATE-SECTION' }; $aii=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); $adv=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/index.md')); foreach($bp in @('自定义 UI 与渲染','高级 II 的《UI 性能》')){ if($aii.IndexOf($bp) -ge 0){ Write-Error ("AII-STALE:"+$bp) }; if($adv.IndexOf($bp) -ge 0){ Write-Error ("ADV-STALE:"+$bp) } }; foreach($dl in @('custom-range','static-vs-dynamic-tiles','point-and-tile-events','equipment-system','custom-replay-command','pathfinding','adding-hero-attribute','adding-enemy-attribute','enemy-context-and-combat')){ if($aii.IndexOf(('./'+$dl+'.md')) -lt 0){ Write-Error ("AII-DATA-LINK-MISSING:"+$dl) } }; foreach($al in @('](./i/)','](./ii/)','](./iii/)')){ if($adv.IndexOf($al) -lt 0){ Write-Error ("ADV-LINK-MISSING:"+$al) } }; $cfgInt=[regex]::Matches($cfg,"'/intermediate/[a-z0-9-]+'") | ForEach-Object { $_.Value } | Sort-Object -Unique; if($cfgInt.Count -ne 25){ Write-Error ("CFG-INTERMEDIATE-COUNT:"+$cfgInt.Count) }; $intOut=cmd /c "git status --porcelain -- docs/intermediate" 2>&1; $intExit=$LASTEXITCODE; if($intExit -ne 0){ Write-Error 'GIT-STATUS-FAIL' }; if(($intOut | Out-String).Trim().Length -gt 0){ Write-Error 'INTERMEDIATE-MODIFIED' }; if($idx.IndexOf('## 边界与注意') -lt 0){ Write-Error 'GUIDE-NO-BOUNDARY' }; $d97=@(Get-ChildItem -Path 'docs/render-guide' -Recurse -Filter *.md | Select-String -Pattern '待审阅|未审阅|已修复|审阅记录'); if($d97.Count -gt 0){ Write-Error 'GUIDE-META-NARRATION' }; $ns=[regex]::Match($t,"(?m)^- 新增页面审阅状态:ui-basics=(已审阅|待审阅);first-static-ui=(已审阅|待审阅)$"); if(-not $ns.Success){ Write-Error 'NO-NEW-STATUS' }; foreach($pair in @(@('ui-basics',$ns.Groups[1].Value),@('first-static-ui',$ns.Groups[2].Value))){ $pg=$pair[0]; $st=$pair[1]; if($t -notmatch ('(?m)^\|\s*\d+\s*\|[^\r\n]*'+[regex]::Escape($pg)+'\.md[^\r\n]*\|\s*'+$st+'\s*\|')){ Write-Error ("NEW-PAGE-STATUS-MISMATCH:"+$pg) } }; $pocOut=cmd /c "git status --porcelain -- docs/poc" 2>&1; $pocExit=$LASTEXITCODE; if($pocExit -ne 0){ Write-Error 'GIT-STATUS-FAIL' }; if(($pocOut | Out-String).Trim().Length -gt 0){ Write-Error 'POC-MODIFIED' }; $allMd=@(Get-ChildItem -LiteralPath 'docs/render-guide' -Recurse -Filter *.md); if($allMd.Count -ne ($base+1)){ Write-Error ("GUIDE-TOTAL-DOCS:"+$allMd.Count) }; $dirNames=@(Get-ChildItem -LiteralPath 'docs/render-guide' -Directory | ForEach-Object { $_.Name } | Sort-Object); if(($dirNames -join ',') -ne 'advanced,basics'){ Write-Error ("GUIDE-DIR-COUNT:"+($dirNames -join ',')) }; 'T4-OK' + non-zero exit, or output contains "NO-PAGE-BASELINE", "NO-DEMO-BASELINE", "OLD-UI-LEFT", "PAGE-COUNT", "NO-GUIDE-H1", "NAV-MISSING", "OLD-SIDEBAR-KEY", "SIDEBAR-COUNT", "SIDEBAR-DEAD", "ORPHAN", "OLD-LINK", "BAD-IMPORT-DEPTH", "PREREQ-COUNT", "PENDING-ROWS", "AII-STALE", "ADV-STALE", "AII-DATA-LINK-MISSING", "ADV-LINK-MISSING", "CFG-INTERMEDIATE-COUNT", "INTERMEDIATE-MODIFIED", "GUIDE-NO-BOUNDARY", "GUIDE-META-NARRATION", "NO-NEW-STATUS", "NEW-PAGE-STATUS-MISMATCH", "POC-MODIFIED", "GUIDE-TOTAL-DOCS", "GUIDE-DIR-COUNT", "10-54-MODIFIED", "DEMOS-MODIFIED", "DEMO-FILE-COUNT", "DEMO-REF-COUNT", "DEMO-LIVE-COUNT", "PRETTIER-FAIL", "DOCS-TYPE-ERROR", "INIT-FAIL", "BUILD-FAIL", "DEAD-LINK", "HTML-COUNT", "NOTES-NO-GATE-SECTION"; or output lacks "T4-OK" + + 结构、导航、导入、文档结构、格式、类型、构建七类门禁全部通过:页面数 = 27、`docs/render-guide` 仅 28 md / 2 目录且无系统文档、旧目录与旧链接清零、侧边栏双向可达、导入均为两级上跳、27 篇前置节各一、示例 6 篇与 `ui-basics` / `first-static-ui` 按确认值待审阅、两份导览无旧子分组/旧性能表述且数据端与 III/中级链接仍在、新指南无审阅元叙述、demo 计数不变、prettier 0、`docs/` 路径 0 类型报错、构建 green 无 dead link、HTML = 27 + 1;NOTES 有 `### 10-55 门禁`;未改 ROADMAP / STATE、未写 SUMMARY、未 commit。 + 全量门禁通过并已记录。 + + + + Task 5: 用户结构 / 链接审阅与修订循环(直到用户明确确认) + .planning/phases/10-docs-restructure/10-55-USER-REVIEW.md, .planning/phases/10-docs-restructure/10-55-INVENTORY.md, docs/render-guide/*.md, docs/render-guide/*/*.md, docs/.vitepress/config.ts, docs/advanced/ii/index.md, docs/advanced/index.md + Task 4 通过;用户可启动文档站;`10-55-USER-REVIEW.md` 尚未创建或已有轮次记录。 + .planning/phases/10-docs-restructure/10-55-INVENTORY.md(映射、前置依据、门禁)、docs/render-guide/index.md、docs/render-guide/ 下全部页面、docs/.vitepress/config.ts、docs/advanced/ii/index.md、docs/advanced/index.md + **本任务由用户主导,只审结构与链接,不审示例内容、不重写正文。** + +1. **提交审阅对象**:启动 `cmd /c "pnpm docs:dev"`(或 `docs:preview`),把新指南交给用户:顶部导航「渲染指南」、`/render-guide/` 侧边栏两组、指南导览页、27 篇页面、高级 II 导览与高级教程总导览里的新入口。**不**要求用户审阅示例 1–6 的正文(仍待审阅),只确认它们已被迁入且未被当作已审阅。 +2. **创建/追加 `10-55-USER-REVIEW.md`**(CRLF、UTF-8、append-only): + - 标题 `# 10-55 结构 / 链接审阅记录`;一句说明「只记录结构、导航、链接与前置知识的意见;不含示例正文审阅」。 + - 每轮 `### 第 N 轮`(N 从 1 递增),逐条 `U-01`、`U-02`…:用户原话(逐字)、用户裁决(改 / 不改 / 改成什么)、`实际改动:`(文件 + 位置)或 `未改 — <原话>`。 + - 用户本轮无意见时写 `U-00:无意见` 与 `用户裁决:不改`,保留轮次标题。 +3. **修订规则**: + - 只改用户点名项;路径名、导航名、分区名若要改,先更新 `10-55-INVENTORY.md` 与 `config.ts`,再统一改链接,并重跑 Task 4 全部门禁。 + - 前置知识的调整必须有证据(阅读顺序 / 正文引用 / 交叉链接),并在 `## 前置知识依据` 同步更新;不得为迎合意见编造依赖。 + - **不得**改写正文、代码块、demo、待审阅状态;不得把审阅过程写进文档正文(D-97)。 + - 每轮结束后把门禁结果写回 NOTES 的 `### 10-55 门禁` 或追加 `### 10-55 门禁(第 N 轮)`。 + - 修订若涉及文档正文、链接或前置知识,派发子代理前必须把 D-115 原文完整写入子代理任务并说明阅读目的;回报须列出已读范围与结构/风格判断。 +4. **循环直到用户明确确认**:只有用户明确说「确认 / 审阅结束」才在 NOTES 追加独占两行 `用户确认(10-55):可以执行` 与 `用户原文:<原话>`,并写 `结构审阅:已完成`;未确认前不得进入 Task 6、不得写 SUMMARY / ROADMAP / STATE。 +5. 历史轮次逐字保留,不得覆盖或合并。 + 迁移后的两级指南、导航/侧边栏、两份导览入口与逐篇前置知识;每轮按用户意见修订并保持门禁绿。 + 请用户确认:①顶部导航与侧边栏能到达全部页面;②导览页两级定位与阅读路径可读;③页内链接与锚点可点;④前置知识是否成立;⑤示例 1–6 与 `ui-basics` / `first-static-ui` 已迁入且按 Task 0 确认的状态保持待审阅;⑥无正文改写。 + 逐条给出意见与裁决;全部结束后回复「确认」或「审阅结束」。 + `10-55-USER-REVIEW.md` 有逐轮 `### 第 N 轮` 与 `U-XX` 记录(原话、裁决、改动);判「不改」的未被改;改动只落在点名项;每轮门禁通过;NOTES 有 `用户确认(10-55):可以执行`、`用户原文:`、`结构审阅:已完成`;示例仍待审阅、正文未改写;未写 SUMMARY、未改 ROADMAP / STATE、未 commit。 + + 用户已明确确认结构与链接;审阅记录完整、判「不改」项未被改动、示例仍为待审阅。 + + 用户确认结构/链接,审阅与修订记录完整。 + + + + Task 6: 收尾:SUMMARY + NOTES + ROADMAP / STATE 追加(不改计数行、不 commit) + .planning/phases/10-docs-restructure/10-55-SUMMARY.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md, .planning/ROADMAP.md, .planning/STATE.md + NOTES 含 `用户确认(10-55):可以执行`、`用户原文:`、`结构审阅:已完成`;Task 4 门禁通过且 Task 5 各轮未破坏门禁。 + .planning/ROADMAP.md(Phase 10 的 `**Plans:**` 行、Plans 列表末尾、`**10-42 增量说明:**`)、.planning/STATE.md:1-70 与 `### Roadmap Evolution`、.planning/phases/10-docs-restructure/10-54-PLAN.md(Task 5 追加体例)、.planning/phases/10-docs-restructure/10-54-SUMMARY.md(SUMMARY 与 HEAD 三行体例)、.planning/phases/10-docs-restructure/10-55-INVENTORY.md、10-55-USER-REVIEW.md、10-CUSTOM-UI-NOTES.md + **(1)写 `.planning/phases/10-docs-restructure/10-55-SUMMARY.md`**(CRLF):问题(画屏幕 / 写 UI 的文档挤在高级 II、缺分层与前置)、方案(`docs/render-guide/` 两分区 + 导览 + 迁移;只收 27 篇 UI 文档,系统文档留在普通教程)、27 篇映射摘要(两区计数)、链接/导入/导航迁移结果、前置知识依据来源、门禁结论、用户结构审阅结论(意见条数、改/不改各几条)、计数口径(27 固定、25 为历史)与审阅谱系(新增页面审阅状态:ui-basics=…;first-static-ui=…;19 继承 / 6 示例待审阅)、**未做事项**(未重写正文、未移动 demo、未审阅示例 1–6、未做普通教程中渲染相关内容收敛、未 commit)、D-112 后续项;并写 HEAD 三行(各自独占一行):`BASE-HEAD: `、`CURRENT-HEAD: `、`PLAN-FILES-COMMITTED: none`。 + +**(2)向 `10-CUSTOM-UI-NOTES.md` 追加**:`用户确认(10-55)` 原文、最终页面计数与两区计数、新增页审阅状态与依据、POC 处置、迁移后 docs 快照哈希、门禁摘要、示例待审阅结论、停止点 `停止点:10-55 渲染指南迁移完成`。 + +**(3)`Edit` 追加 `.planning/ROADMAP.md`**:在 Phase 10 Plans 列表末尾(`10-54-PLAN.md` 行之后)追加一行 `- [x] 10-55-PLAN.md — 渲染指南迁移(只收画屏幕 / 写 UI 的 27 篇 → `docs/render-guide/` 两级分区;导航/侧边栏/导览与链接迁移;逐篇前置知识;示例 1-6 仍待审阅)`;随后追加一句 `**10-55 增量说明:** 本计划只追加自身条目,`**Plans:**` 计数行不因本批改动(收口另行处理);`10-06` / `10-11` / `10-12` 保持未勾选;普通教程中渲染相关内容收敛未在本计划执行。` **不得**改 Goal、`**Plans:**` 计数行、`**10-42 增量说明:**` 行、其它 Phase、`10-06`/`10-11`/`10-12` 三行、`10-33`..`10-41` 条目。 + +**(4)`Edit` 更新 `.planning/STATE.md`**:frontmatter 只改 `stopped_at` / `last_updated` / `last_activity` / `last_activity_desc`;`progress.total_plans` 与 `progress.completed_plans` 保持 134 / 126;`Current Position` 的 `Plan:` 与 `Last activity:` 各追加本计划一句;`Progress:` 行追加「另:渲染指南已建立并完成 27 篇迁移与前置知识(只收画屏幕 / 写 UI,系统文档仍留在普通教程)」;`### Roadmap Evolution` 末尾追加一条本批记录。不得改 Decisions / Deferred Items / Blockers。 + +**(5)不 commit、不 push。** 回报:SUMMARY 路径、ROADMAP 追加行与说明、STATE 改动字段、门禁结果、未提交证明(`git log ..HEAD -- <本批路径>` 为空且 `git status --porcelain -- <本批路径>` 非空)。 + + $ErrorActionPreference='Stop'; $inv='.planning/phases/10-docs-restructure/10-55-INVENTORY.md'; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $inv)); $bh=[regex]::Match($t,'(?m)^- BASE-HEAD:([0-9a-f]{7,40})\s*$'); if(-not $bh.Success){ Write-Error 'NO-BASE-HEAD' }; $base=$bh.Groups[1].Value; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md')); foreach($k in @('用户确认(10-55):可以执行','结构审阅:已完成','停止点:10-55 渲染指南迁移完成')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-USER-QUOTE' }; $sp=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/phases/10-docs-restructure/10-55-SUMMARY.md')); foreach($k in @('BASE-HEAD:','CURRENT-HEAD:','PLAN-FILES-COMMITTED: none','未做','前置知识','门禁','示例 1–6','审阅谱系','新增页面审阅状态','渲染指南')){ if($sp.IndexOf($k) -lt 0){ Write-Error "SUMMARY-MISSING $k" } }; if($sp -notmatch ('(?m)^BASE-HEAD: '+[regex]::Escape($base)+'$')){ Write-Error 'BASE-HEAD-MISMATCH' }; if($sp -match "(?&1; if($LASTEXITCODE -ne 0){ Write-Error 'ROADMAP-DIFF-FAIL' }; $removed=@($rd | Where-Object { $_ -match '^-' -and $_ -notmatch '^---' }); foreach($r in $removed){ if($r -match '10-06-PLAN|10-11-PLAN|10-12-PLAN|10-42 增量说明|\*\*Plans:\*\*'){ Write-Error ("ROADMAP-PROTECTED-CHANGED:"+$r) } }; $st=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); if($st -notmatch '(?m)^\s*total_plans:\s*134\s*$'){ Write-Error 'STATE-TOTAL-CHANGED' }; if($st -notmatch '(?m)^\s*completed_plans:\s*126\s*$'){ Write-Error 'STATE-COMPLETED-CHANGED' }; if($st.IndexOf('渲染指南') -lt 0){ Write-Error 'STATE-NO-BATCH' }; $paths=@('docs/render-guide','docs/advanced/ii','docs/advanced/index.md','docs/.vitepress/config.ts','.planning/ROADMAP.md','.planning/STATE.md','.planning/phases/10-docs-restructure/10-55-INVENTORY.md','.planning/phases/10-docs-restructure/10-55-USER-REVIEW.md','.planning/phases/10-docs-restructure/10-55-SUMMARY.md','.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'); $log=cmd /c "git log --oneline $base..HEAD -- $($paths -join ' ')" 2>&1; if($LASTEXITCODE -ne 0){ 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){ Write-Error 'GIT-STATUS-FAIL' }; if(($status | Out-String).Trim().Length -eq 0){ Write-Error 'PLAN-FILE-CLEAN' }; 'CLOSEOUT-OK' + non-zero exit, or output contains "NO-BASE-HEAD", "NOTES-MISSING", "NO-USER-QUOTE", "SUMMARY-MISSING", "BASE-HEAD-MISMATCH", "SUMMARY-LF-ONLY", "ROADMAP-NO-1055", "ROADMAP-NO-NOTE", "ROADMAP-PLANS-CHANGED", "ROADMAP-PROTECTED-MISSING", "ROADMAP-DIFF-FAIL", "ROADMAP-PROTECTED-CHANGED", "STATE-TOTAL-CHANGED", "STATE-COMPLETED-CHANGED", "STATE-NO-BATCH", "GIT-LOG-FAIL", "PLAN-FILES-COMMITTED", "GIT-STATUS-FAIL", "PLAN-FILE-CLEAN"; or output lacks "CLOSEOUT-OK" + + SUMMARY 完整(问题/方案/映射/迁移/前置依据/门禁/用户审阅/计数口径与审阅谱系/未做事项/HEAD 三行);NOTES 有用户确认、结构审阅完成、停止点;ROADMAP 追加 10-55 条目与 `**10-55 增量说明:**`,`**Plans:** 29/32 completed` 与四类受保护行逐字不变;STATE 计数 134/126 不变且追加本批记录;`git log ..HEAD -- <本批路径>` 为空、`git status --porcelain` 非空;未 commit。 + SUMMARY 与两处账本追加完成,计数行未变、未提交可复查。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 用户确认 → 文件移动 | Task 0 未确认前不得迁移任何文件(D-13、AGENTS.md) | +| 迁移 → 正文内容 | 只允许路径/链接/导入与新增 `## 前置知识`,其余逐字保留 | +| 待审阅示例 → 审阅记录 | 示例 1–6 迁移后仍是待审阅,不得当作已审阅 | +| 文档树 → 导航/侧边栏 | 侧边栏与磁盘文件必须双向一致,否则出现死链或孤儿页 | +| 历史记录 → 计数口径 | 10-54 的 25 篇记录不得被静默改写;本计划只追加 | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-209 | Tampering | 未获确认即移动文档 | high | mitigate | Task 0 硬关卡;Task 1 前置条件要求「可以执行」;Task 2 前置条件复核 | +| T-10-210 | Tampering | 迁移时顺带改写正文 | high | mitigate | Task 2/3/4 剥离链接行/导入行/前置节后与 HEAD 逐字比对,并比对全部代码块内容,不等即失败 | +| T-10-211 | Tampering | 示例或新增页被当作已审阅 | high | mitigate | 示例 6 行固定 `待审阅`;`ui-basics` / `first-static-ui` 默认 `待审阅`;Task 1/4 断言映射与 `新增页面审阅状态` 一致;Task 5 明确不审示例正文 | +| T-10-212 | Tampering | 漏改内部链接导致读者跳错或 404 | high | mitigate | 映射表为唯一事实来源;旧链接 grep 清零;构建 0 dead link | +| T-10-213 | Denial of Service(构建不可用) | demo/RenderDemo 导入深度未改 | high | mitigate | 断言所有导入为 `../../.vitepress/components`;构建与 live 数量核对 | +| T-10-214 | Tampering | 侧边栏死链或孤儿页 | high | mitigate | 双向一致性脚本:侧边栏 27 条各落文件、磁盘 27 篇全在侧边栏 | +| T-10-215 | Repudiation | 27 基线或审阅谱系被静默改写 | high | mitigate | Task 0 固定 27、19 继承 + 2 新增 + 6 示例;INVENTORY 记录谱系与新增页状态;Task 4 断言映射行与清单一致 | +| T-10-216 | Tampering | 改到 ROADMAP 计数行或受保护行 | high | mitigate | Task 6 断言 `29/32`、三行未勾选、`10-42 增量说明` 仍在;`git diff` 无移除受保护行 | +| T-10-217 | Tampering | demo 被移动或修改 | medium | mitigate | 全程 `git status --porcelain -- docs/.vitepress/components/demos/ui` 为空;计数与引用数核对 | +| T-10-218 | Information Disclosure | 把审阅/迁移元叙述写进正文 | medium | mitigate | D-97 写入 Task 2/3/5;Task 2/4 扫描新指南正文无 `待审阅` / `未审阅` / `已修复` / `审阅记录` | +| T-10-219 | Tampering | 新增页被误标为已审阅 | high | mitigate | `ui-basics` / `first-static-ui` 默认 `待审阅`;Task 1/4 断言映射状态与清单 `新增页面审阅状态` 一致;Task 6 SUMMARY 写明 | +| T-10-220 | Tampering | 导览残留旧子分组/旧性能表述 | high | mitigate | Task 2 逐行改写 7 处;Task 4 断言两份导览不含 `自定义 UI 与渲染` 与 `高级 II 的《UI 性能》`,且数据端/III/中级链接仍在 | +| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 | + + + +- 关卡门禁:Task 0 已获「可以执行」;NOTES 含 `用户确认(10-55):可以执行`、`结构审阅:已完成`;用户未确认前无 SUMMARY / 记账改动。 +- D-112 门禁:`docs/render-guide/` 存在且分 `basics/`、`advanced/` 两区(不建 `internals/`);**只含画屏幕 / 写 UI 的 27 篇,系统文档未迁入、未新增**;`index.md` 说明两级与阅读路径;每篇有 `## 前置知识`;普通教程中与渲染相关的内容只在清单中盘点、未改写。 +- 迁移门禁:27 篇源路径不存在、目标存在;旧目录删除;docs 与 config 无 `/advanced/ii/ui/`、`./ui/` 链接;两份导览含 `render-guide` 链接且不含 `自定义 UI 与渲染` / `高级 II 的《UI 性能》`。 +- 链接门禁:46 处内部链接按分区重算;89 处导入前缀为 `../../.vitepress/`;锚点保留。 +- 导航门禁:`config.ts` nav 含 `渲染指南` 与 `/render-guide/`;侧边栏 27 条与磁盘 27 篇双向一致;高级 II 数据端 10 条、高级 III 分组、中级 25 条不变。 +- 内容门禁:剥离链接行/导入行/`## 前置知识` 段后,27 篇与 HEAD 逐字一致;27 篇全部代码块与 HEAD 逐字一致;示例 1–6 与 `ui-basics` / `first-static-ui` 按 Task 0 确认状态(默认待审阅)且正文未审阅;`10-54-SUMMARY.md` / `10-54-USER-REVIEW.md` 未改;新指南正文无审阅/迁移元叙述(D-97)。 +- 谱系门禁:INVENTORY 的 27 行映射与 `## 页面谱系与审阅状态` 一致;19 继承 + 2 新增(按 `新增页面审阅状态`)+ 6 示例;任何无谱系页面不得标为已审阅。 +- 计数门禁:页面基线固定 27;demo 文件/引用/live 计数与基线一致;10-54 的 25 篇 / 24 demo 只作历史记录保留,未被改写。 +- 构建门禁:prettier `--check` 通过;`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错(既有引擎报错只记录);`docs:build` green、0 dead link、HTML = 基线 + 1。 +- 记账门禁:ROADMAP 仅追加 10-55 条目与 `**10-55 增量说明:**`,`**Plans:** 29/32 completed` 与受保护四行不变;STATE 计数 134/126 不变;`git log ..HEAD` 对本批路径为空且 `git status` 非空;未 commit。 + + + +- 用户在 Task 0 确认路径/导航名/两分区/27 基线/审阅谱系后,27 篇完成迁移;旧路径与旧链接清零;导航与侧边栏双向可达。 +- 指南只含画屏幕 / 写 UI 的 27 篇 + index;数据端、存档与录像、插件系统、编辑器等系统仍留在中级/高级教程,未被迁入或新增。 +- 新指南导览页可独立阅读:两级定位、适合谁、阅读路径、27 条目录;每篇有基于真实依赖的 `## 前置知识`。 +- 正文与代码块未被改写;示例 1–6 与 `ui-basics` / `first-static-ui` 仍在指南内并按 Task 0 确认状态(默认待审阅);demo 未移动、未修改。 +- 全量门禁全绿(prettier / docs 路径类型 / 构建 0 dead link / 计数一致)。 +- 用户完成结构/链接审阅并明确确认;SUMMARY 与 ROADMAP/STATE 追加完成且计数行未变;本计划未 commit。 + + + +Create `.planning/phases/10-docs-restructure/10-55-SUMMARY.md` when done + diff --git a/.planning/phases/10-docs-restructure/10-55-SUMMARY.md b/.planning/phases/10-docs-restructure/10-55-SUMMARY.md new file mode 100644 index 0000000..422387b --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-55-SUMMARY.md @@ -0,0 +1,118 @@ +--- +phase: 10-docs-restructure +plan: 55 +subsystem: docs +tags: [docs, vitepress, render-guide, migration, bookkeeping] +requires: + - 10-54 +provides: + - "docs/render-guide/ 两级结构(basics 10 / advanced 17,不建 internals)" + - "27 篇画屏幕 / 写 UI 文档迁移与逐篇 ## 前置知识" +affects: + - docs/.vitepress/config.ts + - docs/advanced/ii/index.md + - docs/advanced/index.md +tech-stack: + added: [] + patterns: + - "两级文档指南:渲染基础 / 渲染进阶" +key-files: + created: + - docs/render-guide/index.md + - docs/render-guide/basics/*.md(10 篇) + - docs/render-guide/advanced/*.md(17 篇) + modified: + - docs/.vitepress/config.ts + - docs/advanced/ii/index.md + - docs/advanced/index.md + - .planning/phases/10-docs-restructure/10-55-INVENTORY.md + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - .planning/ROADMAP.md + - .planning/STATE.md +decisions: + - "指南只收画屏幕 / 写 UI 的 27 篇;数据端 / 存档 / 插件 / 编辑器等系统文档留在中级 / 高级教程" + - "两分区为 basics / advanced;UI 系统与 UI 性能归 advanced;不建 internals" + - "示例 1–6 与 ui-basics / first-static-ui 保持待审阅" +metrics: + duration: "N/A(Task 6 只做记账)" + completed: "2026-11-16" +status: complete +actuals: + tokens: 66088 + tasks: 5 + commits: 0 +--- + +# Phase 10 Plan 55: 渲染指南迁移 Summary + +按 D-112 把画屏幕 / 写 UI 的 27 篇自定义 UI 文档从高级 II 子分组独立为「渲染指南」,用两级结构组织并逐篇补基于真实依赖的前置知识,最后完成结构 / 链接审阅与记账。 + +## 问题 + +画屏幕与写 UI 的内容原先挤在高级 II 的「自定义 UI 与渲染」子分组里,既不方便按深度分层阅读,也让普通中级 / 高级教程承担了本应独立的界面原理讲解。D-112 要求把这类内容独立成指南,并按渲染基础 / 渲染进阶两层组织;与绘制屏幕关系不紧密的系统仍留在普通教程。 + +## 方案 + +新建 `docs/render-guide/`,只收画屏幕 / 写 UI 的 27 篇 UI 文档: + +- `basics/`(渲染基础)10 篇; +- `advanced/`(渲染进阶)17 篇,其中 UI 系统(`ui-system`)与 UI 性能(`ui-performance`)归入 advanced; +- 不创建 `internals/`,不设渲染底层。 + +同时新增指南导览页 `docs/render-guide/index.md`,迁移全部内部链接、demo 导入、顶部导航、侧边栏与两份导览,并给 27 篇逐篇补 `## 前置知识`。系统文档(数据端、存档与录像、插件系统、编辑器等)不迁入、不新增。 + +## 迁移结果 + +- 页面:27 篇全部迁入,`docs/render-guide/` 共 28 个 `.md`(27 篇 + `index.md`);旧目录 `docs/advanced/ii/ui/` 已删除。 +- 分区计数:basics 10 / advanced 17 / internals 0(有效分区 2)。 +- 链接:46 处文内相对链接按新分区重算(同区保留 `./`,跨区改 `../<分区>/`),锚点原样保留。 +- 导入:89 处(demo 65 + `renderDemo.vue` 24)前缀由 `../../../.vitepress` 改为 `../../.vitepress`;demo 未移动、未改名、未修改。 +- 导航:`config.ts` 新增顶部导航「渲染指南」与 `/render-guide/` 侧边栏两组(渲染基础 10 条 / 渲染进阶 17 条);旧「自定义 UI 与渲染」分组移除;高级 II 数据端、高级 III 与中级条目保留。 +- 导览:`docs/advanced/ii/index.md` 与 `docs/advanced/index.md` 的旧子分组 / 旧性能表述改为指向渲染指南,其余内容保留。 + +## 前置知识 + +27 篇各有且仅有一个 `## 前置知识`。依据来自真实依赖:原阅读顺序 / 起步顺序、正文实际引用、现有交叉链接;每条依据都记在 `10-55-INVENTORY.md` 的 `## 前置知识依据`。`ui-system` 的前置只保留「事件与交互」,不以前置 `custom-components` 为前提。导览页「页面目录」的前置列与正文一致。 + +## 门禁与验证 + +- 结构:`docs/render-guide/` 仅 `basics/`、`advanced/` 两个目录,共 28 个 `.md`;无 `internals/`、无系统文档;旧目录与旧链接清零。通过。 +- 导航:侧边栏 27 条与磁盘 27 篇双向一致,无死链、无孤儿页。通过。 +- 导入与 live:全部导入为 `../../.vitepress/...`;demo 文件 67、被正文引用 65、带 live 24,与基线一致;demo 目录无改动。通过。 +- 文档结构:27 篇前置节各一;示例 1–6 与 `ui-basics` / `first-static-ui` 保持待审阅;`10-54-SUMMARY.md`、`10-54-USER-REVIEW.md`、`docs/poc/render-demo.md` 未改;剥离前置节 / 链接行 / 导入行后正文与 HEAD 逐字一致。通过。 +- 格式:prettier `--check` 通过。通过。 +- 构建:`pnpm docs:build` green、0 dead link、HTML = 27 + 1。通过。 +- 类型:`docs/` 路径存在 1 条既有报错(未在本计划修改的 demo 文件 + 工作树中无关包改动所致),已记入 `10-55-DEFERRED-ITEMS.md`,未修改、未绕过;本计划未引入该报错。其余报错位于 `packages/` 与 `packages-user/`,不属于本计划范围。 +- 收尾验证:Task 6 验证脚本输出 `CLOSEOUT-OK`,通过。 + +## 用户结构审阅 + +Task 5 结构 / 链接审阅已由用户确认通过,用户原话「可以收尾」。本轮无新增改动项;`10-55-USER-REVIEW.md` 未单独落盘,本轮也未新增审阅轮次记录。示例 1–6 正文不在审阅范围内。 + +## 计数口径与审阅谱系 + +- 页面基线固定为 27;10-54 记录的 25 篇 / 24 demo 只是历史记录值,不采用、未改写。 +- 审阅谱系:19 篇继承 10-54 的已审阅状态(含改名继承)+ 6 篇示例待审阅 + 2 篇新增待审阅 = 27。 +- 新增页面审阅状态:`ui-basics` = 待审阅;`first-static-ui` = 待审阅。依据:10-54 的 25 篇清单无对应 slug,用户未确认其已审阅,按默认保持待审阅。 +- 示例 1–6 全部保持待审阅,本轮未审阅、未改写。 + +## 未做事项 + +- 未重写任何文档正文、代码块或 demo; +- 未移动、改名或修改 demo; +- 未审阅示例 1–6 的正文; +- 未做普通教程中渲染相关内容的收敛改写(本计划只盘点,另开计划); +- 未改 `packages/`、`packages-user/`、`src/`、POC 页与配置以外的文件; +- 未 commit、未 push。 + +## D-112 后续项 + +- 普通中级 / 高级教程只讲主要逻辑的收敛改写仍待另开计划;盘点清单见 `10-55-INVENTORY.md` 的 `## 普通教程渲染端内容盘点(只盘点、不改写)`。 +- `docs/poc/render-demo.md` 按 Task 0 裁决保留不动;正式指南落地后的处置仍由用户决定。 +- 示例 1–6 与 `ui-basics` / `first-static-ui` 的正文审阅仍待后续计划。 + +## 未提交与 HEAD + +CURRENT-HEAD: 2a4b3220ed9ecc01b2f92eabd375185eb686a01a +PLAN-FILES-COMMITTED: none +BASE-HEAD: 2a4b3220ed9ecc01b2f92eabd375185eb686a01a \ No newline at end of file diff --git a/.planning/phases/10-docs-restructure/10-CONTEXT.md b/.planning/phases/10-docs-restructure/10-CONTEXT.md index fc1b90d..c104a69 100644 --- a/.planning/phases/10-docs-restructure/10-CONTEXT.md +++ b/.planning/phases/10-docs-restructure/10-CONTEXT.md @@ -277,7 +277,7 @@ - **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-112(渲染指南的后续重构):** 自定义 UI / 画面绘制文档内容多且集中,不拆到不同阶段。当前审阅结束后另开计划:新增“渲染指南”专页,内部分为渲染基础、渲染进阶、渲染底层,按不同深度组织。**渲染指南只收“怎么画画面、怎么写 UI”的内容;与渲染关系不大的系统不迁入,仍留在中级/高级教程中。** 普通中/高级教程仍穿插画面/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 的读者全量阅读要求并列,适用于所有文档修改子代理,**不得以时间、并行、上下文限制或任务简单为由跳过**。 diff --git a/.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md b/.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md index 54260a0..b053f24 100644 --- a/.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +++ b/.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md @@ -4,62 +4,62 @@ ## 命名总表 -| 项 | 最终值 | -|----|--------| -| 子分组名 | 自定义 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 收尾 | +| 项 | 最终值 | +| ------------ | ----------------------------------------------------------------------- | +| 子分组名 | 自定义 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 建 | +| 序 | 文件名 | 侧边栏显示名 | 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` | +| 文件 | 组件名 | +| -------------------- | --------------- | +| `template-demo.tsx` | `TemplateDemo` | | `container-demo.tsx` | `ContainerDemo` | -| `shapes-demo.tsx` | `ShapesDemo` | -| `curves-demo.tsx` | `CurvesDemo` | -| `text-demo.tsx` | `TextDemo` | +| `shapes-demo.tsx` | `ShapesDemo` | +| `curves-demo.tsx` | `CurvesDemo` | +| `text-demo.tsx` | `TextDemo` | 用户确认(10-43):可以执行 用户原文:可以执行(批准执行 10-43..10-47;10-48 读者/用户审阅前停下) @@ -69,43 +69,43 @@ 哈希为 `git hash-object -- ` 实测值;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 哈希(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 -- ` 非空(`docs/.vitepress/config.ts`、`docs/tsconfig.json`、两份导览本计划自己要改,除外),立即停下向用户报告,不得按旧内容继续写作。 @@ -113,20 +113,20 @@ `git hash-object -- ` 实测结果: -| 路径 | 实测 | 与 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 | `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 基线一致,工作树对本批参考路径无改动,可按现有内容写作。 @@ -154,14 +154,14 @@ #### 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 | +| 门禁 | 命令 | 结论 | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | +| 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 条(既有、非本轮引入、不得修)。 @@ -169,25 +169,25 @@ docs/ 路径类型报错 0;既有引擎报错 11 条(既有、非本轮引 #### 本批清单(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` | +| 页面 | 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 | +| 门禁 | 命令 | 结论 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 条(与本轮无关,保持不动)。 @@ -197,14 +197,14 @@ docs/ 路径类型报错 0;既有引擎报错 11 条(与本轮无关,保 #### 本批清单(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` | +| 页面 | 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` | ## 人工验证记录 @@ -240,32 +240,32 @@ live 人工验证(10-44):待最终人工审阅。本轮未写「用户人 `git hash-object -- ` 实测结果: -| 路径 | 实测 | 与 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 新建 | 未列入基线 | 未跟踪 | +| 路径 | 实测 | 与 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 | +| 门禁 | 命令 | 结论 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 条(与本轮无关,保持不动)。 @@ -275,12 +275,12 @@ live 人工验证(10-44):待最终人工审阅。本轮未写「用户人 #### 本批清单(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 | 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 关卡标记为完成。 @@ -302,37 +302,37 @@ live 人工验证(10-45):待最终人工审阅。本轮未写「用户人 `git hash-object -- ` 实测结果: -| 路径 | 实测 | 与 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 | `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 | +| 门禁 | 命令 | 结论 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 条(与本轮无关,保持不动)。 @@ -342,13 +342,13 @@ live 人工验证(10-45):待最终人工审阅。本轮未写「用户人 #### 本批清单(5 篇 + 5 个 demo) -| 页面 | live | demo | -|------|------|------| -| `docs/advanced/ii/ui/builtin-text-and-input.md` | 是(等价元素演示) | `docs/.vitepress/components/demos/ui/builtin-text-demo.tsx` | +| 页面 | 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` | +| `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) @@ -377,31 +377,31 @@ live 人工验证(10-46):待最终人工审阅。本轮未写「用户人 `git hash-object -- ` 实测结果: -| 路径 | 实测 | 与 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 | `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 | +| 门禁 | 命令 | 结论 | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 条(与本轮无关,保持不动)。 @@ -409,14 +409,14 @@ live 人工验证(10-46):待最终人工审阅。本轮未写「用户人 #### 本批清单(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` | +| 页面 | 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` | ### 全批交叉核对 @@ -447,6 +447,7 @@ live 人工验证(10-47):待最终人工审阅。本轮未写「用户人 - `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):可以执行 @@ -478,15 +479,16 @@ 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: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 一致。 +- 元素层实际 API 没有 loc() 方法(loc 只是 TSX 属性,对应 pos() + size());六处内联 s 片段统一用 pos() / size(),与 packages/render 一致。 ## 10-49 独立读者审阅 @@ -542,15 +544,15 @@ STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133 ### 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 | +| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 | +| -------------------------------------------------- | ---------- | -------- | ------------- | ---------- | -------- | +| 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。 @@ -582,14 +584,14 @@ STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133 - 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。 + 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) @@ -608,15 +610,15 @@ STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133 ### 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 | +| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 | +| ----------------------------------------------------- | ---------- | -------- | ------------- | ---------- | -------- | +| 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。 @@ -648,20 +650,21 @@ STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133 - 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,不走普通冒泡。 + 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-50 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-51..10-54;未 commit。 ## 10-51 深度扩写(Part 4) @@ -680,13 +683,13 @@ STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133 ### 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 | +| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 | +| -------------------------------------------------- | ---------- | -------- | ------------- | ---------- | -------- | +| 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。 @@ -714,11 +717,11 @@ STATE 全文哈希:e4731f2b66115eb43d9b185634c2d86802ef6c2638201558c98d917e133 - 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 — 通过 + 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 执行偏差 @@ -726,7 +729,7 @@ D-93 抽查:docs/advanced/ii/ui/ui-performance.md — 通过 - 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-51 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-52..10-54;未 commit。 ## 10-52 深度扩写(Part 5) @@ -746,14 +749,14 @@ demo 快照哈希:02b1d6a88d414c9ce197b7bd8f7773020d8ae1c5c18099518595a66ca1ad ### 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 | +| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 | +| ----------------------------------------------------------------- | ---------- | -------- | ------------- | ---------- | -------- | +| 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`;子组件收到的是父级解包后的数组或明确 props,不在子组件里直接引用父级闭包变量;派生列表用 `computed`。 @@ -811,8 +814,8 @@ D-93 抽查:docs/advanced/ii/ui/inventory-example-6-animation-and-register.md - 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 只做 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 执行偏差 @@ -962,8 +965,63 @@ Round 3(D-94)修订:阻断 7 条,已修 6 条(落在 6 处正文), 用户确认(10-54):已完成(非示例) 用户原文(2026-11-15):「这部分文档算是差不多全看完了。示例部分先保留,标记为待审阅,先不审阅它。你把文档审阅计划标记为已完成,把当前计划收尾。」 -审阅范围:25 篇 docs/advanced/ii/ui/*.md;其中 19 篇非示例文档已审阅完成,6 篇示例文档保留现状并标记为待审阅。 +审阅范围: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。 \ No newline at end of file +停止点:10-54 文档审阅收尾;示例 1-6 待审阅;未改源码/demo;未 commit。 + +## 10-55 渲染指南迁移 + +用户确认(10-55):可以执行 +用户原文(摘要,2026-11-16):用户确认修正后的计划 10-55-PLAN.md(名称 / 范围更正:指南为「渲染指南」,不是「渲染端指南」;只收画屏幕 / 写 UI 的材料,无关系统留在中级 / 高级教程),并批准执行 Task 1–4;Task 5 用户审阅与 Task 6 记账不在本次执行范围。 +裁决摘要:路径 docs/render-guide/;导航名「渲染指南」;三分区 asics/、dvanced/、internals/(渲染基础 / 渲染进阶 / 渲染底层);页面基线 27(basics 10 / advanced 15 / internals 2);19 篇继承 10-54 已审阅、ui-basics / irst-static-ui 待审阅、示例 1–6 待审阅;demo 不移动;普通教程渲染相关内容收敛另开计划;POC 页保留不动;不 commit。 +BASE-HEAD:2a4b3220ed9ecc01b2f92eabd375185eb686a01a +页面基线:27;实测 27(docs/advanced/ii/ui/\*.md 计数)。10-54 记录值 25 篇(19 已审阅 + 6 待审阅)/ 24 demo 只作历史记录。 +新增页审阅状态与依据:ui-basics = 待审阅; irst-static-ui = 待审阅。依据:两篇在 10-54 的 25 篇清单中无对应 slug(5db2cef 后新增),用户未确认其已审阅,按默认记待审阅。 +POC 处置:保留不动(docs/poc/render-demo.md 本计划不改)。 +demo 基线:文件 67;被正文引用 65;带 live(renderDemo.vue) 24。demo 目录:docs/.vitepress/components/demos/ui/。 +docs 快照哈希:363b822c90b84761eff38b4ca518837eae609d0a1c6d8f1b7d5f62f38cb6c853(27 篇,按相对路径排序,逐文件 SHA-256 后以 LF 拼 path:hash 再取 SHA-256) +配置快照哈希:212dc5960e3a9ff5d04b0f08e9616cf0dfae268856e92a8654022930ef6bcbbe(docs/.vitepress/config.ts) +迁移范围:docs/advanced/ii/ui/ → docs/render-guide/{basics,advanced,internals}/ +示例口径:1..6 保持待审阅,不审阅正文 +停止点:10-55 迁移前清单已建立 + +### 10-55 门禁 + +执行时间:2026-11-16(本地时间 13:51 起)。 +结构门禁:docs/render-guide/ 共 28 个 .md(27 篇 + index.md),目录仅 asics / dvanced / internals;docs/advanced/ii/ui/ 已删除;docs 与 docs/.vitepress/_.ts 中 /advanced/ii/ui/、./ui/ 链接为 0;docs/advanced/ii/index.md 与 docs/advanced/index.md 含 +ender-guide 链接且不含「自定义 UI 与渲染」「高级 II 的《UI 性能》」,数据端与 III 链接保留。结果:通过。 +导航门禁:nav 含「渲染指南」与 /render-guide/;/render-guide/ 侧边栏 27 条与磁盘 27 篇双向一致(无死链、无孤儿页);旧 UI 分组已移除;/intermediate/ 链接 26 条(25 侧边栏 + 1 顶部)不变。结果:通过。 +导入与 live 门禁:docs/render-guide/\*\*/_.md 中 .vitepress/components 导入全部为 ../../.vitepress/...,../../../.vitepress/components 为 0;demo 目录 git status --porcelain 为空;demo 文件 67、被正文引用 65、带 +enderDemo.vue 24,与基线一致。结果:通过。 +文档结构门禁:27 篇各有且仅有一个 ## 前置知识;示例 6 篇在清单中仍为 待审阅;ui-basics / irst-static-ui 与清单 新增页面审阅状态(均 待审阅)一致;10-54-SUMMARY.md、10-54-USER-REVIEW.md、docs/poc/render-demo.md 未被修改;剥离 ## 前置知识 段、链接行与导入行后 27 篇与 HEAD 逐字一致;全部代码块与 HEAD 逐字一致;新指南正文无 待审阅 / 未审阅 / 已修复 / 审阅记录。结果:通过。 +格式门禁:cmd /c "pnpm exec prettier --check docs/render-guide docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md" 首次对 docs/render-guide/index.md 报格式差异,--write 后复跑 exit 0,差异仅为表格/空行排布。结果:通过。 +类型门禁:cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" exit 2;docs/ 路径报错 1 条:docs/.vitepress/components/demos/ui/container-custom-demo.tsx(17,41): error TS2554;其余 218 条全部位于 packages/ / packages-user/(工作树中存在与本计划无关的未提交改动,如 packages-user/client-base/src/map/element.ts 的 +enderContent 签名改为 1 个参数,10-54 基线 11 条不再适用)。该 docs 报错来自未被本计划修改的 demo 文件与未提交的包改动,不是 10-55 引入;按要求不修改 demo 与 packages/,已记入 10-55-DEFERRED-ITEMS.md。docs 路径断言未达 0。结果:未通过(预存在、非本计划引入,待用户裁决)。 +构建门禁:cmd /c "pnpm exec tsx docs/.vitepress/init.ts" exit 0;cmd /c "pnpm docs:build" exit 0,输出 uild complete in 19.28s,无 dead link;public/\_docs/render-guide/\*_/_.html 共 28 个(basics 10 / advanced 15 / internals 2 + index),等于页面基线 + 1。结果:通过。 +计数:页面 27;导入 89(demo 65 + RenderDemo 24);demo 67/65/24;内部链接 46(跨区改写 25,同区保留 21);侧边栏 27。示例待审阅结论:1–6 全部仍为待审阅,正文未审阅、未改写。旧链接清零结论:/advanced/ii/ui/ 与 ./ui/ 在 docs 与配置中均为 0。 +docs 迁移后快照哈希:6c1130ec8596af25316405b4597f5a815008adee436b5715e6a85c0ceaee8185(27 篇,按相对路径排序,逐文件 SHA-256 后以 LF 拼 path:hash 再取 SHA-256) +迁移后配置快照哈希:cdb9d2562b517ddbed4f8614496e941aad0ca8b51f77c269e5bce171125adc2b +迁移后指南导览哈希:65e9466ba8447eef4dbab7fe0d9936cc8dc7c812bda8477406e458895f202209 +停止点:10-55 Task 4 门禁已跑;未进入 Task 5 用户审阅;未写 SUMMARY、未改 ROADMAP / STATE、未 commit。 + +### 10-55 用户结构修正(2026-11-16) + +用户要求:渲染指南改为两分区,不保留底层文档;`ui-system` 与 `ui-performance` 两篇移入 `advanced/`;`ui-system` 不再以 `custom-components` 为前置。已执行:用 `git mv` 将两篇移到 `docs/render-guide/advanced/` 并删除空的 `internals/`;侧边栏移除「渲染底层」组,两篇并入「渲染进阶」;导览、迁移清单与相关链接同步改为 advanced。分区计数:basics 10 / advanced 17 / internals 0(有效分区 2)。`ui-system.md` 的「前置知识」仅保留「事件与交互」。 + +### 10-55 收尾(2026-11-16) + +用户确认(10-55):可以执行(Task 5 结构 / 链接审阅通过,用户可以收尾) +用户原文:「可以收尾」(2026-11-16,确认 Task 5 审阅后指示执行 Task 6 收尾记账) +结构审阅:已完成 +最终页面计数:27(`docs/render-guide/` 共 28 个 `.md`,含 `index.md`);两区计数:basics 10 / advanced 17;internals 0(不建目录,UI 系统与 UI 性能归 advanced)。 +新增页审阅状态与依据:`ui-basics` = 待审阅;`first-static-ui` = 待审阅。依据:10-54 的 25 篇清单无对应 slug,用户未确认其已审阅,按默认保持待审阅。 +审阅谱系:19 篇继承 10-54 已审阅(含改名继承)+ 2 篇新增待审阅 + 6 篇示例待审阅 = 27。 +POC 处置:保留不动(`docs/poc/render-demo.md` 未改)。 +demo:文件 67;被正文引用 65;带 live(`renderDemo.vue`) 24;目录 `docs/.vitepress/components/demos/ui/` 未移动、未修改。 +迁移后 docs 快照哈希:754b6b15d9aae205ec74ad955c9e683a4b25ab5eb2921f041fb20cecf31f2894(27 篇,按相对路径排序,逐文件 SHA-256 后以 LF 拼 `path:hash` 再取 SHA-256;两分区修正后实测)。 +迁移后配置快照哈希:a498e4e371a12b9617943db7813a5b7dfd82e3e857d6294e9d0b002b6e88e1c3。 +门禁摘要:结构 / 导航 / 导入与 live / 文档结构 / 格式 / 构建通过;类型门禁 `docs/` 路径 1 条为未在本计划修改的 demo 与工作树无关包改动所致,已记 `10-55-DEFERRED-ITEMS.md`,未修、未绕过。 +示例待审阅结论:示例 1–6 全部仍为 待审阅,正文未审阅、未改写。 +停止点:10-55 渲染指南迁移完成 diff --git a/docs/.vitepress/components/demos/ui/container-custom-demo.tsx b/docs/.vitepress/components/demos/ui/container-custom-demo.tsx index 3f8c138..730911c 100644 --- a/docs/.vitepress/components/demos/ui/container-custom-demo.tsx +++ b/docs/.vitepress/components/demos/ui/container-custom-demo.tsx @@ -14,7 +14,7 @@ export default defineComponent(() => { children.forEach((child, index) => { if (child.hidden) return; child.setFilter(`blur(${index * 2}px)`); - child.renderContent(canvas, transform); + child.renderContent(canvas); }); }; diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 3b0f7f6..31e9b1a 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -43,7 +43,8 @@ export default defineConfig({ outline: [2, 3], nav: [ { text: '中级教程', link: '/intermediate/data-vs-render' }, - { text: '高级教程', link: '/advanced/' } + { text: '高级教程', link: '/advanced/' }, + { text: '渲染指南', link: '/render-guide/' } ], sidebar: { '/intermediate/': [ @@ -253,162 +254,6 @@ 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' - } - ] - } - ] } ] }, @@ -443,6 +288,128 @@ export default defineConfig({ } ] } + ], + '/render-guide/': [ + { + text: '渲染基础', + collapsed: false, + items: [ + { + text: 'UI 通用模板(TSX)', + link: '/render-guide/basics/ui-template' + }, + { + text: 'UI 入门', + link: '/render-guide/basics/ui-basics' + }, + { + text: '第一个静态界面', + link: '/render-guide/basics/first-static-ui' + }, + { + text: '容器与坐标', + link: '/render-guide/basics/container-and-coordinates' + }, + { + text: '基础图形', + link: '/render-guide/basics/basic-shapes' + }, + { + text: '文字', + link: '/render-guide/basics/text' + }, + { + text: '图片与纹理', + link: '/render-guide/basics/image-and-texture' + }, + { + text: '自绘元素与自定义容器', + link: '/render-guide/basics/custom-and-container-custom' + }, + { + text: '通用参数', + link: '/render-guide/basics/common-props' + }, + { + text: '层级、变换与性能', + link: '/render-guide/basics/layer-transform-performance' + } + ] + }, + { + text: '渲染进阶', + collapsed: false, + items: [ + { + text: '响应式', + link: '/render-guide/advanced/reactivity' + }, + { + text: '事件与交互', + link: '/render-guide/advanced/events' + }, + { + text: '条件渲染与循环渲染', + link: '/render-guide/advanced/conditional-and-list-rendering' + }, + { + text: '按键与快捷键', + link: '/render-guide/advanced/hotkey-in-ui' + }, + { + text: '什么是组件', + link: '/render-guide/advanced/what-is-component' + }, + { + text: '内置组件:基础', + link: '/render-guide/advanced/builtin-basic' + }, + { + text: '内置组件:布局', + link: '/render-guide/advanced/builtin-layout' + }, + { + text: '内置组件:文本', + link: '/render-guide/advanced/builtin-text' + }, + { + text: '自定义组件', + link: '/render-guide/advanced/custom-components' + }, + { + text: 'UI 系统', + link: '/render-guide/advanced/ui-system' + }, + { + text: 'UI 性能', + link: '/render-guide/advanced/ui-performance' + }, + { + text: '示例(一)目标与骨架', + link: '/render-guide/advanced/inventory-example-1-skeleton' + }, + { + text: '示例(二)道具网格', + link: '/render-guide/advanced/inventory-example-2-grid' + }, + { + text: '示例(三)详情区', + link: '/render-guide/advanced/inventory-example-3-detail' + }, + { + text: '示例(四)滚动与列表', + link: '/render-guide/advanced/inventory-example-4-scroll' + }, + { + text: '示例(五)交互与状态', + link: '/render-guide/advanced/inventory-example-5-state' + }, + { + text: '示例(六)动画、拆分与注册', + link: '/render-guide/advanced/inventory-example-6-animation-and-register' + } + ] + } ] }, socialLinks: [ diff --git a/docs/advanced/ii/index.md b/docs/advanced/ii/index.md index 63613b9..0bf6794 100644 --- a/docs/advanced/ii/index.md +++ b/docs/advanced/ii/index.md @@ -12,7 +12,7 @@ - 认真阅读样板后,能把一部分简单系统和中等复杂度的系统读明白; - 想把某个具体系统改成自己的规则,而不只是调用现成接口。 -这一层不预设你是资深引擎开发者,也不要求通读引擎源码。它要求的是能跟着样板找到改动点,并判断改动会不会影响存档与录像。这一层的主体是数据端;另有自定义 UI 与渲染子分组(见侧边栏),面向要在画布上写界面的作者。 +这一层不预设你是资深引擎开发者,也不要求通读引擎源码。它要求的是能跟着样板找到改动点,并判断改动会不会影响存档与录像。这一层的主体是数据端;要在画布上写界面的作者见[渲染指南](../../render-guide/)。 ## 难度层定位 @@ -49,9 +49,9 @@ ## 本层包含什么 -本层一共十篇(这一页导览 + 九篇数据端正文),另有「自定义 UI 与渲染」子分组 27 篇(见侧边栏)。 +本层一共十篇(这一页导览 + 九篇数据端正文);画屏幕 / 写 UI 的内容已独立为[渲染指南](../../render-guide/)。 -「自定义 UI 与渲染」子分组的入口从 [UI 通用模板](./ui/ui-template.md) 开始;先看 [UI 入门](./ui/ui-basics.md) 了解打开方式、TSX 写法与渲染树,再看 [第一个静态界面](./ui/first-static-ui.md) 把容器、文字、图片与图形拼成一块面板,之后回到模板动手写。Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端;上文的数据端前置只对数据端篇目成立。 +渲染端的阅读入口与三级路径见[渲染指南](../../render-guide/);本层不再重复。 | 序 | 篇目 | 它能让你做什么 | 前置 | | --- | ----------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------- | @@ -78,8 +78,8 @@ ## 本层不覆盖什么 -- **编辑器与状态栏**:编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内,相关篇目只用占位说明归属;界面绘制与 UI 系统见子分组「自定义 UI 与渲染」。 -- **引擎级性能**:高级 II 的《UI 性能》讲缓存与显示策略的取舍,引擎级性能仍属高级 III。 +- **编辑器与状态栏**:编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内,相关篇目只用占位说明归属;界面绘制与 UI 系统见[渲染指南](../../render-guide/)。 +- **引擎级性能**:[《UI 性能》](../../render-guide/advanced/ui-performance)在渲染指南中讲缓存与显示策略的取舍,引擎级性能仍属高级 III。 - **高级 III 的原理与架构**:双端分离约束、数据端分层、编辑器识别协议、录像深层原理与性能调优留给高级 III。 - **API 全量参考**:本层只讲改动链路与关键接口,不做签名清单。 diff --git a/docs/advanced/index.md b/docs/advanced/index.md index f6a8b2b..7c8a8b5 100644 --- a/docs/advanced/index.md +++ b/docs/advanced/index.md @@ -35,8 +35,8 @@ ## 边界与注意 -- 渲染端内容:高级 II 已收录「自定义 UI 与渲染」子分组,本层其它篇目仍以数据端为主;编辑器与内容配置部分只用占位标记指出归属。 -- 性能边界:高级 II 的《UI 性能》讲缓存与显示策略的取舍,引擎级性能仍属高级 III。 +- 渲染端内容:画屏幕 / 写 UI 的内容已独立为[渲染指南](../render-guide/);本层其它篇目仍以数据端为主;编辑器与内容配置部分只用占位标记指出归属。 +- 性能边界:渲染指南的[《UI 性能》](../render-guide/advanced/ui-performance)讲缓存与显示策略的取舍,引擎级性能仍属高级 III。 - 编辑器内容:涉及编辑器与内容配置的部分只保留占位,不在本层展开。 - 不重复中级已讲内容:接口的日常用法、参数清单与常见改法属于中级教程;本层只在需要说明扩展点时引用,不整段重写。 - 高级 III 入口:该层已可阅读,入口见[高级 III 导览](./iii/)。 diff --git a/docs/advanced/ii/ui/builtin-basic.md b/docs/render-guide/advanced/builtin-basic.md similarity index 95% rename from docs/advanced/ii/ui/builtin-basic.md rename to docs/render-guide/advanced/builtin-basic.md index 606f978..7a38fb1 100644 --- a/docs/advanced/ii/ui/builtin-basic.md +++ b/docs/render-guide/advanced/builtin-basic.md @@ -2,6 +2,12 @@ `@user/client-base` 里已经有一批常用的基础组件。它们和普通组件一样,在 TSX 里按名字使用,属性名写成 camelCase。下面每个组件都先说它解决什么问题,再给最小写法,常用参数跟着讲,最后接一个 live。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [什么是组件](./what-is-component.md) + ## Input 要接收用户文字输入,用 `Input`。 @@ -377,20 +383,20 @@ const increase = () => (volume.value = Math.min(100, volume.value + 5)); 拖动滑动条或点两侧按钮,右侧数值会跟着变。 diff --git a/docs/advanced/ii/ui/builtin-layout.md b/docs/render-guide/advanced/builtin-layout.md similarity index 95% rename from docs/advanced/ii/ui/builtin-layout.md rename to docs/render-guide/advanced/builtin-layout.md index 3f6f0f7..e95ccb8 100644 --- a/docs/advanced/ii/ui/builtin-layout.md +++ b/docs/render-guide/advanced/builtin-layout.md @@ -2,6 +2,13 @@ 这一篇讲四个负责区域与列表的组件:`Scroll`、`Page`、`List`、`ListPage`。它们都先说要解决什么,再给最小写法,常用参数跟着讲,最后接一个 live。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [什么是组件](./what-is-component.md) +- [内置组件:基础](./builtin-basic.md) + ## Scroll 内容超过视口时,用 `Scroll` 给一块区域加滚动。 @@ -280,14 +287,14 @@ const selected = ref(items[0][0]); 左侧是三项列表,选中项高亮,右侧显示对应说明。 diff --git a/docs/advanced/ii/ui/builtin-text.md b/docs/render-guide/advanced/builtin-text.md similarity index 95% rename from docs/advanced/ii/ui/builtin-text.md rename to docs/render-guide/advanced/builtin-text.md index 4a4ea30..1286a6c 100644 --- a/docs/advanced/ii/ui/builtin-text.md +++ b/docs/render-guide/advanced/builtin-text.md @@ -2,6 +2,13 @@ 文字元素只画一行。要让长文字按宽度折行、逐字显示或自动向上滚动时,用内置的文本组件。这一篇讲 `TextContent` 和 `ScrollText`,每个都先说它解决什么问题,再给最小写法,最后接一个 live。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [什么是组件](./what-is-component.md) +- [内置组件:基础](./builtin-basic.md) + ## TextContent 要让长文字按宽度自动折行,用 `TextContent`。 @@ -207,10 +214,10 @@ const notice = '这是一条会自己向上滚动的公告。'.repeat(8); 公告在固定视口里持续向上滚动。 diff --git a/docs/advanced/ii/ui/conditional-and-list-rendering.md b/docs/render-guide/advanced/conditional-and-list-rendering.md similarity index 96% rename from docs/advanced/ii/ui/conditional-and-list-rendering.md rename to docs/render-guide/advanced/conditional-and-list-rendering.md index c2aef61..441dfd3 100644 --- a/docs/advanced/ii/ui/conditional-and-list-rendering.md +++ b/docs/render-guide/advanced/conditional-and-list-rendering.md @@ -4,6 +4,13 @@ TSX 里没有模板指令。要不要显示一块内容、要不要重复一组 绝大多数情况用 `hidden` 更划算:它只跳过绘制与命中,元素、状态和事件监听都还在。虽然会多占一点内存,但一般影响很小;TSX 也更平整,不需要为条件分支多套一层缩进。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [响应式](./reactivity.md) +- [事件与交互](./events.md) + ## 条件渲染与 hidden 大多数情况推荐 `hidden`,不推荐三元:它只多占一点内存,一般影响很小,TSX 也更平整。 @@ -333,14 +340,14 @@ export const MyPanelUI = new GameUI('my-panel', MyPanel); | 会增删、重排、带状态的列表 | `.map()` + `key` | 保留元素身份,状态跟着正确的项走 | ## 边界与注意 diff --git a/docs/advanced/ii/ui/custom-components.md b/docs/render-guide/advanced/custom-components.md similarity index 97% rename from docs/advanced/ii/ui/custom-components.md rename to docs/render-guide/advanced/custom-components.md index c131a10..9f26290 100644 --- a/docs/advanced/ii/ui/custom-components.md +++ b/docs/render-guide/advanced/custom-components.md @@ -4,6 +4,13 @@ 这一篇只讲怎么用:怎么接收参数、怎么发事件、怎么留出内容位置,以及怎么把属性透传给内部元素。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [什么是组件](./what-is-component.md) +- [内置组件:基础](./builtin-basic.md) + ## props 组件的外部参数叫 props。父组件把值写在组件标签的属性上,子组件通过 `props.x` 读取。声明分三步: @@ -302,8 +309,8 @@ export const MyPanelUI = new GameUI('my-panel', MyPanel); diff --git a/docs/advanced/ii/ui/events.md b/docs/render-guide/advanced/events.md similarity index 96% rename from docs/advanced/ii/ui/events.md rename to docs/render-guide/advanced/events.md index d73a854..80052cf 100644 --- a/docs/advanced/ii/ui/events.md +++ b/docs/render-guide/advanced/events.md @@ -4,6 +4,13 @@ 一般更符合直觉的是冒泡。点一个按钮,应该先轮到按钮自己处理,而不是父容器先把事件接住;所以 `onClick`、`onDown` 这些默认事件都走冒泡。只有确实需要外层先处理时,才用 `onClickCapture`、`onDownCapture` 这类捕获写法。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [容器与坐标](../basics/container-and-coordinates.md) +- [响应式](./reactivity.md) + ## 内置事件及用法 TSX 里用 `onXxx` 绑定事件。常用事件如下: @@ -321,7 +328,7 @@ live 只显示本次点击触发的事件;打开 stop 后,按钮的冒泡会 - `hidden` 的元素不绘制,也不参与命中,事件会直接落到它后面的元素。 - `noevent` 的元素照常绘制,但跳过命中。它不是只跳过自身,而是**整个子树都不参与命中**:容器加了 `noevent`,里面的子元素也收不到事件,事件会下穿到兄弟或下层元素;`cursor` 也同时失效。 - `cursor` 写在元素上,指针悬停时生效,取值与浏览器的鼠标样式一致,例如 `pointer`、`text`、`default`。多个元素同时命中时,最内层写了 `cursor` 的元素生效;元素被 `noevent` 跳过或 `hidden` 隐藏时,`cursor` 不再生效。 -- `actionStroke` 只把描边算作命中,内部空白区域会下穿。它适合「只有边框看起来可点」的界面;命中宽度跟着 `lineWidth` 走,没有额外的最小热区。基础图形的命中细节见[基础图形](./basic-shapes.md)。 +- `actionStroke` 只把描边算作命中,内部空白区域会下穿。它适合「只有边框看起来可点」的界面;命中宽度跟着 `lineWidth` 走,没有额外的最小热区。基础图形的命中细节见[基础图形](../basics/basic-shapes.md)。 容器即使没有可见背景,也会按自身矩形参与命中;不想挡住下面的元素就用 `noevent`,而不是把背景设成透明。 @@ -368,16 +375,16 @@ sequenceDiagram 外层与内层分别显示进入 / 离开状态。从外层移到内层时,外层不会触发 `leave`;滚轮累计与 `cursor` 也跟随命中结果变化。 ## 边界与注意 diff --git a/docs/advanced/ii/ui/hotkey-in-ui.md b/docs/render-guide/advanced/hotkey-in-ui.md similarity index 99% rename from docs/advanced/ii/ui/hotkey-in-ui.md rename to docs/render-guide/advanced/hotkey-in-ui.md index 0fae56b..6647c4b 100644 --- a/docs/advanced/ii/ui/hotkey-in-ui.md +++ b/docs/render-guide/advanced/hotkey-in-ui.md @@ -4,6 +4,13 @@ UI 里经常需要「按 Esc 关闭」「按 Enter 确认」「按方向键切 下面按「在哪里写」「组件里怎么接」「什么时候需要额外参数」展开。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [响应式](./reactivity.md) +- [事件与交互](./events.md) + ## 按键与元素事件 元素事件来自画布上的指针:先做命中测试,找到指针下的元素,再沿容器捕获与冒泡,关心的是「点在哪里」。 diff --git a/docs/advanced/ii/ui/inventory-example-1-skeleton.md b/docs/render-guide/advanced/inventory-example-1-skeleton.md similarity index 96% rename from docs/advanced/ii/ui/inventory-example-1-skeleton.md rename to docs/render-guide/advanced/inventory-example-1-skeleton.md index 6b84de0..420e455 100644 --- a/docs/advanced/ii/ui/inventory-example-1-skeleton.md +++ b/docs/render-guide/advanced/inventory-example-1-skeleton.md @@ -2,6 +2,13 @@ 前面五批讲的是零件:模板、元素、响应式、事件、组件、内置组件与 UI 栈。这一批把它们装成同一个能用的面板——一个背包 / 装备界面。六篇按「每一步只加一小段」推进,本篇先定目标、拆分与骨架。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [第一个静态界面](../basics/first-static-ui.md) +- [容器与坐标](../basics/container-and-coordinates.md) + ## 这一步要解决什么 最终面板是一块 720×480 的区域: @@ -18,7 +25,7 @@ ## 骨架在渲染树里的位置 -先把最终面板的节点定下来,后面每一步都往这棵树里加东西。根 `container` 下依次是画布底色、面板主体、标题、关闭按钮、左侧占位与右侧占位,它们都是兄弟节点;树形规则本身见[第 2 篇「容器与坐标」](./container-and-coordinates.md#渲染树根容器与子元素)。 +先把最终面板的节点定下来,后面每一步都往这棵树里加东西。根 `container` 下依次是画布底色、面板主体、标题、关闭按钮、左侧占位与右侧占位,它们都是兄弟节点;树形规则本身见[第 2 篇「容器与坐标」](../basics/container-and-coordinates.md#渲染树根容器与子元素)。 三个区域是根容器的子容器,彼此是兄弟关系。它们的坐标都相对根容器的左上角: @@ -36,7 +43,7 @@ 第一次在示例站(480×320)验证时,不用重排内部坐标:给面板根加 `scale={[2 / 3, 2 / 3]}`(比例取 `min(480 / 720, 320 / 480)`),`loc` 仍写 `[0, 0, 720, 480]`,整棵树会按同一比例缩小并完整落在 480×320 里。确认画面之后,如果要正式适配不同窗口,再按 `renderer.width` / `height` 改根 `loc` 并重排内部区域;不要同时改内部坐标和加缩放,否则会缩两次。 -同一父级下的遮挡按 `zIndex` 与加入顺序决定:关闭按钮画在面板主体之后,因此会盖在主体上,点击落在按钮矩形里就由它接收。完整层级规则见[第 7 篇「层级、变换与性能」](./layer-transform-performance.md#渲染树层级与绘制顺序)。 +同一父级下的遮挡按 `zIndex` 与加入顺序决定:关闭按钮画在面板主体之后,因此会盖在主体上,点击落在按钮矩形里就由它接收。完整层级规则见[第 7 篇「层级、变换与性能」](../basics/layer-transform-performance.md#渲染树层级与绘制顺序)。 ## 组件与文件怎么分 @@ -184,10 +191,10 @@ props.state.mainUIController.open(InventoryUI, {}); ## 边界与注意 diff --git a/docs/advanced/ii/ui/inventory-example-2-grid.md b/docs/render-guide/advanced/inventory-example-2-grid.md similarity index 97% rename from docs/advanced/ii/ui/inventory-example-2-grid.md rename to docs/render-guide/advanced/inventory-example-2-grid.md index 42bf57c..0132b56 100644 --- a/docs/advanced/ii/ui/inventory-example-2-grid.md +++ b/docs/render-guide/advanced/inventory-example-2-grid.md @@ -2,6 +2,13 @@ 上一篇的左侧只有一块占位。本篇把道具数据、`ItemCell` 与 `ItemGrid` 填进去,让网格能显示、能选中。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [示例(一)目标与骨架](./inventory-example-1-skeleton.md) +- [基础图形](../basics/basic-shapes.md) + ## 从占位到网格 本步只替换左侧占位区,右侧详情与底部操作条仍然是占位: @@ -284,10 +291,10 @@ const selectedItem = computed( ## 边界与注意 diff --git a/docs/advanced/ii/ui/inventory-example-3-detail.md b/docs/render-guide/advanced/inventory-example-3-detail.md similarity index 96% rename from docs/advanced/ii/ui/inventory-example-3-detail.md rename to docs/render-guide/advanced/inventory-example-3-detail.md index e14475e..92aa32f 100644 --- a/docs/advanced/ii/ui/inventory-example-3-detail.md +++ b/docs/render-guide/advanced/inventory-example-3-detail.md @@ -2,6 +2,14 @@ 上一篇左侧已经能选道具,右侧还是占位。本篇把 `ItemDetail` 填上:名称、数量、描述,以及没有选中时的提示。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [示例(二)道具网格](./inventory-example-2-grid.md) +- [文字](../basics/text.md) +- [通用参数](../basics/common-props.md) + ## 详情区接的是哪个状态 详情不自己保存状态,它只接收一个「选中项」。选中项在 `InventoryPanel` 里用 `computed` 从 `items` 与 `selectedId` 算出来: @@ -179,10 +187,10 @@ export { ItemDetail }; ## 边界与注意 diff --git a/docs/advanced/ii/ui/inventory-example-4-scroll.md b/docs/render-guide/advanced/inventory-example-4-scroll.md similarity index 97% rename from docs/advanced/ii/ui/inventory-example-4-scroll.md rename to docs/render-guide/advanced/inventory-example-4-scroll.md index b6cbf70..9071546 100644 --- a/docs/advanced/ii/ui/inventory-example-4-scroll.md +++ b/docs/render-guide/advanced/inventory-example-4-scroll.md @@ -2,6 +2,13 @@ 道具少的时候,网格一次就能排下。道具变多后,左侧区域放不下,需要滚动。本篇把示例(二)的普通网格换成 `Scroll`,并说明这次替换在渲染树、事件与数据流上各自改了什么。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [示例(三)详情区](./inventory-example-3-detail.md) +- [内置组件:布局](./builtin-layout.md) + ## 为什么要换滚动 普通容器只是按坐标把子元素画出来:区域外的格子照样绘制,超出的部分被窗口裁掉,但节点仍然在树上。道具只有十件时感觉不到问题;四十件时,左侧区域外的格子会越画越多,滚轮也没有任何反应。 @@ -191,10 +198,10 @@ const toBottom = () => { ## 边界与注意 diff --git a/docs/advanced/ii/ui/inventory-example-5-state.md b/docs/render-guide/advanced/inventory-example-5-state.md similarity index 97% rename from docs/advanced/ii/ui/inventory-example-5-state.md rename to docs/render-guide/advanced/inventory-example-5-state.md index 23245a8..e518c6d 100644 --- a/docs/advanced/ii/ui/inventory-example-5-state.md +++ b/docs/render-guide/advanced/inventory-example-5-state.md @@ -2,6 +2,14 @@ 网格、详情与滚动都齐了,但面板还只能看不能动。本篇加 `ActionBar`:装备、使用、关闭,并把状态与副作用收口到 `InventoryPanel`。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [示例(四)滚动与列表](./inventory-example-4-scroll.md) +- [响应式](./reactivity.md) +- [事件与交互](./events.md) + ## 这一步把交互接起来 三类操作各自改变一件事: @@ -346,10 +354,10 @@ key.implement('@common/exit', () => { ## 边界与注意 diff --git a/docs/advanced/ii/ui/inventory-example-6-animation-and-register.md b/docs/render-guide/advanced/inventory-example-6-animation-and-register.md similarity index 95% rename from docs/advanced/ii/ui/inventory-example-6-animation-and-register.md rename to docs/render-guide/advanced/inventory-example-6-animation-and-register.md index 2915ccd..a45aef0 100644 --- a/docs/advanced/ii/ui/inventory-example-6-animation-and-register.md +++ b/docs/render-guide/advanced/inventory-example-6-animation-and-register.md @@ -2,6 +2,14 @@ 前面五步已经把网格、详情、滚动与交互拼起来了。最后一步补三件事:让选中态与提示动起来、把代码落回五个文件、把面板注册成 `GameUI` 并从打开处接入。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [示例(五)交互与状态](./inventory-example-5-state.md) +- [自定义组件](./custom-components.md) +- [UI 系统](./ui-system.md) + ## 最后一步要收什么 收尾不是「再加一个功能」,而是把前面五步已经写下的东西固定下来: @@ -219,7 +227,7 @@ const instance = props.state.mainUIController.open(InventoryUI, {}); props.state.mainUIController.close(instance); ``` -打开时传的是 `GameUI` 对象本身,名字不参与查找;构造与命名的规则见[第 1 篇「UI 通用模板」](./ui-template.md#gameui-是一个对象不是名字)。 +打开时传的是 `GameUI` 对象本身,名字不参与查找;构造与命名的规则见[第 1 篇「UI 通用模板」](../basics/ui-template.md#gameui-是一个对象不是名字)。 关闭当前面板、马上打开另一个面板时,用 `props.controller.keep()` 包住切换,用完调用 `safelyUnload()`,避免背景闪一下;用法见[「UI 系统」的「keep」](./ui-system.md#keep)。 @@ -240,7 +248,7 @@ props.state.mainUIController.close(instance); 关闭后动画必须停:如果 `cancelAnimationFrame` 漏了,再次打开会看到两个循环同时在改 `pulse`,边框呼吸会变得忽快忽慢。这也是清单里「再次打开」要单独验证的原因。 -清单里的「再次打开」按 `close` 写:`close` 会卸载实例,再 `open` 得到新实例,所以未选中、滚动在顶部。如果你改用 `hide` 隐藏面板,实例与滚动位置都会保留,这一行的预期要相应改成「回到隐藏前的位置」;两种语义的区别见[第 7 篇「显示开关」](./layer-transform-performance.md)与[「UI 系统」的「隐藏与显示」](./ui-system.md#隐藏与显示)。 +清单里的「再次打开」按 `close` 写:`close` 会卸载实例,再 `open` 得到新实例,所以未选中、滚动在顶部。如果你改用 `hide` 隐藏面板,实例与滚动位置都会保留,这一行的预期要相应改成「回到隐藏前的位置」;两种语义的区别见[第 7 篇「显示开关」](../basics/layer-transform-performance.md)与[「UI 系统」的「隐藏与显示」](./ui-system.md#隐藏与显示)。 ## 运行效果 @@ -254,10 +262,10 @@ props.state.mainUIController.close(instance); ## 边界与注意 diff --git a/docs/advanced/ii/ui/reactivity.md b/docs/render-guide/advanced/reactivity.md similarity index 95% rename from docs/advanced/ii/ui/reactivity.md rename to docs/render-guide/advanced/reactivity.md index 183c986..4235c5a 100644 --- a/docs/advanced/ii/ui/reactivity.md +++ b/docs/render-guide/advanced/reactivity.md @@ -4,6 +4,13 @@ Vue 的响应式解决的就是这件事:数据被读取时记下依赖,数据变化时自动重新执行用到它的渲染函数,渲染器再把变化 patch 到画布上的元素。本篇从零讲清 UI 作者需要的那部分,不假设你写过 Vue。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [UI 入门](../basics/ui-basics.md) +- [第一个静态界面](../basics/first-static-ui.md) + ## 数据到渲染 响应式值变化后,读取过它的组件会重新执行渲染函数,对应元素的属性或子组件随之更新;没有读取它的组件不会因为这次变化而更新。 @@ -276,16 +283,16 @@ watch(count, (next, prev) => { 组件收到的 `props` 本身是响应式的。把字段解构出来会得到普通值,父组件更新后子组件不会跟着变;直接读 `props.title`,或在 render 函数里现取局部变量。props 的基本写法见[自定义组件](./custom-components.md#props)。 ## 边界与注意 diff --git a/docs/advanced/ii/ui/ui-performance.md b/docs/render-guide/advanced/ui-performance.md similarity index 94% rename from docs/advanced/ii/ui/ui-performance.md rename to docs/render-guide/advanced/ui-performance.md index ddee328..2625197 100644 --- a/docs/advanced/ii/ui/ui-performance.md +++ b/docs/render-guide/advanced/ui-performance.md @@ -2,6 +2,13 @@ 多数简单 UI 不需要特别的性能优化。渲染系统会按需更新,缓存也默认开在合适的元素上;按常规方式写,性能通常已经足够。下面是一组日常习惯,用来减少不必要的绘制与内存占用,按需采用即可。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [层级、变换与性能](../basics/layer-transform-performance.md) +- [UI 系统](./ui-system.md) + ## 元素平铺与分组 同一层里堆很多兄弟元素,会让一次更新牵动整层。更新会沿父链标脏,父容器需要重新遍历并绘制受影响的部分;兄弟越多,重复的工作越明显。按更新频率分组:把一起变化、且不常变的元素放进同一个 `container`,把频繁变化的元素单独放。不要为了分组嵌得太深,层级越深,布局、绘制与命中遍历的递归也越深。 @@ -95,7 +102,7 @@ const render = () => { ``` -缓存的默认值与开关语义见[层级、变换与性能](./layer-transform-performance.md#缓存与脏更新)。 +缓存的默认值与开关语义见[层级、变换与性能](../basics/layer-transform-performance.md#缓存与脏更新)。 ## 像素风:抗锯齿与高清 @@ -109,7 +116,7 @@ const render = () => { ``` -`hd` 与 `anti` / `noanti` 的完整说明见[通用参数](./common-props.md)。 +`hd` 与 `anti` / `noanti` 的完整说明见[通用参数](../basics/common-props.md)。 ## 显隐:hidden 与条件渲染 diff --git a/docs/advanced/ii/ui/ui-system.md b/docs/render-guide/advanced/ui-system.md similarity index 95% rename from docs/advanced/ii/ui/ui-system.md rename to docs/render-guide/advanced/ui-system.md index 15a8c4d..0a0582e 100644 --- a/docs/advanced/ii/ui/ui-system.md +++ b/docs/render-guide/advanced/ui-system.md @@ -4,6 +4,12 @@ UI 系统由控制器、实例和栈组成。每次 `open` 都会在控制器上 写 UI 时主要接触控制器与 `GameUI`;实例由系统创建,作者通常只持有 `open` 返回的实例,用来关闭或隐藏它。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [事件与交互](./events.md) + ## 打开与关闭 需要让一个界面出现在控制器管理的画面上时,用 `open(ui, vBind, alwaysShow?)`。`ui` 是声明的 `GameUI`,`vBind` 是传给组件的参数,`alwaysShow` 省略时为普通界面。每次调用都会新建一个实例、压入栈,并返回这个实例;后打开的实例默认叠在先打开的上面。 @@ -130,11 +136,11 @@ props.controller.showCustom(strategy); - `hide` 不会移除按键作用域,也不会让已打开的输入框失焦;需要彻底停止交互时用 `close`。 diff --git a/docs/advanced/ii/ui/what-is-component.md b/docs/render-guide/advanced/what-is-component.md similarity index 94% rename from docs/advanced/ii/ui/what-is-component.md rename to docs/render-guide/advanced/what-is-component.md index 7651580..cbe72f7 100644 --- a/docs/advanced/ii/ui/what-is-component.md +++ b/docs/render-guide/advanced/what-is-component.md @@ -4,6 +4,12 @@ 本篇只讲组件最基本的形态、props 的传法,以及组件与 GameUI 的关系。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [UI 入门](../basics/ui-basics.md) + ## 用 props 接收数据 组件通过 props 接收父组件给的数据。写法固定为三步: @@ -102,8 +108,8 @@ export const MyPanelUI = new GameUI('my-panel', MyPanel); diff --git a/docs/advanced/ii/ui/basic-shapes.md b/docs/render-guide/basics/basic-shapes.md similarity index 95% rename from docs/advanced/ii/ui/basic-shapes.md rename to docs/render-guide/basics/basic-shapes.md index 17780d6..1d84d87 100644 --- a/docs/advanced/ii/ui/basic-shapes.md +++ b/docs/render-guide/basics/basic-shapes.md @@ -4,6 +4,12 @@ 在逐个看图形之前,先弄清所有图形共用的填充、描边与颜色规则,后面每种图形的用法都建立在这套规则上。每种图形都有一个用数组传参的简写,日常写 UI 用简写最省事;逐个属性写的普通写法只在需要拆分或复用单个值时再用,下面每节只提一句。每种图形配一个 live,最后再把八种放在一起。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [容器与坐标](./container-and-coordinates.md) + ## 通用规则:填充、描边与颜色 图形有两种绘制模式:填充和描边。`fill`、`stroke`、`strokeAndFill` 是模式开关,值都是布尔值,不是颜色;颜色分别写在 `fillStyle` 与 `strokeStyle` 里。写 `fill="#f00"` 不会把图形变成红色,要写 `fill fillStyle="#f00"`;默认填充的图形本来就不用写 `fill`。 @@ -482,30 +488,30 @@ badge.closePath(); 这段代码里每种图形只出现一次,位置按 4×2 排开;换成自己的布局时,改各自的 `loc`、圆心或端点即可。 ## 默认值与注意 diff --git a/docs/advanced/ii/ui/common-props.md b/docs/render-guide/basics/common-props.md similarity index 93% rename from docs/advanced/ii/ui/common-props.md rename to docs/render-guide/basics/common-props.md index c27625e..30694d8 100644 --- a/docs/advanced/ii/ui/common-props.md +++ b/docs/render-guide/basics/common-props.md @@ -2,6 +2,13 @@ 这些属性大多数元素都能写。它们有的只在特定条件下有意义:`hd` 只对开启缓存的元素有效;`anti` / `noanti` 影响绘制内容在缩放时的插值;`cursor`、`hidden` 要鼠标经过或隐藏时才能看出差别。下面会说明每个参数在什么条件下有意义;场景只是由属性语义推出的适用条件,不是限定用途。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [容器与坐标](./container-and-coordinates.md) +- [基础图形](./basic-shapes.md) + ## hd `hd` 默认 `true`。它控制元素的缓存画布是否按设备像素比(DPR)使用高清分辨率:为 `true` 时缓存画布按 DPR 放大,为 `false` 时按 1x 绘制。它只对开启缓存的元素有效;没有缓存的元素写 `hd` 看不到可见变化。 @@ -135,16 +142,16 @@ diff --git a/docs/advanced/ii/ui/container-and-coordinates.md b/docs/render-guide/basics/container-and-coordinates.md similarity index 93% rename from docs/advanced/ii/ui/container-and-coordinates.md rename to docs/render-guide/basics/container-and-coordinates.md index 1f78270..9325495 100644 --- a/docs/advanced/ii/ui/container-and-coordinates.md +++ b/docs/render-guide/basics/container-and-coordinates.md @@ -2,6 +2,12 @@ 上一篇[《第一个静态界面》](./first-static-ui.md)已经用容器、文字和几个简单图形拼出了一块静态界面:`container` 圈出范围,文字和图形按 `loc` 摆进去。这一篇只讲怎么把元素放到想要的位置:坐标从哪里算起、`loc` 与锚点怎么配合、容器嵌套后子元素的坐标怎么变。事件、变换、缓存和层级都留到后面的篇章。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [第一个静态界面](./first-static-ui.md) + ## 坐标来源 根容器的左上角是原点,向右是正 `x`,向下是正 `y`。子元素的坐标相对父容器的左上角,不是相对整块画布;容器嵌套时,每一层都把坐标系重新平移一次。 @@ -88,12 +94,12 @@ 子容器的 `(0, 0)` 是它在父容器内的位置,不是画布原点;父容器移动时,子容器和里面的元素一起移动。 ## 边界与注意 diff --git a/docs/advanced/ii/ui/custom-and-container-custom.md b/docs/render-guide/basics/custom-and-container-custom.md similarity index 94% rename from docs/advanced/ii/ui/custom-and-container-custom.md rename to docs/render-guide/basics/custom-and-container-custom.md index 25b4efd..be8b9d5 100644 --- a/docs/advanced/ii/ui/custom-and-container-custom.md +++ b/docs/render-guide/basics/custom-and-container-custom.md @@ -2,6 +2,13 @@ `` 与 `` 用来处理现成元素无法直接表达的绘制与子元素控制:前者在元素内部直接用 Canvas 2D 画内容,后者接管子元素的绘制与事件传递。普通布局仍然优先用 `` 与现成元素;只有确实需要直接操作画布或控制子元素时才用这两个标签。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [容器与坐标](./container-and-coordinates.md) +- [基础图形](./basic-shapes.md) + ## custom `` 是叶子元素,没有子元素。它的尺寸与位置由 `loc` 决定,`loc` 之外不参与布局。 @@ -10,7 +17,7 @@ 系统在调用 `render` 前后已经保存并恢复了画布状态,函数里不需要在开头和结尾习惯性地写 `save` / `restore`。只有在函数内部临时改变状态、之后还要恢复并继续绘制时,才需要自己保存和恢复。 -`bindings` 接收依赖值数组。把 `render` 读取的响应式值放进数组,例如 `bindings={[angle.value]}`,不需要传 `ref` 对象。读取 `.value` 发生在父组件 render 中,和 `loc={[x.value, ...]}` 一样会被 Vue 追踪;值变化后父组件重渲染,`bindings` prop 更新,`` 重绘。`render` 函数本身不需要认识 Vue、`Ref` 或 `watch`,它只读取普通值。`Ref` 等响应式基础见[《响应式》](./reactivity.md)。 +`bindings` 接收依赖值数组。把 `render` 读取的响应式值放进数组,例如 `bindings={[angle.value]}`,不需要传 `ref` 对象。读取 `.value` 发生在父组件 render 中,和 `loc={[x.value, ...]}` 一样会被 Vue 追踪;值变化后父组件重渲染,`bindings` prop 更新,`` 重绘。`render` 函数本身不需要认识 Vue、`Ref` 或 `watch`,它只读取普通值。`Ref` 等响应式基础见[《响应式》](../advanced/reactivity.md)。 ::: warning 不要在 `render` 里修改用于 `bindings` 的响应式值(例如渲染时递增 `angle.value`),这会让渲染与状态更新互相触发。一般不会遇到这种情况,确实需要时会在高级 III 中进一步讲解。 @@ -131,10 +138,10 @@ const render = (canvas, children, transform) => { - 普通布局与能用现成元素表达的内容,继续用 `` 与现成元素。 diff --git a/docs/advanced/ii/ui/first-static-ui.md b/docs/render-guide/basics/first-static-ui.md similarity index 95% rename from docs/advanced/ii/ui/first-static-ui.md rename to docs/render-guide/basics/first-static-ui.md index ca93e34..8de507d 100644 --- a/docs/advanced/ii/ui/first-static-ui.md +++ b/docs/render-guide/basics/first-static-ui.md @@ -2,6 +2,12 @@ 这一篇从头拼一个静态界面:深色底、标题、一个图标、一个矩形、一个圆、一条分隔线,最后用两块重叠的矩形看层级。整屏 UI 用引擎给出的 `FULL_LOC`。每一步只加一种东西,最后得到一份可以直接运行的静态界面。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [UI 入门](./ui-basics.md) + ## 容器 界面从容器开始。容器决定这块 UI 占多大,也决定子元素的坐标从哪里算: @@ -153,10 +159,10 @@ export const MyPanelUI = new GameUI('my-panel', MyPanel); ## 后续 @@ -166,4 +172,4 @@ const staticUiLoader = () => - 文字样式:[文字](./text.md) - 纹理与素材:[图片与纹理](./image-and-texture.md) - 层级、变换与缓存:[层级、变换与性能](./layer-transform-performance.md) -- 让界面响应点击:[事件与交互](./events.md) +- 让界面响应点击:[事件与交互](../advanced/events.md) diff --git a/docs/advanced/ii/ui/image-and-texture.md b/docs/render-guide/basics/image-and-texture.md similarity index 88% rename from docs/advanced/ii/ui/image-and-texture.md rename to docs/render-guide/basics/image-and-texture.md index bb7c0b4..021f3d2 100644 --- a/docs/advanced/ii/ui/image-and-texture.md +++ b/docs/render-guide/basics/image-and-texture.md @@ -2,6 +2,12 @@ `` 用来显示一张纹理。它只负责把纹理按元素矩形铺开,本身不产生像素,也不负责加载。界面里用到的纹理都已经由客户端登记在贴图管理器里,写 UI 时从那里取,不在页面里现场生成。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [容器与坐标](./container-and-coordinates.md) + ## 贴图管理器中的纹理 `props.state.materials` 是 `ITextureManager`,客户端启动时把素材登记进去。取图片有两种方法: @@ -55,10 +61,10 @@ const texture = props.state.materials.getImageByAlias('bg.jpg'); - `` 会把纹理拉伸到 `loc` 的宽高,比例不一致会变形;按原图比例给尺寸。 diff --git a/docs/advanced/ii/ui/layer-transform-performance.md b/docs/render-guide/basics/layer-transform-performance.md similarity index 94% rename from docs/advanced/ii/ui/layer-transform-performance.md rename to docs/render-guide/basics/layer-transform-performance.md index 7ff9bd1..2099752 100644 --- a/docs/advanced/ii/ui/layer-transform-performance.md +++ b/docs/render-guide/basics/layer-transform-performance.md @@ -4,6 +4,13 @@
+## 前置知识 + +阅读本篇前,建议先读完: + +- [容器与坐标](./container-and-coordinates.md) +- [通用参数](./common-props.md) + ## 渲染树、层级与绘制顺序 元素组成一棵渲染树:子元素相对父元素定位,绘制顺序、变换与缓存都沿父子关系生效。同一父级下的兄弟按 `zIndex` 从小到大绘制,命中顺序相反;`zIndex` 只在兄弟之间比较,父级的 `zIndex` 带着整棵子树参与父级兄弟的排序。`zIndex` 与 `hidden` 的完整语义见[通用参数页](./common-props.md#zindex)。 @@ -122,12 +129,12 @@ UI 栈也遵循同一套规则。控制器把每个打开的面板当作 UI 容 - `composite` 影响绘制结果的混合方式,不改变布局与命中区域。 diff --git a/docs/advanced/ii/ui/text.md b/docs/render-guide/basics/text.md similarity index 94% rename from docs/advanced/ii/ui/text.md rename to docs/render-guide/basics/text.md index 95a95c8..1f82078 100644 --- a/docs/advanced/ii/ui/text.md +++ b/docs/render-guide/basics/text.md @@ -2,6 +2,13 @@ 文字元素只画一行。它的宽高由字体测量结果决定,不能自动换行,也没有行高与对齐属性;字号、字重、斜体这些信息由 `Font` 描述,`` 负责把内容画出来。这一篇先讲 `Font`,再讲文字元素怎么用、尺寸与锚点怎么定。 +## 前置知识 + +阅读本篇前,建议先读完: + +- [容器与坐标](./container-and-coordinates.md) +- [基础图形](./basic-shapes.md) + ## 字体:Font `Font` 是描述字体的值对象,不负责绘制。它只有五项配置: @@ -138,19 +145,19 @@ ## 换行、打字机与输入 -文字元素只画一行,`text` 里的换行符不会生效,长文本也不会按宽度折行。多行说明、按宽度折行与打字机效果不要用多个 `` 硬拼;用[内置组件:文本](./builtin-text.md)里的 `TextContent`。 +文字元素只画一行,`text` 里的换行符不会生效,长文本也不会按宽度折行。多行说明、按宽度折行与打字机效果不要用多个 `` 硬拼;用[内置组件:文本](../advanced/builtin-text.md)里的 `TextContent`。 ## 边界与注意 diff --git a/docs/advanced/ii/ui/ui-basics.md b/docs/render-guide/basics/ui-basics.md similarity index 90% rename from docs/advanced/ii/ui/ui-basics.md rename to docs/render-guide/basics/ui-basics.md index d543472..e936f51 100644 --- a/docs/advanced/ii/ui/ui-basics.md +++ b/docs/render-guide/basics/ui-basics.md @@ -2,6 +2,10 @@ 这篇讲三件事:怎样打开一个 UI、TSX 里的标签和组件怎么写、渲染树是什么样。看完你能在模板里写出文字和矩形。 +## 前置知识 + +无——只要掌握基础 TS/JS,并按本指南的阅读路径阅读即可。 + ## UI 的打开 每个 UI 是一个 `GameUI` 对象。在已有 UI 里,可以用 `props.controller` 打开另一个 UI,返回值是这次打开的实例: @@ -14,7 +18,7 @@ const instance = props.controller.open(MyPanelUI, {}); props.controller.close(instance); ``` -每次 `open` 都会得到独立实例,同一个 `GameUI` 也可以被打开多次。参数、栈顺序与 `alwaysShow` 的细节见 [UI 系统](./ui-system.md)。 +每次 `open` 都会得到独立实例,同一个 `GameUI` 也可以被打开多次。参数、栈顺序与 `alwaysShow` 的细节见 [UI 系统](../advanced/ui-system.md)。 ## TSX 里的标签和组件 @@ -75,7 +79,7 @@ props.controller.close(instance); 组件本身不额外产生节点,它的根元素挂在使用位置。组件内部写什么,由组件自己决定。 -条件与循环这里先不展开,用到时再看[条件渲染与循环渲染](./conditional-and-list-rendering.md)。 +条件与循环这里先不展开,用到时再看[条件渲染与循环渲染](../advanced/conditional-and-list-rendering.md)。 ## 渲染树的基本模型 @@ -163,10 +167,10 @@ export const MyPanelUI = new GameUI('my-panel', MyPanel); ## 后续 @@ -174,6 +178,6 @@ const basicsLoader = () => - 摆位置:[容器与坐标](./container-and-coordinates.md) - 画更多图形:[基础图形](./basic-shapes.md) - 写字:[文字](./text.md) -- 处理交互:[事件与交互](./events.md) -- 拆组件:[自定义组件](./custom-components.md) -- 接 UI 系统:[UI 系统](./ui-system.md) +- 处理交互:[事件与交互](../advanced/events.md) +- 拆组件:[自定义组件](../advanced/custom-components.md) +- 接 UI 系统:[UI 系统](../advanced/ui-system.md) diff --git a/docs/advanced/ii/ui/ui-template.md b/docs/render-guide/basics/ui-template.md similarity index 75% rename from docs/advanced/ii/ui/ui-template.md rename to docs/render-guide/basics/ui-template.md index 136d111..a047ad5 100644 --- a/docs/advanced/ii/ui/ui-template.md +++ b/docs/render-guide/basics/ui-template.md @@ -25,6 +25,10 @@ const MyPanel = defineComponent(props => { export const MyPanelUI = new GameUI('my-panel', MyPanel); ``` +## 前置知识 + +无——只要掌握基础 TS/JS,并按本指南的阅读路径阅读即可。 + ## 模板用法 1. 复制到 `src/client/ui/` 下新建的 `.tsx` 文件(例如 `my-panel.tsx`)。 @@ -38,7 +42,7 @@ export const MyPanelUI = new GameUI('my-panel', MyPanel); - 摆放元素:[容器与坐标](./container-and-coordinates.md) - 画图形:[基础图形](./basic-shapes.md) - 写字与图片:[文字](./text.md)、[图片与纹理](./image-and-texture.md) -- 让 UI 动起来:[响应式](./reactivity.md)、[事件与交互](./events.md) -- 拆组件:[自定义组件](./custom-components.md) -- 接 UI 系统:[UI 系统](./ui-system.md) -- 完整示例:[示例(一)目标与骨架](./inventory-example-1-skeleton.md) +- 让 UI 动起来:[响应式](../advanced/reactivity.md)、[事件与交互](../advanced/events.md) +- 拆组件:[自定义组件](../advanced/custom-components.md) +- 接 UI 系统:[UI 系统](../advanced/ui-system.md) +- 完整示例:[示例(一)目标与骨架](../advanced/inventory-example-1-skeleton.md) diff --git a/docs/render-guide/index.md b/docs/render-guide/index.md new file mode 100644 index 0000000..6ef34f1 --- /dev/null +++ b/docs/render-guide/index.md @@ -0,0 +1,76 @@ +# 渲染指南 + +本指南只讲画屏幕 / 写 UI:怎样用 TSX 画出界面、摆好位置、处理交互、拆成组件,以及 UI 系统与性能的取舍。数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统不在这里讲,仍见中级 / 高级教程;普通教程只保留主要的渲染逻辑,具体写法集中到本指南。 + +本指南只收现有 27 篇自定义 UI 文档,不新增系统文档,也不增设系统页面。 + +## 两级结构 + +| 分区 | 定位 | 页面数 | +| -------- | -------------------------------------------- | ------ | +| 渲染基础 | 模板、元素、坐标、图形、文字与元素属性 | 10 | +| 渲染进阶 | 响应式、事件、组件化、UI 系统/性能与完整示例 | 17 | + +分层是深度标签,不是领域分类:同一层里可能既有元素,也有组件或示例;读到哪一层取决于你要解决的问题,不必按层读完全部页面。 + +## 适合谁 + +- **完全没写过 UI**:从 [UI 通用模板(TSX)](./basics/ui-template.md) 起步,先拿模板跑起来,再用 [UI 入门](./basics/ui-basics.md) 认识标签、组件与渲染树。 +- **写过基础界面,想加交互与组件**:从[响应式](./advanced/reactivity.md)接手,把状态、事件与条件渲染接进已有界面。 +- **想了解 UI 系统与性能**:从 [UI 系统](./advanced/ui-system.md)读起,再看 [UI 性能](./advanced/ui-performance.md)的日常优化习惯。 + +## 阅读路径 + +- **从基础顺读**:[UI 通用模板(TSX)](./basics/ui-template.md) → [UI 入门](./basics/ui-basics.md) → [第一个静态界面](./basics/first-static-ui.md) → [容器与坐标](./basics/container-and-coordinates.md) → [基础图形](./basics/basic-shapes.md) → [文字](./basics/text.md) → [图片与纹理](./basics/image-and-texture.md) → [通用参数](./basics/common-props.md) → [层级、变换与性能](./basics/layer-transform-performance.md)。适合第一次写界面,先把静态部分画稳。 +- **从静态到交互**:[响应式](./advanced/reactivity.md) → [事件与交互](./advanced/events.md) → [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) → [按键与快捷键](./advanced/hotkey-in-ui.md) → [什么是组件](./advanced/what-is-component.md) → [自定义组件](./advanced/custom-components.md)。适合界面已经画出来、要接数据和操作的时候。 +- **做一个完整面板**:[示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) → [示例(二)道具网格](./advanced/inventory-example-2-grid.md) → [示例(三)详情区](./advanced/inventory-example-3-detail.md) → [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) → [示例(五)交互与状态](./advanced/inventory-example-5-state.md) → [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md)。适合把零件装成背包 / 装备面板。 +- **改内置 UI 或做性能取舍**:[什么是组件](./advanced/what-is-component.md) → [内置组件:基础](./advanced/builtin-basic.md) → [内置组件:布局](./advanced/builtin-layout.md) → [内置组件:文本](./advanced/builtin-text.md) → [自定义组件](./advanced/custom-components.md) → [UI 系统](./advanced/ui-system.md) → [UI 性能](./advanced/ui-performance.md)。适合替换现成控件或处理缓存与列表开销。 + +四条路径都建议先读 [UI 通用模板(TSX)](./basics/ui-template.md);模板是后面所有页面的起点。 + +## 页面目录 + +### 渲染基础 + +| 篇目 | 一句话说明 | 前置 | +| --------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| [UI 通用模板(TSX)](./basics/ui-template.md) | 写 UI 时从这段模板开始:复制、改名、在 `container` 里写内容 | 无 | +| [UI 入门](./basics/ui-basics.md) | 怎样打开 UI、TSX 的标签与组件怎么写、渲染树是什么样 | 无 | +| [第一个静态界面](./basics/first-static-ui.md) | 从头拼一个静态界面:深色底、标题、图标、图形、分隔线与层级 | [UI 入门](./basics/ui-basics.md) | +| [容器与坐标](./basics/container-and-coordinates.md) | 坐标从哪里算起、`loc` 与锚点怎么配合、嵌套后子元素怎么算 | [第一个静态界面](./basics/first-static-ui.md) | +| [基础图形](./basics/basic-shapes.md) | 八种图形元素的几何参数,以及共用的填充、描边与颜色规则 | [容器与坐标](./basics/container-and-coordinates.md) | +| [文字](./basics/text.md) | `Font` 与文字元素:单行绘制、尺寸测量与锚点对齐 | [容器与坐标](./basics/container-and-coordinates.md)、[基础图形](./basics/basic-shapes.md) | +| [图片与纹理](./basics/image-and-texture.md) | 从贴图管理器按别名或索引取纹理,按 `loc` 显示并处理比例 | [容器与坐标](./basics/container-and-coordinates.md) | +| [自绘元素与自定义容器](./basics/custom-and-container-custom.md) | 用 Canvas 2D 自绘内容,或接管子元素的绘制与事件传递 | [容器与坐标](./basics/container-and-coordinates.md)、[基础图形](./basics/basic-shapes.md) | +| [通用参数](./basics/common-props.md) | 大多数元素都能写的一组属性,以及它们在什么条件下有意义 | [容器与坐标](./basics/container-and-coordinates.md)、[基础图形](./basics/basic-shapes.md) | +| [层级、变换与性能](./basics/layer-transform-performance.md) | 渲染树的层级与绘制顺序、缩放旋转,以及缓存的取舍 | [容器与坐标](./basics/container-and-coordinates.md)、[通用参数](./basics/common-props.md) | + +### 渲染进阶 + +| 篇目 | 一句话说明 | 前置 | +| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| [响应式](./advanced/reactivity.md) | 数据变化如何自动推到画布元素,以及渲染函数读到什么才算依赖 | [UI 入门](./basics/ui-basics.md)、[第一个静态界面](./basics/first-static-ui.md) | +| [事件与交互](./advanced/events.md) | 点击、按下、抬起、移动、悬停与滚轮的捕获与冒泡 | [容器与坐标](./basics/container-and-coordinates.md)、[响应式](./advanced/reactivity.md) | +| [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) | 用 `hidden` 或三元做条件、用 `.map()` 做循环 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | +| [按键与快捷键](./advanced/hotkey-in-ui.md) | 按键指令、分组、作用域,以及组件里怎么接 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | +| [什么是组件](./advanced/what-is-component.md) | 组件最基本的形态、props 的传法,以及组件与 `GameUI` 的关系 | [UI 入门](./basics/ui-basics.md) | +| [内置组件:基础](./advanced/builtin-basic.md) | `Input`、`Icons`、`Arrow`、`Selection`、`Progress`、`Background` 与 `Slider` | [什么是组件](./advanced/what-is-component.md) | +| [内置组件:布局](./advanced/builtin-layout.md) | `Scroll`、`Page`、`List` 与 `ListPage` 的区域与列表用法 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | +| [内置组件:文本](./advanced/builtin-text.md) | `TextContent` 的折行与打字机、`ScrollText` 的自动滚动 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | +| [自定义组件](./advanced/custom-components.md) | 怎么接收参数、发事件、留出内容位置与透传属性 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) | +| [UI 系统](./advanced/ui-system.md) | 控制器、实例与栈:打开关闭、隐藏显示与显示策略 | [事件与交互](./advanced/events.md) | +| [UI 性能](./advanced/ui-performance.md) | 一组日常习惯,用来减少不必要的绘制与内存占用 | [层级、变换与性能](./basics/layer-transform-performance.md)、[UI 系统](./advanced/ui-system.md) | +| [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) | 定下背包 / 装备面板的目标、组件拆分与骨架 | [第一个静态界面](./basics/first-static-ui.md)、[容器与坐标](./basics/container-and-coordinates.md) | +| [示例(二)道具网格](./advanced/inventory-example-2-grid.md) | 把道具数据、`ItemCell` 与 `ItemGrid` 填进左侧,让网格能显示与选中 | [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md)、[基础图形](./basics/basic-shapes.md) | +| [示例(三)详情区](./advanced/inventory-example-3-detail.md) | 用 `ItemDetail` 填右侧:名称、数量、描述与空选中提示 | [示例(二)道具网格](./advanced/inventory-example-2-grid.md)、[文字](./basics/text.md)、[通用参数](./basics/common-props.md) | +| [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) | 把普通网格换成 `Scroll`,并说明渲染树、事件与数据流的变化 | [示例(三)详情区](./advanced/inventory-example-3-detail.md)、[内置组件:布局](./advanced/builtin-layout.md) | +| [示例(五)交互与状态](./advanced/inventory-example-5-state.md) | 加 `ActionBar`:装备、使用、关闭,并把状态收口到面板 | [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md)、[响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) | +| [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md) | 让选中态与提示动起来,把代码落回文件并注册成 `GameUI` | [示例(五)交互与状态](./advanced/inventory-example-5-state.md)、[自定义组件](./advanced/custom-components.md)、[UI 系统](./advanced/ui-system.md) | + +## 边界与注意 + +- 本指南只讲绘制屏幕与编写 UI;数据端、存档与录像、插件系统、编辑器等内容见中级 / 高级教程,这里不重复。 +- 元素坐标相对父容器,不是屏幕绝对坐标;需要跨元素比较位置时,用事件里的画布坐标。 +- 示例里的预览是文档站内固定尺寸的演示,与真实画布的尺寸、缩放和素材都不同;实际效果以接入后的画布为准。 +- 文字元素只画一行,不自动换行;长文本用内置的文本组件。 +- 缓存的默认值与开关只是当前实现的取舍,超出容器的绘制不要依赖缓存行为。