Files

lanyuanxiaoyao 124ef0e5ce refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷：
- 用户文档迁移到 docs/ (用户指南、元素、模板、参考等)
- 开发文档迁移到 docs/development/ (架构、模块、规范)
- README.md 精简至 ~290 行，仅保留概览和导航
- 删除 README_DEV.md，内容已迁移
- 归档 OpenSpec 变更 refactor-docs-progressive-disclosure

2026-03-06 15:11:36 +08:00

4.2 KiB

Raw Blame History

作用域系统

字体作用域系统实现了文档和模板库之间的字体隔离和跨域引用控制。

作用域定义

系统定义了两个字体作用域：

文档作用域（document）

包含文档的 metadata.fonts 中定义的字体
文档的 fonts_default 只能引用文档作用域的字体
文档元素可以引用文档作用域和模板库作用域的字体

模板库作用域（template）

包含模板库的 metadata.fonts 中定义的字体
模板库的 fonts_default 只能引用模板库作用域的字体
模板元素只能引用模板库作用域的字体（不能引用文档字体）

跨域引用规则

允许的引用

文档元素 → 文档字体
文档元素 → 模板库字体（跨域引用）
模板元素 → 模板库字体
文档 fonts_default → 文档字体
模板库 fonts_default → 模板库字体

禁止的引用

模板元素 → 文档字体（跨域引用被禁止）
模板库 fonts_default → 文档字体（跨域引用被禁止）
文档 fonts_default → 模板库字体（跨域引用被禁止）

设计理由

模板库应该是自包含的，不依赖特定文档的字体配置
文档可以引用模板库字体，实现样式复用
防止模板库与文档之间的紧耦合

FontResolver 实现

初始化

class FontResolver:
    def __init__(self, fonts, fonts_default, scope="document", template_fonts=None):
        """
        Args:
            scope: 作用域标识 ("document" 或 "template")
            template_fonts: 模板库字体字典（仅文档作用域需要）
        """

跨域引用检测

使用作用域标签（doc.@font-name 或 template.@font-name）追踪引用路径
检测跨域循环引用（如 doc.@a → template.@b → doc.@a）
在 parent 引用时根据作用域限制跨域访问

fonts_default 级联规则

当元素未指定字体时，按以下顺序查找默认字体：

模板元素

模板库的 fonts_default（如果存在）
文档的 fonts_default（如果存在）
系统默认字体

文档元素

文档的 fonts_default（如果存在）
系统默认字体

循环引用检测

单域内循环

fonts:
  a:
    parent: "@b"
  b:
    parent: "@a"

错误信息：检测到字体引用循环: doc.@a -> doc.@b -> doc.@a

跨域循环

# 文档
fonts:
  doc-font:
    parent: "@template-font"

# 模板库
fonts:
  template-font:
    parent: "@doc-font"  # 这会被禁止

错误信息：检测到跨域字体引用循环: doc.@doc-font -> template.@template-font -> doc.@doc-font

错误代码

模板库 metadata 相关

TEMPLATE_LIBRARY_MISSING_METADATA - 模板库缺少 metadata 字段
TEMPLATE_LIBRARY_METADATA_MISSING_SIZE - 模板库 metadata 缺少 size 字段
TEMPLATE_LIBRARY_METADATA_INVALID_SIZE - 模板库 metadata.size 值无效

Size 一致性

SIZE_MISMATCH - 文档和模板库的 size 不一致

字体引用相关

TEMPLATE_FONT_REF_DOC_FORBIDDEN - 模板元素引用文档字体
TEMPLATE_PARENT_REF_DOC_FORBIDDEN - 模板库字体的 parent 引用文档字体
FONT_NOT_FOUND - 字体配置不存在
CIRCULAR_REFERENCE - 检测到字体引用循环
FONT_DEFAULT_INVALID - fonts_default 引用无效

使用示例

正确的跨域引用

# templates.yaml（模板库）
metadata:
  size: "16:9"
  fonts:
    template-title:
      family: "cjk-sans"
      size: 44
      bold: true

# presentation.yaml（文档）
metadata:
  size: "16:9"

slides:
  - elements:
      - type: text
        content: "正文"
        font: "@template-title"  # 文档元素可以引用模板库字体

错误的跨域引用

# templates.yaml（模板库）
metadata:
  size: "16:9"
  fonts_default: "@doc-body"  # 模板库 fonts_default 不能引用文档字体

templates:
  title-slide:
    elements:
      - type: text
        content: "{title}"
        font: "@doc-body"  # 模板元素不能引用文档字体

4.2 KiB Raw Blame History Unescape Escape