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

字体主题系统设计文档

Context

当前系统在 core/elements.py 中定义 TextElement.font 为字典类型，支持 size、bold、italic、color、align 五个属性。渲染器 renderers/pptx_renderer.py 的 _render_text() 方法直接访问这些字典字段并应用到 python-pptx 对象。

表格元素 TableElement 通过 style.font_size 和 style.header_color 两个属性控制字体，与文本元素的 font 字典设计不一致。

系统不存在字体主题抽象，所有字体配置都在元素级别定义，导致重复配置和缺乏统一的样式管理。

约束条件

• 继续使用 python-pptx 库，不能引入新的 PowerPoint 生成依赖
• 字体检测不能污染主机环境配置，不能安装系统字体
• 主要面向中文用户，必须优先处理 CJK 字体支持
• 不考虑向后兼容性，使用新的字体配置语法
• temp 目录仅用于临时文件和测试中间文件，正式示例文件放在 tests/fixtures/ 下

Goals / Non-Goals

Goals:

• 引入 fonts 和 fonts_default 元数据字段，支持定义可复用的字体配置
• 实现三种字体引用方式：整体引用、继承覆盖、独立定义
• 提供五种预设字体类别（sans、serif、mono、cjk-sans、cjk-serif），直接映射到推荐字体名称
• 扩展字体属性集合，新增 family、underline、strikethrough、line_spacing、space_before、space_after、baseline、caps
• 统一表格元素的字体配置方式，新增 font 和 header_font 字段，移除旧语法 style.font_size 和 style.header_color

Non-Goals:

• 不实现富文本混合样式（同一段落多种字体）
• 不支持字体嵌入到 PPTX 文件（依赖系统字体）
• 不实现多语言字体回退链（如英文用 Arial、中文用微软雅黑的自动切换）
• 不验证字体是否存在（依赖 PowerPoint 自动回退）
• 不考虑向后兼容性（直接使用新语法）

Decisions

1. 数据结构设计

决策：使用 FontConfig 数据类替代原始字典

为保持与现有 TextElement 设计一致，创建 FontConfig 数据类封装字体配置：

@dataclass
class FontConfig:
    parent: Optional[str] = None
    family: Optional[str] = None
    size: Optional[int] = None
    bold: Optional[bool] = None
    italic: Optional[bool] = None
    underline: Optional[bool] = None
    strikethrough: Optional[bool] = None
    color: Optional[str] = None
    align: Optional[str] = None
    line_spacing: Optional[float] = None
    space_before: Optional[int] = None
    space_after: Optional[int] = None
    baseline: Optional[str] = None
    caps: Optional[str] = None

理由：

• 数据类提供类型提示和验证入口
• 与现有 TextElement、ImageElement 设计保持一致
• 便于序列化和反序列化

替代方案：

• 继续使用字典：失去类型安全，验证逻辑分散
• 继承 dict 的自定义类：复杂度增加，收益有限

2. 元素 font 字段类型

决策：font 字段支持 FontConfig | str 两种类型

@dataclass
class TextElement:
    font: FontConfig | str | dict = field(default_factory=dict)

理由：

• 字符串形式 font: "@title" 支持简洁的整体引用
• 字典形式兼容现有 YAML 语法
• FontConfig 对象作为内部表示

处理流程：

1. YAML 加载时保持原始类型（str 或 dict）
2. 元素创建前解析为 FontConfig 对象
3. 渲染时使用 FontConfig 对象

3. 预设字体类别映射

决策：直接映射到推荐字体名称，不进行字体验证

# 预设字体类别映射（跨平台推荐）
PRESET_FONT_MAPPING = {
    "sans": "Arial",              # 西文无衬线，跨平台通用
    "serif": "Times New Roman",   # 西文衬线，跨平台通用
    "mono": "Courier New",        # 等宽字体，跨平台通用
    "cjk-sans": "Microsoft YaHei",  # 中文无衬线（Windows 推荐）
    "cjk-serif": "SimSun",         # 中文衬线（Windows 推荐）
}

理由：

• 零依赖：不需要任何额外的字体检测库
• python-pptx 行为：测试表明 font.name 可以接受任意字符串，不会报错
• PowerPoint 回退：字体不存在时，由 PowerPoint 应用程序在打开文件时自动回退到系统默认字体
• 简化实现：避免复杂的平台检测和字体扫描逻辑

为什么不验证字体：

