Modifications

範本是一份帶有命名圖層的設計。modification 會在單次繪製中變更其中一個圖層，因此同一個範本可以為每項商品、每位客戶或每則貼文產生不同的檔案。範本本身不會改變，沒有 modification 的圖層會維持你在編輯器中設定的值。

每個生成檔案的請求都會一併傳送 modification：

{
  "apiKey": "YOUR_API_KEY",
  "templateId": "tpl_xxx",
  "modifications": [
    { "name": "headline", "text": "Summer sale" },
    { "name": "photo", "src": "https://example.com/shoes.png" },
    { "name": "badge", "visible": false }
  ]
}

為圖層命名

name 必須與範本中的圖層名稱相符。比對時必須完全相符，所以 Headline 和 headline 是兩個不同的名稱。

若要重新命名圖層，請在編輯器的圖層面板中連按兩下該圖層。若要透過 API 列出範本的圖層名稱，請呼叫範本清單，並加上 includeLayers=true。

當某個值沒有變更時，有兩條規則可以幫上忙：

• 如果沒有任何圖層使用這個名稱，Bannerify 會忽略該 modification，也不會回傳錯誤。請先檢查拼字。
• 如果有多個圖層使用相同的名稱，它們全都會套用同一個 modification。

欄位

欄位	型別	變更的內容
name	string	要變更的圖層。必填
text	string	文字圖層或連結圖層的文字、提醒的內文，或簽名的簽署人姓名
color	string	文字圖層或連結圖層的文字顏色，例如 #ff5733
src	string	圖片圖層的圖片網址
href	string	連結圖層的網址，在 PDF 中點選時會開啟
visible	boolean	顯示或隱藏任何圖層
qrcode	string	QR 碼圖層的內容
barcode	string	條碼圖層的值
star	number	星星圖層的評分。值為 0 時會被忽略
rows	array	表格、圖表或鍵值圖層的資料
columns	array	表格圖層的欄
title	string	提醒的標題，或簽名的職稱
date	string	簽名的日期

Bannerify 會忽略不適用於該圖層的欄位。例如，在文字圖層上設定 src 不會有任何作用，而 color 只會變更文字圖層。它也會忽略自己不認得的欄位。

每種圖層會讀取的欄位

圖層	欄位
文字	text, color, visible
連結	text, color, href, visible
圖片	src, visible
QR 碼	qrcode, visible
條碼	barcode, visible
星星	star, visible
表格	rows, columns, visible
圖表	rows, visible
鍵值	rows, visible
簽名	text, title, date, visible
提醒	title, text, visible
圖示、框架、線條	visible

modification 無法變更畫布、圖層的位置或大小，或填色。這些請在編輯器中變更。

文字

新的文字會取代圖層的整段文字。換行會開始新的段落。圖層會保留自己的樣式，例如字型和大小，但文字內部的格式（例如單一個粗體字）會消失。

圖片

src 必須是 PNG、JPEG、WebP 或 SVG 檔案的公開網址。Bannerify 會在繪製時下載該檔案。下載最多等待 5 秒，並重試兩次。如果下載失敗，或檔案是其他類型，請求會以 FETCH_IMAGE_ERROR 失敗。

表格

表格接受 columns 和 rows。每一列是以欄名為鍵的物件。儲存格可以放字串、數字、布林值或 null。

{
  "name": "line-items",
  "columns": ["Item", "Qty", "Total"],
  "rows": [
    { "Item": "Automate plan", "Qty": 1, "Total": "$29.00" },
    { "Item": "Extra seat", "Qty": 2, "Total": "$10.00" }
  ]
}

欄可以是一個名稱，或是含有下列欄位的物件：

欄位	型別	說明
key	string	各列用於這一欄的鍵
header	string	標題儲存格中的文字
align	left、center 或 right	儲存格的對齊方式
width	string 或 number	欄寬

如果你傳送 rows 但沒有 columns，表格會保留範本中的欄，且每一列都需要有這些欄的鍵。

圖表

圖表接受 rows。單一資料系列請傳送資料點，多個系列則傳送各系列的資料。

{
  "name": "revenue",
  "rows": [
    { "label": "Jan", "value": 22 },
    { "label": "Feb", "value": 31, "color": "#0d9373" }
  ]
}

{
  "name": "revenue",
  "rows": [
    { "name": "2025", "data": [{ "label": "Jan", "value": 22 }, { "label": "Feb", "value": 31 }] },
    { "name": "2026", "data": [{ "label": "Jan", "value": 27 }, { "label": "Feb", "value": 35 }] }
  ]
}

資料點有 label、數值的 value，以及選填的 color。資料系列有 name、它的 data 資料點，以及選填的 color。

鍵值

鍵值圖層接受 rows，每一行對應一個項目。value 可以是字串或數字，Bannerify 會以文字顯示。

{
  "name": "order-details",
  "rows": [
    { "key": "Order", "value": "1042" },
    { "key": "Total", "value": 29 }
  ]
}

接受的格式

modifications 欄位接受四種形式，全都會產生相同的檔案。

形式	適用情境
modification 陣列	SDK 傳送的格式。本頁使用這種格式
每個圖層一個鍵的物件	免寫程式工具和快速請求
任一種形式的 JSON 字串	查詢字串，例如簽署網址
null 或空字串	沒有 modification

在物件形式中，鍵代表圖層。字串或數字的值會設定 text，物件的值則保留它自己的欄位。

{
  "modifications": {
    "headline": "Summer sale",
    "photo": { "src": "https://example.com/shoes.png" },
    "badge": { "visible": false }
  }
}

布林值需要使用物件。"badge": false 會把圖層的文字設為 false，而 "badge": { "visible": false } 才會隱藏它。

檢查請求

無效的 modification 會回傳 BAD_REQUEST。訊息會指出欄位的路徑，例如 modifications[0].text。

Modification 結構描述列出了每個欄位及其型別。