lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
229 lines
5.1 KiB
Markdown
229 lines
5.1 KiB
Markdown
# 混合模式
|
||
|
||
混合模式允许你在使用模板的同时添加自定义元素，实现更灵活的布局组合。
|
||
|
||
## 基本用法
|
||
|
||
在使用模板的幻灯片中，同时指定 `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)
|