PPTX/openspec/specs/inline-templates/spec.md at master

Files

lanyuanxiaoyao 01eacb0b97 feat: 添加内联模板支持

支持在 YAML 源文件中直接定义模板，无需单独的模板文件。
简化单文档编写流程，降低模板系统使用门槛。

核心功能：
- 在 YAML 顶层新增 templates 字段定义内联模板
- 支持变量替换、条件渲染、默认值等完整模板功能
- 内联模板优先于外部模板查找
- 同名冲突检测：禁止内联和外部模板同名
- 相互引用检测：禁止内联模板之间相互引用
- 完整的错误处理和验证机制

代码变更：
- core/template.py: 新增 from_data() 类方法
- core/presentation.py: 支持内联模板查找和冲突检测
- loaders/yaml_loader.py: 新增 validate_templates_yaml() 验证
- validators/: 扩展验证器支持内联模板

测试：
- 新增 9 个内联模板专项测试
- 修复 1 个变量验证测试
- 所有 333 个测试通过

文档：
- README.md: 添加内联模板使用指南和最佳实践
- README_DEV.md: 说明实现细节和设计决策

完全向后兼容，不使用 templates 字段时行为不变。

2026-03-03 15:59:55 +08:00

5.6 KiB

Raw Permalink Blame History

Purpose

内联模板功能允许用户在 YAML 源文件中直接定义模板，无需单独的模板文件。这简化了单文档的编写流程，降低了模板系统的使用门槛，同时保持与外部模板系统的完全兼容。

Requirements

Requirement: YAML 文件支持内联模板定义

系统 SHALL 允许用户在 YAML 源文件的 templates 字段中定义内联模板，模板定义包括变量和元素。

Scenario: 定义简单的内联模板

WHEN 用户在 YAML 文件的 templates 字段中定义一个名为 title-slide 的模板，包含 vars 和 elements 字段
THEN 系统 SHALL 成功解析模板定义，并将模板存储在 inline_templates 字典中

Scenario: 定义多个内联模板

WHEN 用户在 YAML 文件的 templates 字段中定义多个不同的内联模板
THEN 系统 SHALL 成功解析所有模板定义，并允许通过模板名称引用任何一个模板

Requirement: 内联模板支持变量替换

系统 SHALL 支持在内联模板的元素中使用 {variable} 语法定义变量占位符，并在渲染时替换为实际值。

Scenario: 简单变量替换

WHEN 用户定义内联模板，在元素的 content 字段中使用 {title} 占位符，并在使用模板时提供 title: "My Title" 变量值
THEN 系统 SHALL 将占位符替换为 My Title

Scenario: 嵌套变量替换

WHEN 用户的模板默认值引用其他变量，如 default: "{title} - Extended"
THEN 系统 SHALL 递归解析所有变量引用，生成完整的替换结果

Requirement: 内联模板支持条件渲染

系统 SHALL 支持通过 visible 字段控制元素的显示，基于变量值的条件表达式。

Scenario: 条件渲染为真

WHEN 元素的 visible 字段设置为 "{subtitle != ''}"，且用户提供非空的 subtitle 值
THEN 系统 SHALL 在渲染结果中包含该元素

Scenario: 条件渲染为假

WHEN 元素的 visible 字段设置为 "{subtitle != ''}"，且用户提供空的 subtitle 值
THEN 系统 SHALL 在渲染结果中排除该元素

Requirement: 内联模板支持变量默认值

系统 SHALL 支持在模板的 vars 定义中为可选变量提供 default 值。

Scenario: 使用默认值

WHEN 用户的模板定义 subtitle 变量为可选（required: false），并提供 default: ""
THEN 系统 SHALL 在用户未提供 subtitle 变量时使用默认值

Scenario: 提供值覆盖默认值

WHEN 用户的模板定义了默认值，且用户在使用模板时提供了该变量的值
THEN 系统 SHALL 使用用户提供的值，而不是默认值

Requirement: 禁止内联和外部模板同名

系统 SHALL 检测内联模板和外部模板的名称冲突，当同名模板同时存在时，抛出 ERROR 级别错误。

Scenario: 内联和外部模板同名

WHEN 同名模板同时存在于内联 templates 字段和外部模板目录中
THEN 系统 SHALL 抛出 ERROR 级别错误，明确指出模板名称冲突，并禁止使用该模板

Scene: 内联和外部模板名称唯一

WHEN 内联模板和外部模板的名称都不相同
THEN 系统 SHALL 正常加载和使用模板，不产生任何错误

Requirement: 禁止内联模板相互引用

系统 SHALL 检测并禁止内联模板之间的相互引用。

Scenario: 检测到内联模板相互引用

WHEN 一个内联模板的 elements 中引用了另一个内联模板
THEN 系统 SHALL 抛出 ERROR 级别错误，明确指出内联模板不支持相互引用

Scenario: 内联模板正常使用

WHEN 用户使用内联模板，且模板的 elements 中不包含其他模板引用
THEN 系统 SHALL 正常渲染该模板

Requirement: 完整的错误处理

系统 SHALL 对内联模板的错误场景提供清晰的错误消息和适当的错误级别。

Scenario: 模板定义结构错误

WHEN templates 字段不是字典类型，或某个模板缺少必需的 elements 字段
THEN 系统 SHALL 在加载时抛出 ERROR 级别错误，包含具体的错误位置和原因

Scenario: 变量定义错误

WHEN 模板的 vars 定义中某个变量缺少必需的 name 字段
THEN 系统 SHALL 在加载时抛出 ERROR 级别错误

Scenario: 变量传递错误

WHEN 用户使用模板时缺少必需的变量，或传递了未定义的变量
THEN 系统 SHALL 在渲染时抛出 ERROR 或 WARNING 级别错误，明确指出问题所在

Requirement: 向后兼容

系统 SHALL 在不使用 templates 字段时，保持与现有版本完全一致的行为。

Scenario: 不使用 templates 字段

WHEN 用户的 YAML 文件不包含 templates 字段，只使用外部模板或直接定义元素
THEN 系统 SHALL 表现与现有版本完全一致，不产生任何副作用

Scenario: 混合使用内联和外部模板

WHEN 用户的 YAML 文件同时定义了内联模板和使用外部模板
THEN 系统 SHALL 支持两种模板类型在同一演示文稿中混合使用

Requirement: 内联模板数据验证

系统 SHALL 在加载 YAML 文件时验证内联模板的结构和内容。

Scenario: 验证模板结构

WHEN 用户定义的内联模板包含 vars 和 elements 字段，且结构正确
THEN 系统 SHALL 验证通过，允许后续使用该模板

Scenario: 验证元素结构

WHEN 用户的内联模板 elements 中定义了有效的元素类型和字段
THEN 系统 SHALL 验证通过，元素在渲染时正常工作

5.6 KiB Raw Permalink Blame History