# 报告模板开发指南 | Template Development Guide

## 1. 概述

XP.ReportEngine 使用 JSON 格式定义报告模板。模板描述了 PDF 报告的页面结构、元素布局、数据绑定和样式定义。

模板文件存放在 `XP.ReportEngine/Templates/` 目录下，通过 `App.config` 中的 `Report:TemplatePath` 配置项指定使用哪个模板。

## 2. 新增模板步骤

### 2.1 创建模板文件

1. 在 `Templates/` 目录下创建新的 JSON 文件，如 `CustomReportTemplate.json`
2. 在 `.csproj` 中确认模板文件会被复制到输出目录（已有通配规则）：
   ```xml
   <Content Include="Templates\*.json">
     <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
   </Content>
   ```
3. 修改 `App.config` 中的 `Report:TemplatePath` 指向新模板：
   ```xml
   <add key="Report:TemplatePath" value="Templates\CustomReportTemplate.json" />
   ```

### 2.2 模板验证规则

模板加载后会自动验证，必须满足以下条件：
- 包含 `document` 顶层字段（页面设置）
- 包含 `pages` 顶层字段（至少一个页面定义）
- 包含 `styles` 顶层字段（样式字典）

验证失败时报告生成会返回错误，不会生成 PDF。

## 3. 模板 JSON 结构

```json
{
  "document": { ... },   // 必需：文档级设置（页面尺寸、边距、页眉页脚）
  "pages": [ ... ],      // 必需：页面定义数组
  "styles": { ... }      // 必需：样式定义字典
}
```

## 4. document 配置

```json
{
  "document": {
    "pageSize": "A4",
    "orientation": "Portrait",
    "margins": { "top": 40, "bottom": 20, "left": 20, "right": 20 },
    "header": {
      "enabled": true,
      "left": ["标题文本", "第二行文本"],
      "right": ["右侧文本"],
      "rightImageKey": "companyLogo",
      "leftImageKey": "softwareLogo",
      "fontSize": 7,
      "color": "#666666",
      "showLine": true
    },
    "footer": {
      "enabled": true,
      "left": ["公司名称"],
      "right": ["{currentPage} / {totalPages}"],
      "fontSize": 8,
      "color": "#666666",
      "showLine": true
    }
  }
}
```

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `pageSize` | string | `"A4"` | 页面尺寸 |
| `orientation` | string | `"Portrait"` | 方向：Portrait / Landscape |
| `margins` | object | `{top:20, bottom:20, left:20, right:20}` | 边距（mm） |
| `header` | object | null | 页眉配置（首页不显示） |
| `footer` | object | null | 页脚配置（首页不显示） |

### 页眉/页脚字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `enabled` | bool | 是否启用 |
| `left` | string[] | 左侧文本行（支持 `${}` 绑定） |
| `right` | string[] | 右侧文本行（支持 `${}` 绑定） |
| `leftImageKey` | string | 左侧图像的 dataKey |
| `rightImageKey` | string | 右侧图像的 dataKey |
| `fontSize` | float | 字体大小 |
| `color` | string | 字体颜色（十六进制） |
| `showLine` | bool | 是否显示分隔线 |

页脚特殊占位符：
- `{currentPage}` — 当前页码
- `{totalPages}` — 总页数

## 5. pages 页面定义

