YAML 配置参考

手动编辑 template.yaml 文件的完整指南，涵盖布局、映射和逻辑。

本指南面向希望直接编辑 template.yaml 文件的高级用户和开发者。此文件作为配置文件的"唯一可信来源（Single Source of Truth）"，定义了 PDF 布局、数据映射和计算逻辑。

文件位置

配置文件位于工作区内的配置文件目录中：

Documents/PDFMailEngine_Workspace/Profiles/<YourProfileName>/template.yaml

默认工作区位于"文档"目录下的 PDFMailEngine_Workspace 文件夹。您可以在应用设置中更改工作区位置。

1. PAGE 配置（画布）

定义 PDF 画布的物理属性。

size：标准尺寸（A3、A4、A5、B4、B5、LETTER、LEGAL）。
orientation：PORTRAIT（纵向）或 LANDSCAPE（横向）。
margins：以毫米为单位的全局边距。

手动资源管理

在 YAML 文件中手动添加背景 PDF 时，应用不会自动将文件导入到配置文件文件夹中。

您必须手动将 .pdf 文件复制到配置文件目录。

设计器默认路径：assets/background/
建议：使用相对路径（例如 ./background.pdf 或 assets/background/bg.pdf）。

PAGE:
  size: "A4"
  orientation: "PORTRAIT"
  margins:
    top: 20
    bottom: 20
    left: 20
    right: 20
  background: "assets/background/stationery.pdf" # 可选的背景 PDF

2. FONTS（字体）

注册自定义 TrueType（.ttf）或 OpenType（.otf）字体。

手动资源管理

您必须手动将字体文件复制到配置文件目录。

设计器默认路径：assets/fonts/

FONTS:
  # 字体名称 : 相对路径
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING（数据绑定）

将 CSV/Excel 列标题映射到模板中使用的内部变量名。

语法：InternalKey: "CSV Column Header"

MAPPING:
  # 内部 : 外部
  customer_name: "Customer Name"
  invoice_no: "Invoice Number"
  date: "Issue Date"
  amount: "Total Amount"

4. CALCULATIONS（计算）

定义在数据导入过程中运行的自动计算。

语法一致性

变量使用 {{ }} 大括号。 为了与文本字段保持一致，建议即使在计算公式中也用 {{ }} 包裹变量名。

标准写法：{{ quantity }} * {{ price }}

scope：
- item：为每一行计算（例如 {{ quantity }} * {{ price }}）。
- group：为一组行计算（例如合计的 sum）。
expression：数学表达式。支持 math 函数如 floor()、ceil()、round()。

CALCULATIONS:
  # 行级计算（例如税额）
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # 使用 math 函数

  # 添加此项以展示 total_with_tax 的来源
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"

  # 组级计算（发票内所有行的合计）
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' 对值求和
    field: "total_with_tax"

5. LAYOUT（布局元素）

LAYOUT 列表定义 PDF 上的每个视觉元素。元素按顺序绘制（后面的元素绘制在上层）。

坐标系

坐标原点

通过设计器创建的模板使用 左上角 坐标系（Y=0 为页面顶部）。使用 PAGE 键手动编辑 YAML 时，默认坐标系为 左下角（Y=0 为页面底部）。

坐标系自动判定：使用 canvas 键（设计器格式）的模板为左上角原点，使用 PAGE 键的模板为左下角原点。

通用属性

大多数元素支持以下属性：

x, y：以毫米为单位的位置。
visible：控制元素是否渲染的条件表达式（详见下文）。
position：absolute（默认）或 relative。

`visible` 属性

visible 属性接受一个 Python 表达式，针对当前数据行进行求值。如果表达式求值为 False（或假值），则该元素隐藏。

可用的内置函数：int()、float()、str()、len()

# 仅在金额为正数时显示
- type: "text"
  value: "合计: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# 仅在字段不为空时显示
- type: "text"
  value: "备注: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# 组合多个条件
- type: "text"
  value: "已应用折扣"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

文本（Text）

显示静态文本或使用 Jinja2 语法 {{ key }} 的动态变量。

