lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
98098dc911f7cf84f7bed2e1e4c0ca6b526abee1
PPTX/openspec/changes/archive/2026-03-05-template-metadata-and-font-ref/proposal.md
lanyuanxiaoyao 98098dc911 feat: 实现模板库metadata和跨域字体引用系统 
实现了统一的metadata结构和字体作用域系统，支持文档和模板库之间的单向字体引用。

主要变更：
- 模板库必须包含metadata字段（包括size、fonts、fonts_default）
- 实现文档和模板库的size一致性校验
- 实现字体作用域系统（文档可引用模板库字体，反之不可）
- 实现跨域循环引用检测
- 实现fonts_default级联规则（模板库→文档→系统默认）
- 添加错误代码常量（SIZE_MISMATCH、FONT_NOT_FOUND等）
- 更新文档和开发者指南

测试覆盖：
- 新增33个测试（单元测试20个，集成测试13个）
- 所有457个测试通过

Breaking Changes：
- 模板库文件必须包含metadata字段
- 模板库metadata.size为必填字段
- 文档和模板库的size必须一致

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-03-05 18:12:05 +08:00

2.7 KiB
Raw Blame History

Proposal: 模板库元数据与跨域字体引用

Why

当前系统中，文档可以定义 metadata.fonts 来管理字体主题，但模板库缺乏相应的元数据结构，导致：

  1. 模板库无法定义自己的字体配置，限制了模板的独立性和复用性
  2. 模板中的元素无法引用统一的字体配置
  3. 文档和模板库之间缺乏明确的字体引用关系规范

本变更旨在统一文档和模板库的元数据结构，建立清晰的跨域字体引用规则。

What Changes

  • 模板库增加 metadata 结构

    • 模板库必须包含 metadata 字段，与文档使用相同的结构
    • metadata.size 必填，必须是 "16:9" 或 "4:3"
    • 其他字段（version、author、description、fonts、fonts_default）可选
    • 模板库的 fonts 定义模板级别的字体配置

  • 文档 metadata 扩展

    • 新增 version 字段（可选）
    • 新增 author 字段（可选）

  • 跨域字体引用规则

    • 文档元素和内联模板元素：优先引用文档 fonts，文档没有时可引用模板库 fonts
    • 外部模板元素：只能引用模板库 fonts，不能引用文档 fonts
    • 文档 fonts 的 parent：可引用文档内部或模板库 fonts
    • 模板库 fonts 的 parent：只能引用模板库内部 fonts

  • fonts_default 级联规则

    • 模板元素未定义 font 时：优先使用文档 fonts_default，文档没有则使用模板库 fonts_default

  • size 一致性校验

    • 文档的 size 必须与模板库的 size 一致
    • 不一致时抛出 ERROR 级别错误

Capabilities

New Capabilities

Modified Capabilities

  • template-library: 扩展模板库能力，支持 metadata 结构和字体配置
  • font-theme: 扩展字体主题能力，支持跨域引用（文档引用模板库）

Impact

受影响的代码模块

  • loaders/yaml_loader.py: 添加模板库 metadata 验证逻辑
  • validators/validator.py: 添加 size 一致性校验
  • core/presentation.py: 解析和存储模板库 metadata.fonts
  • core/template.py: 模板渲染时应用字体引用规则
  • utils/font_resolver.py: 扩展字体解析器，支持跨域引用

API 变更

  • validate_template_library_yaml() 增加 metadata 验证
  • Template 类增加字体解析上下文（是文档作用域还是模板库作用域）
  • FontResolver 增加跨域引用检测逻辑

破坏性变更

  • 模板库必须包含 metadata 字段且 size 必填
  • 需要清理旧的模板库相关测试，重新设计新测试

测试影响

  • 清理旧的模板库验证测试
  • 重新设计模板库 metadata 相关测试
  • 新增跨域字体引用测试
  • 新增 size 一致性校验测试
  • 新增 fonts_default 级联测试
View Git Blame Copy Permalink