数据驱动PPT渲染引擎

为什么需要 pptx-craft

传统 PPT 制作的痛点在于绝对坐标计算。使用 pptxgenjs 等工具时，50+ 元素需要手写 200+ 个 (x,y,w,h) 坐标，一个计算错误就会导致元素重叠、截断或“气口”（呼吸感）不足。即使坐标正确，由于布局是单次顺序排列，元素间间距常因“最小化适配”而过于紧凑，缺乏视觉缓冲。

pptx-craft 通过数据模型驱动和文本优先的多遍布局解决这些问题：

• 不依赖 HTML 或画布，直接从数据模型生成可编辑 PPT
• 以模板为尺寸锚点，原生生成内容，避免缩放错位
• 文本优先布局确保文字“先占地”，装饰元素填充剩余空间
• 间距令牌（gap/padding）和密度系数（DENSITY）统一控制松紧，而非逐块调整
• QA 迭代器（最多 3 轮）自动优化字号，确保留白达标

它如何工作

1. 模板确认（Step 0）

- 无模板：使用内置通用模板（默认 16:9，33.87×19.05cm）
- 有模板：自动测量模板可用区（排除背景图，扫描 slide.shapes 和 slide.slide_layout.shapes 以避开页眉页脚）

1. 数据模型定义（Step 1）

- 定义 TOKENS（颜色、字体、圆角）和 DASHBOARD_DATA（数据快照）
- 这是唯一真相源，HTML/画布仅作为可选预览，不参与输入

1. 虚拟画布构建（Step 2）

- 使用 VW/VH 定义虚拟像素画布，比例匹配目标区域
- 通过 SCALE 和 OFFX/OFFY 映射到实际尺寸（如模板可用区的 EMU 坐标）

1. Flex 容器布局（Step 3）

- 使用 hbox/vbox 划分区域框架，子元素按 flex 权重分配空间
- 例如：hbox(deck, box, items, gap, pad) 自动计算子元素位置，修改父容器尺寸时子元素自动重排

1. 文本优先组件库（Step 4）

- 调用 KpiCard、CompareCard 等组件
- 每个组件内：先绘制背景矩形，再调用 layout_texts() 放置文本（通过 text_h() 测量字体高度，按 pad/breath 留气口），最后将装饰元素（如进度条）填充到剩余空间

1. 验证器检查（Step 5）

- 保存前运行 validate(deck.recs)，确保：
- 无越界元素
- 跨组元素无重叠（同组内文本嵌套允许）
- 相邻跨组元素间距≥MIN_BREATH 下限

适用边界

• 不要用于快速原型：若仅需截图级别的 PPT，直接截图（“方法1”）更高效
• 模板克隆场景：需提供 template_path，引擎会克隆模板并原生生成内容（主题/字体/页脚/logo 全继承）
• “尺寸自适应”是伪问题：当模板作锚点时，内容按模板真实可用区生成，无需事后缩放
• 数据模型需完整：若数据“实时更新”，导出时需传递快照（PPT 是时间切片，非实时数据源）