lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
191 lines
3.9 KiB
Markdown
191 lines
3.9 KiB
Markdown
# 内联模板
|
||
|
||
内联模板允许你在 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)
|