```json
{
  "pages": [
    {
      "type": "homepage",
      "elements": [ ... ]
    },
    {
      "type": "customPage",
      "elements": [ ... ]
    }
  ]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | string | 页面类型标识（`homepage` 类型不显示页眉页脚） |
| `elements` | array | 页面内的元素列表 |

### 内置页面类型

| 类型 | 说明 | 特殊行为 |
|------|------|---------|
| `homepage` | 首页 | 不显示页眉页脚 |
| `summary` | 汇总页 | 无 |
| `metricData` | 距离测量页 | 无 |
| `bgaInspection` | BGA 检测页 | 无 |
| `voidInspection` | 空隙检测页 | 无 |
| `viaFillInspection` | 通孔填锡页 | 无 |

你可以自定义任意 `type` 名称，只有 `homepage` 有特殊行为（不显示页眉页脚）。

## 6. 元素类型

### 6.1 text — 文本元素

```json
{
  "type": "text",
  "content": "${loc:Report_Title}",
  "style": "heading",
  "positioning": "flow",
  "align": "center",
  "colorRules": { "Pass": "#008000", "Fail": "#FF0000" }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `content` | string | 文本内容，支持 `${}` 绑定表达式 |
| `style` | string | 引用 `styles` 中定义的样式名 |
| `align` | string | 对齐：left / center / right |
| `colorRules` | object | 条件颜色规则（内容包含关键词时变色） |

### 6.2 image — 图像元素

```json
{
  "type": "image",
  "dataKey": "workpieceImage",
  "size": [160, 110],
  "border": true,
  "align": "center",
  "style": "imageDefault",
  "positioning": "flow"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `dataKey` | string | 图像数据键（对应 `ReportContext.Images` 中的键） |
| `size` | float[2] | [宽, 高]（mm），图像会等比缩放适应 |
| `border` | bool | 是否显示边框 |
| `align` | string | 对齐：left / center / right |

图像缺失时会渲染灰色占位矩形，不会中断报告生成。

### 6.3 table — 表格元素

```json
{
  "type": "table",
  "dataKey": "bgaBallsTable",
  "positioning": "flow",
  "size": [170, 0],
  "style": "tableDefault",
  "columns": [
    { "header": "序号", "field": "index", "width": 25, "align": "center" },
    { "header": "气泡率", "field": "voidRate", "width": 40, "align": "center" },
    { "header": "面积", "field": "area", "width": 40, "align": "center" },
    {
      "header": "分类",
      "field": "classification",
      "width": 35,
      "align": "center",
      "colorRules": { "Pass": "#008000", "Fail": "#FF0000" }
    }
  ]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `dataKey` | string | 表格数据键（对应 `ReportContext.Properties` 中的 `List<Dictionary<string, object>>` 数据） |
| `size` | float[2] | [宽, 高]（mm），高度为 0 表示自动 |
| `columns` | array | 列定义数组 |

#### 列定义（ColumnDefinition）

| 字段 | 类型 | 说明 |
|------|------|------|
| `header` | string | 表头文本（支持 `${}` 绑定） |
| `field` | string | 数据字段名（对应行数据字典中的键） |
| `width` | float | 列宽（mm） |
| `align` | string | 对齐：left / center / right |
| `colorRules` | object | 条件颜色规则（单元格值匹配时变色） |

### 6.4 row — 水平布局容器

```json
{
  "type": "row",
  "size": [170, 100],
  "widths": [6, 4],
  "positioning": "flow",
  "children": [
    {
      "type": "column", "align": "left",
      "children": [
        { "type": "image", "dataKey": "myImage", "size": [110, 90] }
      ]
    },
    {
      "type": "column", "align": "left",
      "children": [
        { "type": "text", "content": "文本内容", "style": "body" }
      ]
    }
  ]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `size` | float[2] | [总宽, 总高]（mm） |
| `widths` | float[] | 列宽比例数组（如 `[6, 4]` 表示 60%:40%） |
| `children` | array | 子列元素（`type: "column"`） |

### 6.5 spacer — 间距元素

```json
{ "type": "spacer", "size": [170, 10], "positioning": "flow" }
```

用于在元素之间添加垂直间距。`size[1]` 为间距高度（mm）。

### 6.6 divider — 分隔线

```json
{ "type": "divider", "positioning": "flow" }
```

渲染一条水平分隔线。

### 6.7 pagebreak — 强制分页

```json
{ "type": "pagebreak" }
```

在当前位置强制插入分页符。

## 7. 样式定义

```json
{
  "styles": {
    "heading": {
      "font": "auto",
      "size": 16,
      "bold": true,
      "italic": false,
      "color": "#333333",
      "align": "left",
      "marginTop": 0,
      "marginBottom": 3,
      "paddingLeft": 0,
      "lineHeight": 0,
      "backgroundColor": ""
    }
  }
}
```

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `font` | string | `"auto"` | 字体（`auto` 根据语言自动选择） |
| `size` | float | 12 | 字体大小（pt） |
| `bold` | bool | false | 粗体 |
| `italic` | bool | false | 斜体 |
| `color` | string | `"#000000"` | 字体颜色（十六进制） |
| `align` | string | `"left"` | 对齐：left / center / right |
| `backgroundColor` | string | — | 背景色（十六进制） |
| `marginTop` | float | 0 | 上边距（mm） |
| `marginBottom` | float | 0 | 下边距（mm） |
| `paddingLeft` | float | 0 | 左缩进（mm） |
| `lineHeight` | float | 0 | 行高倍数（0 = 默认） |

元素引用未定义的样式名时，会使用默认样式（12pt、黑色、左对齐），不会报错。

## 8. 数据绑定表达式

模板中的 `content`、`header` 等文本字段支持 `${}` 绑定表达式：

| 语法 | 说明 | 示例 |
|------|------|------|
| `${key}` | 从 Properties 中取值 | `${sampleName}` |
| `${metadata.field}` | 从 Metadata 中取值 | `${metadata.reportId}` |
| `${loc:Key}` | 多语言资源键 | `${loc:Report_Title}` |
| `${formatDate(value)}` | 格式化日期 | `${formatDate(metadata.inspectionDate)}` |
| `${formatNumber(value, decimals)}` | 格式化数字 | `${formatNumber(totalArea, 2)}` |
| `${formatPercent(value)}` | 格式化百分比 | `${formatPercent(voidRate)}` |

### 数据来源

绑定表达式从 `ReportContext` 中查找数据：
- `Properties` 字典 — 扁平化的键值对（由 `ProcessorDataAdapter` 从处理器输出转换而来）
- `Metadata` — 报告元数据对象
- `Images` 字典 — 图像数据（通过 `dataKey` 引用）

### ProcessorDataAdapter 输出的键名

| 处理器类型 | Properties 中的键 | Images 中的键 | 表格 dataKey |
|-----------|------------------|--------------|-------------|
| LineMeasurementProcessor | measurementType, point1, point2, pixelDistance, actualDistance, unit, angle | lineMeasurementImage | — |
| BgaVoidRateProcessor | bgaCount, voidRate, fillRate, totalBgaArea, totalVoidArea, voidLimit, classification | bgaInspectionImage | bgaBallsTable |
| VoidMeasurementProcessor | roiArea, totalVoidArea, voidRate, voidLimit, voidCount, maxVoidArea, classification | voidInspectionImage | voidsTable |
| FillRateProcessor | fillRate, voidRate, fullDistance, fillDistance, thtLimit, classification, e1-e4 | viaFillImage | — |

### ReportService 自动注入的键

| 键 | 来源 | 说明 |
|----|------|------|
| `CompanyName` | ReportConfig | 公司名称 |
| `SoftwareName` | ReportConfig | 软件名称 |
| `companyLogo` | ReportConfig.CompanyLogo | 公司 Logo（Images） |
| `softwareLogo` | ReportConfig.SoftwareLogo | 软件 Logo（Images） |
| `summaryTable` | 自动生成 | 首页汇总表数据 |

## 9. 定位方式

| 值 | 说明 |
|----|------|
| `"flow"` | 流式布局，元素按顺序从上到下排列（推荐） |
| `"absolute"` | 绝对定位，使用 `position` 坐标（不推荐，兼容性差） |

建议所有元素使用 `"positioning": "flow"`。

## 10. 完整模板示例（最小化）

```json
{
  "document": {
    "pageSize": "A4",
    "orientation": "Portrait",
    "margins": { "top": 20, "bottom": 20, "left": 20, "right": 20 }
  },
  "pages": [
    {
      "type": "homepage",
      "elements": [
        { "type": "text", "content": "检测报告", "style": "title", "positioning": "flow" },
        { "type": "text", "content": "报告编号：${metadata.reportId}", "style": "body", "positioning": "flow" },
        { "type": "text", "content": "检测日期：${formatDate(metadata.inspectionDate)}", "style": "body", "positioning": "flow" }
      ]
    },
    {
      "type": "dataPage",
      "elements": [
        { "type": "text", "content": "检测数据", "style": "heading", "positioning": "flow" },
        { "type": "image", "dataKey": "inspectionImage", "size": [150, 100], "positioning": "flow" }
      ]
    }
  ],
  "styles": {
    "title": { "size": 24, "bold": true, "align": "center" },
    "heading": { "size": 16, "bold": true },
    "body": { "size": 12 }
  }
}
```

## 11. 注意事项

1. **尺寸单位**：所有尺寸（size、margins、width）单位为 **mm**（毫米）
2. **颜色格式**：使用十六进制格式 `#RRGGBB`（如 `#FF0000` 为红色）
3. **表格自动跨页**：当表格数据行超出当前页面剩余空间时，排版引擎会自动分页
4. **图像缺失容错**：图像 dataKey 对应的数据不存在时，渲染占位矩形，不中断生成
5. **样式缺失容错**：引用未定义的样式名时使用默认样式，不中断生成
6. **绑定表达式缺失**：`${}` 表达式对应的数据不存在时，替换为空字符串
7. **首页特殊处理**：`type: "homepage"` 的页面不显示页眉页脚
8. **JSON 编码**：模板文件必须使用 **UTF-8** 编码保存