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/external-library.md
+++ b/docs/templates/external-library.md
@@ -0,0 +1,192 @@
+# 外部模板库
+
+外部模板库是一个包含多个模板的 YAML 文件，适合跨文档复用和团队共享。
+
+## 创建模板库文件
+
+创建模板库文件 `templates.yaml`：
+
+```yaml
+# 模板库元数据（必需）
+metadata:
+  size: "16:9"  # 必需：模板库尺寸，必须与使用它的文档一致
+  description: "公司标准模板库"  # 可选：描述信息
+  fonts:  # 可选：模板库字体主题
+    template-title:
+      family: "cjk-sans"
+      size: 44
+      bold: true
+      color: "#2c3e50"
+    template-body:
+      family: "sans"
+      size: 20
+      color: "#34495e"
+  fonts_default: "@template-body"  # 可选：模板库默认字体
+
+# 模板定义（必需）
+templates:
+  title-slide:
+    description: "标题页模板"
+    vars:
+      - name: title
+        required: true
+      - name: subtitle
+        required: false
+        default: ""
+    elements:
+      - type: text
+        box: [1, 2, 8, 1]
+        content: "{title}"
+        font: "@template-title"  # 引用模板库字体
+      - type: text
+        box: [1, 3.5, 8, 0.5]
+        content: "{subtitle}"
+        visible: "{subtitle != ''}"
+        font:
+          parent: "@template-title"
+          size: 24
+          align: center
+
+  content-slide:
+    description: "内容页模板"
+    vars:
+      - name: title
+        required: true
+      - name: content
+        required: true
+    elements:
+      - type: text
+        box: [1, 1, 8, 0.8]
+        content: "{title}"
+        font:
+          parent: "@template-title"
+          size: 32
+      - type: text
+        box: [1, 2, 8, 3]
+        content: "{content}"
+        # 未指定 font 时使用 fonts_default
+```
+
+## 重要说明
+
+### 1. metadata 字段是必需的
+
+- `metadata.size` 必须指定（"16:9" 或 "4:3"）
+- 模板库的 size 必须与使用它的文档 size 一致，否则会报错
+
+### 2. 字体主题系统
+
+- 模板库可以定义自己的字体主题（`metadata.fonts`）
+- 文档可以引用模板库的字体（跨域引用）
+- 模板库不能引用文档的字体（单向引用）
+- 模板库的 `fonts_default` 只能引用模板库内部字体
+
+### 3. 字体级联规则
+
+- 模板元素未指定字体时，使用模板库的 `fonts_default`
+- 如果模板库没有 `fonts_default`，使用文档的 `fonts_default`
+- 如果都没有，使用系统默认字体
+
+## 使用外部模板库
+
+在命令行中指定模板库文件：
+
+```bash
+uv run yaml2pptx.py convert presentation.yaml output.pptx --template ./templates.yaml
+```
+
+在 YAML 文件中引用模板：
+
+```yaml
+slides:
+  - template: title-slide
+    vars:
+      title: "我的演示文稿"
+      subtitle: "使用外部模板库"
+
+  - template: content-slide
+    vars:
+      title: "第一章"
+      content: "这是内容"
+```
+
+## 模板库特性
+
+- 单个文件包含多个模板
+- 支持模板库元数据（description、version、author）
+- 每个模板可以有独立的 description
+- 便于版本控制和分发
+- 支持相对路径的图片资源（相对于模板库文件所在目录）
+
+## 模板库文件结构
+
+```yaml
+# 顶层元数据（可选）
+description: "模板库描述"
+version: "版本号"
+author: "作者"
+
+# 模板定义（必需）
+templates:
+  模板名称1:
+    description: "模板描述（可选）"
+    vars: [...]
+    elements: [...]
+
+  模板名称2:
+    description: "模板描述（可选）"
+    vars: [...]
+    elements: [...]
+```
+
+## 模板 description 字段
+
+模板可以包含可选的 `description` 字段，用于描述模板的用途和设计意图：
+
+```yaml
+templates:
+  title-slide:
+    description: "用于章节标题页的模板，包含主标题和副标题"
+    vars:
+      - name: title
+        required: true
+    elements:
+      - type: text
+        box: [1, 2, 8, 1]
+        content: "{title}"
+        font:
+          size: 44
+          bold: true
+```
+
+## 资源路径解析
+
+模板库中的图片资源使用相对于模板库文件所在目录的路径：
+
+```yaml
+# templates.yaml 所在目录：/path/to/templates/
+templates:
+  logo-slide:
+    elements:
+      - type: image
+        src: "images/logo.png"  # 相对于 templates.yaml 所在目录
+        box: [1, 1, 2, 2]
+```
+
+## 与内联模板的对比
+
+| 特性 | 内联模板 | 外部模板库 |
+|------|---------|-----------|
+| 定义位置 | 源文件中 | 独立文件 |
+| 适用场景 | 单文档使用 | 跨文档复用 |
+| 命令行参数 | 无需 | 需要 `--template` |
+| 模板间引用 | 不支持 | 支持 |
+| 字体主题 | 使用文档字体 | 可定义独立字体 |
+
+## 相关文档
+
+- [内联模板](inline.md) - 在源文件中定义模板
+- [混合模式](mixing-mode.md) - 模板与自定义元素组合
+- [字体主题系统](../fonts.md) - 字体配置和跨域引用
+
+[返回文档索引](../README.md)