feat: 实现模板元素混合模式功能
新增混合模式,允许幻灯片同时使用 template 和 elements,实现更灵活的布局组合。 核心变更: - core/presentation.py: 修改 render_slide() 支持三种模式(纯模板/纯自定义/混合模式) - 自定义元素可访问模板变量,实现主题色等值的统一控制 - 元素采用简单追加策略合并(模板元素在前,自定义元素在后) - 完全向后兼容现有用法 测试覆盖: - 新增 TestRenderSlideHybridMode 测试类,包含 8 个测试用例 - 验证向后兼容性(纯模板模式、纯自定义模式) - 验证混合模式功能(变量共享、空元素列表、元素顺序等) - 所有 79 个测试通过 文档更新: - README.md: 新增"混合模式模板"章节,包含语法示例和使用场景 - README_DEV.md: 更新开发文档,说明元素合并策略和实现细节 规范更新: - openspec/specs/template-system/spec.md: - 修改"系统必须支持自定义幻灯片"需求,支持混合模式 - 新增 4 个需求:变量共享、元素合并策略、向后兼容、内联模板支持 - 新增 13 个场景定义 归档: - openspec/changes/archive/2026-03-04-template-element-composition/: 完整变更记录
This commit is contained in:
165
README.md
165
README.md
@@ -418,6 +418,171 @@ slides:
|
||||
author: "作者"
|
||||
```
|
||||
|
||||
### 混合模式模板
|
||||
|
||||
混合模式允许你在使用模板的同时添加自定义元素,实现更灵活的布局组合。
|
||||
|
||||
#### 基本用法
|
||||
|
||||
在使用模板的幻灯片中,同时指定 `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]
|
||||
data: [[...]]
|
||||
|
||||
# 页面 3:头部 + 图片
|
||||
- template: standard-header
|
||||
vars:
|
||||
title: "图片页面"
|
||||
elements:
|
||||
- type: image
|
||||
box: [2, 1.5, 6, 3.5]
|
||||
src: "chart.png"
|
||||
```
|
||||
|
||||
#### 向后兼容性
|
||||
|
||||
混合模式完全向后兼容:
|
||||
|
||||
- **纯模板模式**:只指定 `template`,行为不变
|
||||
- **纯自定义模式**:只指定 `elements`,行为不变
|
||||
- **混合模式**:同时指定 `template` 和 `elements`,新功能
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
# 纯模板模式(原有行为)
|
||||
- template: title-slide
|
||||
vars:
|
||||
title: "标题"
|
||||
|
||||
# 纯自定义模式(原有行为)
|
||||
- elements:
|
||||
- type: text
|
||||
content: "自定义内容"
|
||||
|
||||
# 混合模式(新功能)
|
||||
- template: title-slide
|
||||
vars:
|
||||
title: "标题"
|
||||
elements:
|
||||
- type: text
|
||||
content: "额外内容"
|
||||
```
|
||||
|
||||
### 条件渲染
|
||||
|
||||
#### 元素级条件渲染
|
||||
|
||||
Reference in New Issue
Block a user