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/inline.md
+++ b/docs/templates/inline.md
@@ -0,0 +1,190 @@
+# 内联模板
+
+内联模板允许你在 YAML 源文件中直接定义模板，无需创建单独的模板文件。
+
+## 定义内联模板
+
+在 YAML 文件顶层添加 `templates` 字段：
+
+```yaml
+metadata:
+  size: "16:9"
+
+templates:
+  title-slide:
+    vars:
+      - name: title
+        required: true
+      - name: subtitle
+        required: false
+        default: ""
+    elements:
+      - type: text
+        box: [1, 2, 8, 1]
+        content: "{title}"
+        font:
+          size: 44
+          bold: true
+          align: center
+      - type: text
+        box: [1, 3.5, 8, 0.5]
+        content: "{subtitle}"
+        visible: "{subtitle != ''}"
+        font:
+          size: 24
+          align: center
+
+slides:
+  - template: title-slide
+    vars:
+      title: "我的演示文稿"
+      subtitle: "使用内联模板"
+```
+
+## 变量定义
+
+### required 变量
+
+```yaml
+vars:
+  - name: title
+    required: true
+```
+
+### 可选变量与默认值
+
+```yaml
+vars:
+  - name: subtitle
+    required: false
+    default: ""
+```
+
+## 内联模板特性
+
+- 支持变量替换和条件渲染
+- 可以与外部模板混合使用
+- 无需指定 `--template` 参数
+- 内联模板不能相互引用
+- 内联和外部模板同名时会发出警告，优先使用内联模板
+
+## 何时使用内联模板
+
+**适合使用内联模板**：
+- 模板仅在单个文档中使用
+- 快速原型开发
+- 简单的模板定义（1-3 个元素）
+- 文档自包含，无需外部依赖
+
+**适合使用外部模板**：
+- 需要跨多个文档复用
+- 复杂的模板定义（>5 个元素）
+- 团队共享的模板库
+- 需要版本控制和独立维护
+
+## 最佳实践
+
+### 1. 命名规范
+
+- 内联模板使用描述性名称（如 `title-slide`, `content-slide`）
+- 避免与外部模板同名，否则会发出警告
+- 使用一致的命名风格（kebab-case 推荐）
+
+### 2. 模板大小
+
+- 内联模板建议不超过 50 行
+- 超过 50 行考虑拆分或使用外部模板
+- 保持 YAML 文件可读性
+
+### 3. 混合使用
+
+- 可以在同一文档中混合使用内联和外部模板
+- 通用模板使用外部模板（如标题页、结束页）
+- 文档特定模板使用内联模板
+
+### 4. 迁移策略
+
+- 原型阶段使用内联模板快速迭代
+- 模板稳定后，如需复用则迁移到外部模板
+- 使用 `--template` 参数指定外部模板库文件
+
+## 内联模板限制
+
+- 内联模板不能相互引用（会报错）
+- 内联和外部模板同名时会发出警告，优先使用内联模板
+- 内联模板不支持继承或组合
+
+## 示例
+
+### 简单标题页
+
+```yaml
+metadata:
+  size: "16:9"
+
+templates:
+  simple-title:
+    vars:
+      - name: title
+        required: true
+    elements:
+      - type: text
+        box: [1, 2.5, 8, 1]
+        content: "{title}"
+        font:
+          size: 44
+          bold: true
+          align: center
+
+slides:
+  - template: simple-title
+    vars:
+      title: "欢迎使用 yaml2pptx"
+```
+
+### 带条件渲染的模板
+
+```yaml
+templates:
+  optional-subtitle:
+    vars:
+      - name: title
+        required: true
+      - name: subtitle
+        required: false
+        default: ""
+    elements:
+      - type: text
+        box: [1, 2, 8, 1]
+        content: "{title}"
+        font:
+          size: 44
+          bold: true
+          align: center
+      - type: text
+        box: [1, 3.2, 8, 0.6]
+        content: "{subtitle}"
+        visible: "{subtitle != ''}"
+        font:
+          size: 24
+          align: center
+
+slides:
+  - template: optional-subtitle
+    vars:
+      title: "标题"
+      subtitle: "有副标题"
+
+  - template: optional-subtitle
+    vars:
+      title: "只有标题"
+      # subtitle 省略，使用默认值 ""
+```
+
+## 相关文档
+
+- [外部模板库](external-library.md) - 独立的模板库文件
+- [混合模式](mixing-mode.md) - 模板与自定义元素组合
+- [条件渲染](condition-rendering.md) - 元素和页面的条件显示
+
+[返回文档索引](../README.md)