• python-pptx 不会验证字体是否存在
• 验证需要额外依赖或复杂的平台特定代码
• 字体不存在不会阻止转换，仅影响最终显示效果
• 用户可以在 PowerPoint 中看到字体回退情况

4. 字体引用解析顺序

决策：三阶段解析链（不验证字体）

1. parent 解析（如果存在）
   → 复制 fonts[parent] 的所有属性
   → 用当前定义的属性覆盖

2. family 解析
   → "@xxx" 格式：仅验证是有效的引用格式
   → "sans/..." 格式：映射到预设字体类别
   → "FontName" 格式：直接使用字体名称（不验证）

3. 未指定属性继承
   → 继承 fonts_default 指向的配置
   → 继承完成后仍为 None 的属性使用系统默认值

理由：

• 明确的优先级避免歧义
• parent 优先处理，确保覆盖逻辑正确
• 不验证字体存在，依赖 PowerPoint 自动回退

5. 表格字体配置

决策：使用 font 和 header_font 字段，提供完整字体配置

@dataclass
class TableElement:
    # 表格整体字体（应用于数据单元格）
    font: FontConfig | str | None = None

    # 表头字体（可选，未定义时继承 font）
    header_font: FontConfig | str | None = None

    # 表格样式（非字体相关，如背景色、边框等）
    style: dict = field(default_factory=dict)

字体解析优先级：

数据单元格：

1. font（如果定义）
2. fonts_default（如果 font 未定义）
3. 系统 默认

表头单元格：

1. header_font（如果定义）
2. font（如果 header_font 未定义）
3. fonts_default（如果都未定义）
4. 系统 默认

继承和覆盖：

• header_font 可以通过 parent: "@font" 继承表格字体，然后覆盖特定属性
• font 和 header_font 都支持引用方式：整体引用 font: "@body" 或继承覆盖 font: {parent: "@body", size: 14}

示例：

# 示例1: 表格整体字体
- type: table
  font:
    family: "Microsoft YaHei"
    size: 14
    color: "#333333"
  # 表头和数据单元格都使用相同样式

# 示例2: 表头使用不同样式
- type: table
  font:
    family: "Microsoft YaHei"
    size: 14
  header_font:
    parent: "@font"      # 继承表格字体
    bold: true          # 覆盖：表头加粗
    color: "#ffffff"    # 覆盖：表头白色
  style:
    header_bg: "#4a90e2"

# 示例3: 引用字体主题
- type: table
  font: "@table-body"
  header_font: "@table-header"

# 示例4: 仅定义表头字体
- type: table
  header_font:
    bold: true
    color: "#ffffff"
  # 数据单元格继承 fonts_default

理由：

• 统一的字体配置方式，与文本元素保持一致
• header_font 明确表示表头样式，语义清晰
• 支持继承覆盖，避免重复配置
• 移除 style.font_size 和 style.header_color，简化字段用途

6. 字体解析器模块化

决策：创建独立的 FontResolver 类

class FontResolver:
    def __init__(self, fonts: dict, fonts_default: Optional[str]):
        self.fonts = fonts
        self.default = fonts_default

    def resolve(self, font_config: FontConfig | str | dict) -> ResolvedFont:
        # 解析引用、继承、验证
        pass

    def resolve_family(self, family: str) -> str:
        # 处理预设类别和字体名称
        pass

    def validate_font(self, family: str) -> bool:
        # 检查字体可用性
        pass

理由：

• 集中字体解析逻辑，便于测试和维护
• 解耦渲染器和字体验证逻辑
• 便于单元测试各种引用场景

7. 模板字体继承

决策：模板元素未定义 font 时继承 fonts_default

模板渲染流程中：

1. 解析模板变量和条件渲染
2. 对每个元素检查 font 字段
3. 如果 font 未定义，将 fonts_default 的配置注入到元素 font 字段
4. 传递给渲染器处理

理由：

• 保持模板简洁，不需要为每个元素定义 font
• 允许通过 fonts_default 统一控制模板样式
• 模板仍可以覆盖特定元素的字体

Risks / Trade-offs

Risk 1: 字体不存在时显示效果不符合预期

风险： 用户指定了系统不存在的字体，PowerPoint 回退后显示效果与预期不符

缓解措施：

• 在文档中说明预设字体类别的推荐字体
• 建议用户使用预设字体类别以提高跨平台兼容性
• 可选：在转换日志中列出所有使用的字体名称供用户检查

