lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
f1aae96a042e6f06bd1726e40edd93303f78fa13
PPTX/openspec/changes/archive/2026-03-05-refactor-external-template-system/proposal.md
lanyuanxiaoyao f1aae96a04 refactor: 重构外部模板系统，改为单文件模板库模式 
主要变更：
- 将 templates_dir 参数改为 template_file，支持单个模板库 YAML 文件
- 添加模板库 YAML 验证功能
- 为模板添加 base_dir 支持，正确解析相对路径资源
- 内联模板与外部模板同名时改为警告（内联优先）
- 移除模板缓存机制，直接使用模板库字典
- 更新所有相关测试以适配新的模板加载方式

此重构简化了模板管理，使模板资源的路径解析更加清晰明确。
2026-03-05 13:27:12 +08:00

3.1 KiB
Raw Blame History

Why

当前外部模板系统使用文件夹+文件名的方式存储和查询模板，与内联模板的字典查询方式不一致。这种不一致导致以下问题：

  1. 模板名称受文件命名规则限制（不能包含路径分隔符）
  2. 查询逻辑不统一（外部模板通过文件系统查找，内联模板通过字典键查找）
  3. 外部模板分散在多个文件中，难以管理和分发

重构为统一的模板库格式后，外部模板和内联模板将使用相同的数据结构和查询逻辑，提高系统一致性。

What Changes

  • BREAKING: 命令行参数 --template-dir 改为 --template，指定单个 YAML 文件而非文件夹
  • BREAKING: 外部模板文件格式从单个模板的 YAML 改为包含多个模板的模板库 YAML
  • 移除外部模板的缓存机制 (template_cache)
  • 统一资源路径解析：所有图片元素的相对路径在渲染前都解析为绝对路径
    • 自定义元素和内联模板元素：相对于文档 YAML 所在目录
    • 外部模板元素：相对于模板库文件所在目录
  • 模板库文件支持元数据字段（description、version、author 等）
  • 优化错误提示：区分模板库文件不存在、模板名称不存在两种错误
  • 同名冲突处理：内联和外部模板同名时发出 WARNING，优先使用内联模板

Capabilities

New Capabilities

  • template-library: 模板库文件的加载、验证和管理
    • 模板库文件必须包含 templates 字段（字典类型）
    • 支持元数据字段（description、version、author）
    • 递归验证每个模板的结构（vars、elements）
    • 提供模板库文件级别的错误提示

Modified Capabilities

  • template-system: 模板查询和引用逻辑
    • 外部模板查询从文件系统查找改为从模板库字典查找
    • 统一内联模板和外部模板的查询接口
    • 同名冲突时返回 WARNING 级别的验证问题

Impact

受影响的代码模块

  • yaml2pptx.py: 命令行参数修改
  • core/presentation.py: 模板加载逻辑重构，移除 template_cache
  • core/template.py: from_data 增加 base_dir 参数，render 中解析图片路径
  • loaders/yaml_loader.py: 新增 validate_template_library_yaml 函数
  • validators/resource.py: 修改模板验证逻辑，区分三种错误类型
  • validators/validator.py: 参数 template_dir 改为 template_file
  • preview/server.py: 参数 template_dir 改为 template_file
  • tests/: 更新相关测试用例

API 变更

命令行参数:

# 旧方式
yaml2pptx.py convert input.yaml --template-dir /path/to/templates/

# 新方式
yaml2pptx.py convert input.yaml --template /path/to/templates.yaml

模板库文件格式:

# 新格式 (templates.yaml)
description: "公司标准模板库"
version: "1.0.0"
templates:
  title-slide:
    vars: ...
    elements: ...
  content-slide:
    vars: ...
    elements: ...

依赖变更

无新增依赖。

兼容性

  • 不向后兼容：现有使用 --template-dir 的脚本需要更新为 --template
  • 现有的单文件模板需要迁移到模板库格式
View Git Blame Copy Permalink