PPTX/openspec/changes/archive/2026-03-05-font-theme-system/tasks.md

字体主题系统实现任务清单

1. 数据结构更新

• 1.1 在 core/elements.py 中新增 FontConfig 数据类，定义所有字体属性（parent、family、size、bold、italic、underline、strikethrough、color、align、line_spacing、space_before、space_after、baseline、caps）
• 1.2 更新 TextElement.font 字段类型注解，支持 FontConfig | str | dict 类型
• 1.3 在 TableElement 中新增 font 字段（FontConfig | str | None）
• 1.4 在 TableElement 中新增 header_font 字段（FontConfig | str | None）
• 1.5 为 FontConfig 添加 post_init 验证方法（baseline 和 caps 枚举值验证）

2. 解析器实现

• 2.1 创建 utils/font_resolver.py 模块
• 2.2 实现 FontResolver 类，接受 fonts 和 fonts_default 参数
• 2.3 实现预设字体类别映射常量（sans → Arial, serif → Times New Roman, mono → Courier New, cjk-sans → Microsoft YaHei, cjk-serif → SimSun）
• 2.4 实现 resolve_font() 方法，处理字符串引用（整体引用 "@xxx"）
• 2.5 实现 resolve_font_dict() 方法，处理字典形式（parent、family、其他属性）
• 2.6 实现引用循环检测逻辑（维护已访问集合，检测重复引用）
• 2.7 实现属性继承链逻辑（parent → 当前 → fonts_default → 系统默认）
• 2.8 实现预设类别解析（识别 family 字段中的预设类别名称）

3. 加载器集成

• 3.1 在 loaders/yaml_loader.py 中添加解析 metadata.fonts 的逻辑
• 3.2 在 loaders/yaml_loader.py 中添加解析 metadata.fonts_default 的逻辑
• 3.3 验证 fonts_default 必须是引用格式（@xxx），直接字体名称抛出 ERROR
• 3.4 验证 fonts_default 引用的配置必须存在于 fonts 中
• 3.5 实现元素 font 字段转换逻辑（字符串/字典 → FontConfig 对象）
• 3.6 实现表格 font 和 header_font 字段转换逻辑

4. 渲染器更新

• 4.1 在 renderers/pptx_renderer.py 中导入 FontResolver
• 4.2 在 PptxGenerator.init 中初始化 FontResolver 实例
• 4.3 更新 _render_text() 方法，使用 FontResolver 解析 font 配置
• 4.4 在 _render_text() 中应用 font.family 属性
• 4.5 在 _render_text() 中应用 font.underline 属性
• 4.6 在 _render_text() 中应用 font.strikethrough 属性
• 4.7 在 _render_text() 中应用 paragraph.line_spacing 属性
• 4.8 在 _render_text() 中应用 paragraph.space_before 属性
• 4.9 在 _render_text() 中应用 paragraph.space_after 属性
• 4.10 在 _render_text() 中处理多行文本的扩展属性应用
• 4.11 更新 _render_table() 方法，支持 font 字段
• 4.12 更新 _render_table() 方法，支持 header_font 字段
• 4.13 实现 header_font 继承 font 的逻辑
• 4.14 在 _render_table() 中移除 style.font_size 和 style.header_color 的处理

5. 模板集成

• 5.1 在 core/template.py 的 render() 方法中获取 metadata.fonts_default
• 5.2 在模板元素渲染前，为未定义 font 的元素注入 fonts_default
• 5.3 确保内联模板支持字体继承
• 5.4 确保外部模板支持字体继承

6. 测试

6.1 移除旧语法相关测试

• 6.1.1 移除 test_pptx_renderer.py 中的 test_render_table 测试（使用旧语法 style.font_size）
• 6.1.2 移除 test_pptx_renderer.py 中的 test_render_table_with_header_style 测试（使用旧语法 style.font_size 和 style.header_color）
• 6.1.3 更新 test_render_table_col_widths_mismatch 测试，移除 style={} 参数

6.2 添加新语法相关测试

• 6.2.1 添加 FontConfig 数据类的单元测试
• 6.2.2 添加预设字体类别映射的单元测试
• 6.2.3 添加整体引用功能（font: "@xxx"）的单元测试
• 6.2.4 添加继承覆盖功能（font: {parent: "@xxx"}）的单元测试
• 6.2.5 添加引用循环检测的单元测试
• 6.2.6 添加属性继承链的单元测试
• 6.2.7 添加表格 font 字段的单元测试
• 6.2.8 添加表格 header_font 字段的单元测试
• 6.2.9 添加表格 header_font 继承 font 的单元测试
• 6.2.10 添加扩展字体属性（family、underline、strikethrough）的单元测试
• 6.2.11 添加段落属性（line_spacing、space_before、space_after）的单元测试
• 6.2.12 添加 baseline 和 caps 属性的单元测试
• 6.2.13 添加 baseline 和 caps 枚举值验证的单元测试
• 6.2.14 添加多行文本扩展属性应用的集成测试
• 6.2.15 添加模板字体继承的集成测试
• 6.2.16 添加引用循环错误的集成测试
• 6.2.17 添加预设字体类别解析的集成测试

6.3 更新现有测试以支持新语法

• 6.3.1 更新 test_render_text 测试，验证扩展字体属性应用
• 6.3.2 更新 test_render_multiline_text 测试，验证扩展属性应用到所有段落

7. 文档

• 7.1 更新 README.md，添加字体主题系统使用说明
• 7.2 更新 README.md，说明预设字体类别（sans、serif、mono、cjk-sans、cjk-serif）
• 7.3 更新 README.md，添加表格 font 和 header_font 字段说明
• 7.4 更新 README.md，说明扩展字体属性（underline、strikethrough、line_spacing 等）
• 7.5 更新 README_DEV.md，添加 FontConfig 和 FontResolver 的开发文档
• 7.6 更新 README_DEV.md，说明字体引用解析逻辑
• 7.7 在 tests/fixtures/yaml_samples/ 下添加字体主题系统示例 YAML 文件
• 7.8 在 tests/fixtures/yaml_samples/ 下添加预设字体类别示例 YAML 文件
• 7.9 在 tests/fixtures/yaml_samples/ 下添加表格字体配置示例 YAML 文件
• 7.10 在 tests/fixtures/yaml_samples/ 下添加扩展字体属性示例 YAML 文件
• 7.11 更新测试文档，说明移除旧语法测试的原因和新增测试的内容

8. 验证

• 8.1 运行单元测试，确保所有测试通过
• 8.2 手动测试预设字体类别显示效果
• 8.3 手动测试字体继承链功能
• 8.4 手动测试引用循环错误提示
• 8.5 手动测试表格新字体字段（font 和 header_font）
• 8.6 手动测试表格 header_font 继承 font 的功能
• 8.7 手动测试扩展字体属性（underline、strikethrough、line_spacing 等）
• 8.8 手动测试多行文本扩展属性应用
• 8.9 手动测试模板字体继承
• 8.10 生成示例 PPTX 文件并在 PowerPoint 中验证显示效果
• 8.11 验证旧语法（style.font_size、style.header_color）不再生效
• 8.12 验证新语法（font、header_font）正确工作