# 占位符语法参考

PPT 模板中使用占位符标记需要替换的内容。

## 文本占位符

语法: `{变量名}`

在 PPT 的任意文本框或表格单元格中使用。替换时保留原始字体格式。

示例:
- `{标题}` → 替换为文本数据中 "标题" 键对应的值
- `{日期}` → 替换为 "日期" 对应的值
- `{收益率}%` → 替换数值并保留 % 符号

## 图表占位符

语法: `{@图:图表名}` 或 `{@图|图表名}`

放在一个矩形或文本框中。替换时，整个形状被删除并替换为同尺寸的图表。

图表的配置通过 config.json 的 `chart_configs` 字典提供，键名对应占位符中的"图表名"。

示例:
- `{@图:收益率走势}` → 替换为 chart_configs["收益率走势"] 定义的图表
- `{@图|持仓分布}` → 替换为 chart_configs["持仓分布"] 定义的图表

## 表格占位符

语法: `{@表:表格名}` 或 `{@表|表格名}`

**注意: 表格替换功能尚未实现**（replacer.py 中为 TODO）。

## 占位符三种状态

| 状态 | 说明 | 结果 |
|------|------|------|
| 已匹配 | 数据中包含对应键 | 被替换为目标值 |
| 未匹配 | 数据中无对应键 | 保留原始占位符文本，如 `{未定义变量}` |
| 格式错误 | 不符合占位符语法 | 被当作普通文本，不处理 |

## add_placeholders.py 用法

将现有 PPT 中的固定文本替换为占位符，生成模板:

```bash
python scripts/add_placeholders.py input.pptx template.pptx map.json
```

map.json 格式:

```json
{
  "2024年度投资报告": "{标题}",
  "2024-12-31": "{日期}",
  "稳健增长组合": "{组合名}"
}
```

- 键: PPT 中的原始文本（必须精确匹配 run 内的文本）
- 值: 替换后的占位符

**限制**: 文本匹配基于 `run.text`，跨 run 的文本无法匹配。如果文字被拆分成多个 run（字体变化处），需要逐段匹配。

## 注意事项

- 占位符名称区分大小写
- 占位符可以跨越多个 run（字体样式切换点），解析器会正确识别
- 图表占位符的位置和大小决定了生成图表的位置和大小
- 图表占位符所在的形状（矩形/文本框）会被整个删除并替换