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

5.1 KiB

Raw Permalink Blame History

混合模式

混合模式允许你在使用模板的同时添加自定义元素，实现更灵活的布局组合。

基本用法

在使用模板的幻灯片中，同时指定 template 和 elements 字段：

slides:
  # 混合模式：模板 + 自定义元素
  - template: standard-header
    vars:
      title: "混合模式示例"
      theme_color: "#3949ab"
    elements:
      # 自定义内容区域
      - type: text
        box: [1, 1.5, 8, 1]
        content: "这是自定义内容"
        font:
          size: 24
      # 自定义形状
      - type: shape
        shape: rectangle
        box: [1, 3, 8, 2]
        fill: "#f5f5f5"

变量共享

自定义元素可以访问模板中定义的变量：

templates:
  branded-header:
    vars:
      - name: title
      - name: theme_color
        default: "#3949ab"
    elements:
      - type: shape
        box: [0, 0, 10, 0.8]
        fill: "{theme_color}"
      - type: text
        box: [0.5, 0.2, 9, 0.5]
        content: "{title}"

slides:
  - template: branded-header
    vars:
      title: "我的页面"
      theme_color: "#4caf50"
    elements:
      # 自定义元素使用模板变量
      - type: shape
        box: [1, 2, 8, 3]
        fill: "{theme_color}"  # 使用模板的 theme_color

元素渲染顺序

混合模式中，元素按以下顺序渲染（z 轴顺序）：

模板元素（先渲染，在底层）
自定义元素（后渲染，在上层）

这意味着自定义元素会覆盖在模板元素之上。

slides:
  - template: background-template  # 提供背景和头部
    vars:
      title: "标题"
    elements:
      # 这些元素会显示在模板元素之上
      - type: shape
        box: [2, 2, 6, 3]
        fill: "#ffffff"  # 白色框会覆盖背景

使用场景

适合使用混合模式：

复用统一的头部/底部，自定义中间内容
使用模板提供的背景和品牌元素，添加页面特定内容
需要在标准布局基础上添加特殊元素

示例

统一头部 + 自定义内容

templates:
  standard-header:
    vars:
      - name: title
    elements:
      # 统一的头部样式
      - type: shape
        box: [0, 0, 10, 0.8]
        fill: "#3949ab"
      - type: text
        box: [0.5, 0.2, 9, 0.5]
        content: "{title}"
        font:
          color: "#ffffff"

slides:
  # 页面 1：头部 + 文本内容
  - template: standard-header
    vars:
      title: "文本页面"
    elements:
      - type: text
        box: [1, 1.5, 8, 3]
        content: "页面内容..."

  # 页面 2：头部 + 表格
  - template: standard-header
    vars:
      title: "数据页面"
    elements:
      - type: table
        position: [1, 1.5]
        col_widths: [3, 3]
        data:
          - ["列1", "列2"]
          - ["数据1", "数据2"]

  # 页面 3：头部 + 图片
  - template: standard-header
    vars:
      title: "图片页面"
    elements:
      - type: image
        box: [2, 1.5, 6, 3.5]
        src: "chart.png"

背景模板 + 覆盖层

templates:
  gradient-bg:
    vars:
      - name: accent_color
        default: "#3498db"
    elements:
      - type: shape
        box: [0, 0, 10, 5.625]
        fill: "{accent_color}"

slides:
  - template: gradient-bg
    vars:
      accent_color: "#9b59b6"
    elements:
      # 白色内容框覆盖在渐变背景上
      - type: shape
        box: [1, 1, 8, 3.625]
        fill: "#ffffff"
      - type: text
        box: [1.5, 2, 7, 2]
        content: "内容区域"
        font:
          size: 32

向后兼容性

混合模式完全向后兼容：

纯模板模式：只指定 template，行为不变
纯自定义模式：只指定 elements，行为不变
混合模式：同时指定 template 和 elements，新功能

slides:
  # 纯模板模式（原有行为）
  - template: title-slide
    vars:
      title: "标题"

  # 纯自定义模式（原有行为）
  - elements:
      - type: text
        content: "自定义内容"

  # 混合模式（新功能）
  - template: title-slide
    vars:
      title: "标题"
    elements:
      - type: text
        content: "额外内容"

幻灯片 description 字段

幻灯片可以包含可选的 description 字段，用于描述该幻灯片的作用和内容。description 内容会自动写入 PPT 备注页，方便在演示时查看演讲说明：

slides:
  - description: "介绍项目背景和目标"
    template: title-slide
    vars:
      title: "项目背景"

  - description: "展示核心功能特性"
    elements:
      - type: text
        content: "功能特性"

注意事项：

仅幻灯片级别的 description 会写入备注
模板的 description 不会继承到幻灯片备注
metadata.description 用于描述整个演示文稿，不写入单个幻灯片备注

5.1 KiB Raw Permalink Blame History Unescape Escape