- type: "text"
  value: "Invoice #{{ invoice_no }}" # 动态
  x: 20
  y: 250
  font_family: "Helvetica"
  font_size: 12
  font_weight: "bold"
  align: "LEFT" # LEFT, CENTER, RIGHT
  color: "#000000"
  opacity: 1.0

图像（Image）

嵌入图像文件。

手动资源管理

您必须手动将图像文件复制到配置文件目录。

设计器默认路径：assets/images/

- type: "image"
  path: "assets/images/logo.png"
  x: 150
  y: 260
  width: 40
  height: 20

分组表格（Group Table - 动态）

渲染遍历数据行（明细/行项目）的动态表格。

- type: "group_table"
  x: 20
  y: 180
  # 全局样式
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # 斑马纹

  columns:
    - header: "Item"
      key: "item_name"
      width: 60
      align: "LEFT"

    - header: "Price"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # 带逗号格式化

静态表格（Static Table - 固定）

渲染手动定义行的固定网格。适用于页脚、银行账户信息或签名区域。

- type: "static_table"
  x: 20
  y: 50
  width: 170 # 可选。未指定时从列宽之和推断

  columns:
    - width: 30
      header: "Label"
    - width: 140
      header: "Value"

  # 手动定义的行
  rows:
    - ["Bank Name", "Mizuho Bank"]
    - ["Account No", "{{ account_number }}"] # 可使用变量
    - ["Note", "Please pay within 30 days"]

条码（Barcode）

生成一维条码。

支持的类型：CODE128、JAN（EAN13 混合）、EAN13、EAN8、CODE39、UPCA、NW-7（Codabar）、ITF。

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # 最大宽度（需要时自动缩小）
  height: 10       # 总高度

  barcode_type: "CODE128"
  bar_width: 1.0   # 条的粗细
  bar_height: 10   # 条的高度

  # 人眼可读文本
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

二维码（QR Code）

生成二维码。

纠错级别：L（7%）、M（15%）、Q（25%）、H（30%）。

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # 尺寸（宽高比固定）

  qr_error_level: "M"
  qr_quiet_zone: true   # 包含白色边距

  color: "#000000"      # 前景色
  back_color: "#ffffff" # 背景色
  opacity: 1.0

图形（Shapes - Rect / Line）

仅限 YAML 手动编辑

图形元素（rect 和 line）无法通过设计器 UI 添加。仅在直接编辑 YAML 文件时可用。

矩形（Rect）属性：

x, y：以毫米为单位的位置。
width, height：以毫米为单位的尺寸。
stroke_color：边框颜色（十六进制，例如 "#000000"）。
fill_color：填充颜色（十六进制，例如 "#f0f0f0"）。省略则不填充。
stroke_width：边框粗细（磅，默认：1）。
opacity：不透明度，0.0（透明）到 1.0（不透明）。

线条（Line）属性： 线条以 height: 0（水平线）或 width: 0（垂直线）的矩形方式绘制。

x, y：以毫米为单位的起始位置。
width：水平线的长度。
height：垂直线的长度。水平线设为 0。
stroke_color：线条颜色（十六进制）。
stroke_width：线条粗细（磅）。

# 带边框和填充的矩形
- type: "rect"
  x: 10
  y: 100
  width: 190
  height: 50
  stroke_color: "#000000"
  fill_color: "#f0f0f0"
  stroke_width: 1

# 水平线
- type: "line"
  x: 10
  y: 200
  width: 190
  height: 0
  stroke_width: 2
  stroke_color: "#000000"

YAML 配置参考

文件位置

1. PAGE 配置（画布）

手动资源管理

2. FONTS（字体）

手动资源管理

3. MAPPING（数据绑定）

4. CALCULATIONS（计算）

语法一致性

5. LAYOUT（布局元素）

坐标系

坐标原点

通用属性

visible 属性

文本（Text）

图像（Image）

手动资源管理

分组表格（Group Table - 动态）

静态表格（Static Table - 固定）

条码（Barcode）

二维码（QR Code）

图形（Shapes - Rect / Line）

仅限 YAML 手动编辑

`visible` 属性