lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
3.9 KiB
3.9 KiB
内联模板
内联模板允许你在 YAML 源文件中直接定义模板，无需创建单独的模板文件。
定义内联模板
在 YAML 文件顶层添加 templates 字段：
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 变量
vars:
- name: title
required: true
可选变量与默认值
vars:
- name: subtitle
required: false
default: ""
内联模板特性
- 支持变量替换和条件渲染
- 可以与外部模板混合使用
- 无需指定
--template参数 - 内联模板不能相互引用
- 内联和外部模板同名时会发出警告，优先使用内联模板
何时使用内联模板
适合使用内联模板：
- 模板仅在单个文档中使用
- 快速原型开发
- 简单的模板定义（1-3 个元素）
- 文档自包含，无需外部依赖
适合使用外部模板：
- 需要跨多个文档复用
- 复杂的模板定义（>5 个元素）
- 团队共享的模板库
- 需要版本控制和独立维护
最佳实践
1. 命名规范
- 内联模板使用描述性名称（如
title-slide,content-slide） - 避免与外部模板同名，否则会发出警告
- 使用一致的命名风格（kebab-case 推荐）
2. 模板大小
- 内联模板建议不超过 50 行
- 超过 50 行考虑拆分或使用外部模板
- 保持 YAML 文件可读性
3. 混合使用
- 可以在同一文档中混合使用内联和外部模板
- 通用模板使用外部模板（如标题页、结束页）
- 文档特定模板使用内联模板
4. 迁移策略
- 原型阶段使用内联模板快速迭代
- 模板稳定后，如需复用则迁移到外部模板
- 使用
--template参数指定外部模板库文件
内联模板限制
- 内联模板不能相互引用（会报错）
- 内联和外部模板同名时会发出警告，优先使用内联模板
- 内联模板不支持继承或组合
示例
简单标题页
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"
带条件渲染的模板
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 省略，使用默认值 ""