Risk 2: 引用循环导致无限递归

风险： fonts 配置中存在循环引用，如 fonts.a.parent: "@b" 且 fonts.b.parent: "@a"

决策：检测到引用循环直接抛出 ERROR

在解析过程中维护已访问的引用链，检测到重复引用时立即抛出 ERROR 并提示循环引用路径。例如：

ERROR: 检测到字体引用循环: fonts.title -> fonts.subtitle -> fonts.title

缓解措施：

• 使用集合记录当前解析链中的引用名称
• 限制最大引用深度（如 10 层），超出时也抛出 ERROR
• 在错误信息中显示完整的引用路径，便于用户定位问题

Risk 3: 预设字体类别在不同平台表现不一致

风险： 预设字体类别映射到特定字体名称，不同平台的可用字体不同

缓解措施：

• 选择跨平台通用性最高的字体（如 Arial、Times New Roman）
• 在文档中说明各预设类别的推荐字体
• 用户可以通过 fonts 定义自己的字体配置来覆盖预设行为

Risk 4: 旧 YAML 文件需要迁移

风险： 使用旧语法的 YAML 文件需要更新才能使用新功能

缓解措施：

• 提供清晰的迁移文档和示例
• 新语法更加直观和强大，值得迁移成本
• 可以提供迁移脚本或工具辅助转换

Trade-off 1: 简洁性 vs 表达能力

权衡： 三种引用方式增加学习成本，但提供更强大的复用能力

决策： 优先表达能力，提供清晰的文档和示例

Trade-off 2: 字体验证 vs 简洁性

权衡： 验证字体是否存在（增加复杂度）vs 直接设置字体名（依赖 PowerPoint 回退）

决策： 不验证字体，直接设置字体名称。理由：

• python-pptx 不验证字体，可以接受任意字符串
• 字体不存在时 PowerPoint 会自动回退到系统默认字体
• 避免引入额外依赖或复杂的平台检测代码
• 用户可以在 PowerPoint 中查看最终效果

Migration Plan

阶段 1: 数据结构更新

1. 在 core/elements.py 中新增 FontConfig 数据类
2. 更新 TextElement 和 TableElement，font 字段支持 FontConfig | str | dict
3. 支持 dict 作为输入格式（在元素创建前转换为 FontConfig 对象）

阶段 2: 解析器实现

1. 创建 utils/font_resolver.py，实现 FontResolver 类
2. 实现预设字体类别映射（sans → Arial 等）
3. 实现字体引用解析逻辑（整体引用、继承覆盖、独立定义）
4. 实现引用循环检测和错误提示

阶段 3: 加载器集成

1. 在 loaders/yaml_loader.py 中解析 metadata.fonts 和 metadata.fonts_default
2. 将元素 font 字段从原始类型转换为 FontConfig 对象
3. 将 metadata.fonts 字典转换为 FontConfig 对象字典

阶段 4: 渲染器更新

1. 更新 renderers/pptx_renderer.py 的 _render_text() 方法：
   • 使用 FontResolver 解析 font 配置
   • 应用扩展字体属性（underline、strikethrough、line_spacing 等）
2. 更新 _render_table() 方法：
   • 支持 font 和 header_font 字段
   • 移除 style.font_size 和 style.header_color 的处理逻辑
3. 实现段落属性（line_spacing、space_before、space_after）

阶段 5: 模板集成

1. 更新 core/template.py，模板渲染时注入 fonts_default
2. 确保内联模板和外部模板都支持字体继承

阶段 6: 测试和文档

1. 新增单元测试覆盖字体解析、引用、继承逻辑
2. 新增集成测试覆盖各种 YAML 语法
3. 更新 README.md 和 README_DEV.md，说明预设字体类别
4. 添加示例 YAML 文件展示字体主题系统用法

Open Questions

1. fonts_default 未定义时的行为： 是否完全等同于当前行为，还是提供最小默认字体？

   • 倾向：完全等同当前行为，font 未设置时使用 python-pptx 的默认字体

2. 表格单元格级字体： 是否需要支持不同行/列使用不同字体？

   • 决策：不在当前范围，仅支持表头和数据单元格两种字体

3. 预设字体类别扩展： 是否允许用户自定义预设类别映射？

   • 决策：不在当前范围，预设类别保持系统内置。用户可以通过 fonts 定义自己的字体配置