lanyuanxiaoyao
98098dc911
实现了统一的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>
74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
# 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 级联测试
|