复杂 Blazor UI 功能规划：当页面有 3+…

适用于构建包含多个独立视觉区域、交互子功能、侧边栏与内容面板的复杂 Blazor 页面、仪表盘或布局。

适用场景

解决思路

1. 当被要求构建复杂 UI 功能时，先规划组件分解，然后立即实现；单个单体页面组件几乎从不是正确答案，要把 UI 拆成聚焦、可组合的组件。
2. Step 1 — 映射视觉区域：阅读请求，识别每个不同的视觉区域；每个拥有自己的数据、行为或布局职责的区域都是候选组件。
3. 画出组件树，例如 InventoryDashboard 页面拥有数据并编排布局，包含 StockSummaryBar、InventoryFilters、InventoryTable（内含 InventoryRow）和 AddProductForm。
4. 识别组件的规则：当区域有明确独立职责、拥有自身状态或行为时，拆成单独组件。
5. 识别组件的规则：当存在重复结构（如列表项、网格卡片）时，提取 item template。
6. 识别组件的规则：当某区域独立处理用户输入且与兄弟区域分离时，拆成单独组件。
7. 识别组件的规则：任何单独超过约 150 行 markup 的区域都要拆分。
8. Step 2 — 对组件树中的每个组件确定：Component、Action、Render Mode、State Owned、Lines（est.）。
9. 若页面组件的 markup 加代码合计超过约 200 行，就太大了；如果估计单个组件超过该值，继续拆分。
10. Step 3 — 为每份数据识别 state owner，然后映射数据如何流动。
11. 数据总是通过 [Parameter] 向下流动。
12. 事件总是通过 EventCallback<T> 向上流动。
13. 页面/父组件拥有数据，并向子组件传递 filtered/transformed views。
14. 子组件绝不修改 parameters；它们通过 callbacks 通知父组件。
15. 如果数据必须跨越超过 2 层，且中间组件不需要该数据，使用 cascading value 或 scoped service。
16. 映射数据流示例：InventoryDashboard 拥有 products[]、filters；通过 [Parameter] 传给 StockSummaryBar、InventoryFilters、InventoryTable；子组件通过 EventCallback<Filters> OnFiltersChanged、EventCallback<Product> OnSave/OnDelete、EventCallback<Product> OnProductAdded 通知父级。
17. Step 4 — 创建新组件前，检查项目中已有组件是否能满足目的。
18. 寻找已有匹配结构的 list-item 组件。
19. 寻找项目中已有的共享 filter/search 组件。
20. 寻找接受 templates 的通用组件（如 DataTable<T>、Pagination）。
21. 如果组件会用于多个页面，把它放在 Shared/ 或 Components/ 文件夹。
22. Step 5 — 按自底向上顺序实现：先叶子组件，再组合它们的父组件。
23. 1. Models/DTOs：定义数据形状。
24. 2. Services：实现数据访问、业务逻辑（interface + implementation）。
25. 3. Leaf components：创建没有子组件的组件（InventoryRow、StockSummaryBar）。
26. 4. Container components：创建组合叶子的组件（InventoryTable、InventoryFilters）。
27. 5. Page component：把所有内容接起来并注册 routes。
28. 6. Configuration：完成依赖注入（DI）注册、render mode 设置。
29. 每个组件应能独立编译；绝不引用尚不存在的组件。
30. Output Format — 简要呈现计划，然后立即实现；绝不止于计划或写代码前询问确认。计划是思考工具，不是交付物。
31. 输出 markdown 计划，包含：## Component Plan: [Feature Name]。
32. 输出计划中的 ### Component Tree，用 ASCII tree 显示父子关系。
33. 输出计划中的 ### Component Table，列为 Component、Action、Render Mode、Purpose、Est. Lines。
34. 输出计划中的 ### Data Flow，写清 state owner → Parameters down → EventCallbacks up。
35. 输出计划中的 ### Implementation Order，列出第一个要创建的文件及原因、第二个文件及原因等。
36. 输出计划后，立即按列出的顺序实现组件；不要等待批准或问 “shall I proceed?”。
37. Anti-Pattern：不要写 500+ 行的单个页面组件；改为分解成聚焦组件。
38. Anti-Pattern：不要通过中间组件传递 10+ 个 parameters；改用 cascading values 或 scoped state service。
39. Anti-Pattern：不要让孩子组件自己从 API 获取数据；由父组件拥有数据并通过 parameters 传递。
40. Anti-Pattern：不要用复杂 markup 内联渲染列表项；把 item template 提取成独立组件。
41. Anti-Pattern：不要先在一个文件里构建所有东西再“以后重构”；upfront 规划分解，因为重构很少发生且单体容易上线。
42. Anti-Pattern：不要为一次性用途创建通用组件；只有复用被证明时才提取 generics。
43. Guideline：简要计划，然后实现；写简洁的组件表和数据流图，然后立即创建 .razor 文件，绝不止于计划。
44. Guideline：偏好多个小组件而非一个大组件；单一明确用途的组件更易理解、测试和复用。
45. Guideline：状态所有权是第一个决策；写 fetch 逻辑前，先决定哪个组件拥有数据。
46. Guideline：自底向上构建；先创建叶子组件，让父组件可以立即引用它们。
47. Guideline：按组件渲染的内容命名，而不是按内部行为命名：ProductCard 而不是 ProductRenderer，OrderFilters 而不是 FilterHandler。

适用边界 · 注意事项

• 不要用于创建新的 Blazor 项目或从零开始创建应用（使用 create-blazor-project）。
• 不要用于实现单个独立组件，或用 parameters 和 EventCallback 编写组件代码（使用 author-component）。
• 不要用于简单的单组件页面。