refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions
--- a/docs/templates/mixing-mode.md
+++ b/docs/templates/mixing-mode.md
@@ -0,0 +1,228 @@
+# 混合模式
+
+混合模式允许你在使用模板的同时添加自定义元素，实现更灵活的布局组合。
+
+## 基本用法
+
+在使用模板的幻灯片中，同时指定 `template` 和 `elements` 字段：
+
+```yaml
+slides:
+  # 混合模式：模板 + 自定义元素
+  - template: standard-header
+    vars:
+      title: "混合模式示例"
+      theme_color: "#3949ab"
+    elements:
+      # 自定义内容区域
+      - type: text
+        box: [1, 1.5, 8, 1]
+        content: "这是自定义内容"
+        font:
+          size: 24
+      # 自定义形状
+      - type: shape
+        shape: rectangle
+        box: [1, 3, 8, 2]
+        fill: "#f5f5f5"
+```
+
+## 变量共享
+
+自定义元素可以访问模板中定义的变量：
+
+```yaml
+templates:
+  branded-header:
+    vars:
+      - name: title
+      - name: theme_color
+        default: "#3949ab"
+    elements:
+      - type: shape
+        box: [0, 0, 10, 0.8]
+        fill: "{theme_color}"
+      - type: text
+        box: [0.5, 0.2, 9, 0.5]
+        content: "{title}"
+
+slides:
+  - template: branded-header
+    vars:
+      title: "我的页面"
+      theme_color: "#4caf50"
+    elements:
+      # 自定义元素使用模板变量
+      - type: shape
+        box: [1, 2, 8, 3]
+        fill: "{theme_color}"  # 使用模板的 theme_color
+```
+
+## 元素渲染顺序
+
+混合模式中，元素按以下顺序渲染（z 轴顺序）：
+
+1. **模板元素**（先渲染，在底层）
+2. **自定义元素**（后渲染，在上层）
+
+这意味着自定义元素会覆盖在模板元素之上。
+
+```yaml
+slides:
+  - template: background-template  # 提供背景和头部
+    vars:
+      title: "标题"
+    elements:
+      # 这些元素会显示在模板元素之上
+      - type: shape
+        box: [2, 2, 6, 3]
+        fill: "#ffffff"  # 白色框会覆盖背景
+```
+
+## 使用场景
+
+**适合使用混合模式**：
+
+- 复用统一的头部/底部，自定义中间内容
+- 使用模板提供的背景和品牌元素，添加页面特定内容
+- 需要在标准布局基础上添加特殊元素
+
+## 示例
+
+### 统一头部 + 自定义内容
+
+```yaml
+templates:
+  standard-header:
+    vars:
+      - name: title
+    elements:
+      # 统一的头部样式
+      - type: shape
+        box: [0, 0, 10, 0.8]
+        fill: "#3949ab"
+      - type: text
+        box: [0.5, 0.2, 9, 0.5]
+        content: "{title}"
+        font:
+          color: "#ffffff"
+
+slides:
+  # 页面 1：头部 + 文本内容
+  - template: standard-header
+    vars:
+      title: "文本页面"
+    elements:
+      - type: text
+        box: [1, 1.5, 8, 3]
+        content: "页面内容..."
+
+  # 页面 2：头部 + 表格
+  - template: standard-header
+    vars:
+      title: "数据页面"
+    elements:
+      - type: table
+        position: [1, 1.5]
+        col_widths: [3, 3]
+        data:
+          - ["列1", "列2"]
+          - ["数据1", "数据2"]
+
+  # 页面 3：头部 + 图片
+  - template: standard-header
+    vars:
+      title: "图片页面"
+    elements:
+      - type: image
+        box: [2, 1.5, 6, 3.5]
+        src: "chart.png"
+```
+
+### 背景模板 + 覆盖层
+
+```yaml
+templates:
+  gradient-bg:
+    vars:
+      - name: accent_color
+        default: "#3498db"
+    elements:
+      - type: shape
+        box: [0, 0, 10, 5.625]
+        fill: "{accent_color}"
+
+slides:
+  - template: gradient-bg
+    vars:
+      accent_color: "#9b59b6"
+    elements:
+      # 白色内容框覆盖在渐变背景上
+      - type: shape
+        box: [1, 1, 8, 3.625]
+        fill: "#ffffff"
+      - type: text
+        box: [1.5, 2, 7, 2]
+        content: "内容区域"
+        font:
+          size: 32
+```
+
+## 向后兼容性
+
+混合模式完全向后兼容：
+
+- **纯模板模式**：只指定 `template`，行为不变
+- **纯自定义模式**：只指定 `elements`，行为不变
+- **混合模式**：同时指定 `template` 和 `elements`，新功能
+
+```yaml
+slides:
+  # 纯模板模式（原有行为）
+  - template: title-slide
+    vars:
+      title: "标题"
+
+  # 纯自定义模式（原有行为）
+  - elements:
+      - type: text
+        content: "自定义内容"
+
+  # 混合模式（新功能）
+  - template: title-slide
+    vars:
+      title: "标题"
+    elements:
+      - type: text
+        content: "额外内容"
+```
+
+## 幻灯片 description 字段
+
+幻灯片可以包含可选的 `description` 字段，用于描述该幻灯片的作用和内容。**`description` 内容会自动写入 PPT 备注页**，方便在演示时查看演讲说明：
+
+```yaml
+slides:
+  - description: "介绍项目背景和目标"
+    template: title-slide
+    vars:
+      title: "项目背景"
+
+  - description: "展示核心功能特性"
+    elements:
+      - type: text
+        content: "功能特性"
+```
+
+**注意事项**：
+- 仅幻灯片级别的 `description` 会写入备注
+- 模板的 `description` 不会继承到幻灯片备注
+- `metadata.description` 用于描述整个演示文稿，不写入单个幻灯片备注
+
+## 相关文档
+
+- [内联模板](inline.md) - 在源文件中定义模板
+- [外部模板库](external-library.md) - 独立的模板库文件
+- [条件渲染](condition-rendering.md) - 元素和页面的条件显示
+
+[返回文档索引](../README.md)