YAML 設定參考

手動編輯 template.yaml 檔案的完整指南，涵蓋版面配置、對應和邏輯。

本指南適用於希望直接編輯 template.yaml 檔案的進階使用者和開發人員。此檔案作為您設定檔的「唯一真實來源」，定義 PDF 版面配置、資料對應和計算邏輯。

檔案位置

設定檔位於工作區中的設定檔目錄：

Documents/PDFMailEngine_Workspace/Profiles/<您的設定檔名稱>/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 欄位標題"

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)" # 使用數學函式

  # 顯示 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: "Total: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# 僅在欄位不為空時顯示
- type: "text"
  value: "Note: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# 組合多個條件
- type: "text"
  value: "Discount Applied"
  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

生成 1D 條碼。

支援的類型：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

生成 2D 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` 屬性