圖層類型 | Bannerify Docs

範本是一塊畫布，上面放著圖層。每個圖層都有類型，類型決定了請求可以變更什麼。為圖層命名之後，請求就能用名稱來變更它。所有欄位請見 Modifications。

新增圖層

畫布頂端的工具列有四個按鈕：Insert（+）、Frame（F）、Text（T）和 Shapes。Frame、Text、Insert 中的 Stack 和 Grid，以及 Shapes 中的 Rectangle（R）、Oval（O）、Line 和 Path（P）會啟動工具，你可以在畫布上點選或拖曳來放置圖層。在框架內繪製的圖層會放在該框架裡面。Insert 中的其他圖層類型，以及 Shapes 中的 Star，會出現在畫布的左上角附近，請把它們拖曳到想要的位置。

新圖層會以其類型作為名稱，例如 Text，同一類型的第二個圖層會加上編號，例如 Text 1。呼叫 API 之前，請先重新命名。做法請見為圖層命名。

項目	圖層	繪製的內容
Text	文字	一行或一段文字
Image	圖片	PNG、JPEG、WebP 或 SVG 圖片
Frame	框架	可設定填色、邊框或陰影的方塊
Stack	框架	把圖層排成一列或一欄的框架
Grid	框架	把圖層排成多個欄的框架
Rectangle	框架	200 × 200 像素的灰色框架
Oval	框架	200 × 200 像素的圓形灰色框架
Line	路徑	從按下的位置到放開位置的直線
Path	路徑	通過你點選的各點的直線或曲線
QR Code	QR 碼	QR 碼
Barcode	條碼	Code 128 條碼
Icon	圖示	向量圖示
Star	星級評分	用來表示評分的一排星星
Key Value	鍵值	成對的標籤與值
Signature	簽名	簽署人姓名、職稱和日期
Alert	提醒	含標題和內文的提示方塊
Link	連結	在 PDF 中點選後會開啟網址的文字
Chart	圖表	長條圖、折線圖、區域圖、圓餅圖或環圈圖
Table	表格	由欄和列組成的表格

選取圖層後，Design 面板會開啟它的設定。每個圖層都有 Position & Size，其他區段則依類型而異。

文字

選擇 Text，在畫布上點選或拖曳，然後輸入文字。連按兩下文字圖層即可編輯。Design 面板可以設定文字的字型、字重、大小、間距、對齊方式、大小寫和顏色。

請求可以變更 text 和 color。新的文字會取代圖層的整段文字，舊文字內部的格式（例如單一個粗體字）不會保留下來。

{ "name": "headline", "text": "Summer sale", "color": "#e11d48" }

字型清單來自 Google Fonts，字型選擇器有搜尋框。你無法上傳字型，Google Fonts 沒有提供的字型會以 Arial 繪製。

請把文字圖層的方塊拉得夠高，足以容納你預期最長的值。繪製出來的圖片不會在方塊底部截斷文字，所以太長的值可能會蓋到下方的圖層。編輯器的畫布會隱藏那一部分，因此請在預覽中檢查較長的值，因為預覽繪製文字的方式與 API 相同。

Text fit 區段中的 Max lines 最多只會顯示該行數。同一區段的 Fit 會依方塊縮放文字，可選擇 Off、Grow to fill the box、Grow up to 150%、Shrink to fit 和 Scale each line。Shrink to fit 會縮小字級，直到整段文字都放得進方塊。Scale each line 會分別調整每一行的大小，所以對最後一行或只有一行的文字沒有效果。

圖片

選取圖層，使用 Content 區段中的 Image source。Library 可選擇已上傳的圖片或圖庫圖片，URL 則接受圖片網址。Appearance 區段中的 Fit 提供 Cover、Contain 和 Fill。

選取的照片圖層，Design 面板中有 Image source 和 Fit — 圖片圖層和它的 Design 面板。

若要裁切圖片，請選取它並點選 Crop，或連按兩下圖片。

請求可以變更 src，它會取代同一個方塊中的圖片。網址必須是 PNG、JPEG、WebP 或 SVG 檔案的公開網址。Bannerify 如何下載圖片，請見 Modifications。

框架

框架是一個方塊。選擇 Frame，並在畫布上拖曳即可繪製。在 Fill 區段中設定顏色。Stroke 和 Shadow 區段可以加上邊框和陰影，Appearance 中的 Radius 可以讓邊角變圓。你可以把框架當作其他圖層後方的背景或卡片。

框架可以容納其他圖層。Rectangle 和 Oval 也是框架。在框架內繪製圖層，或把圖層拖曳到框架上，就能把它放進去：圖層之後會隨著框架移動，框架也會隱藏圖層超出方塊的部分。把圖層拖出框架，就能取出。Layers 面板會在框架下方顯示它所含的圖層。

堆疊與格線

設定了版面配置的框架，會依照 Layers 面板的順序，幫你排列圖層。請在 Insert 中選擇 Stack 或 Grid，或是在任何框架的 Layout 區段中點選 +。新的堆疊一開始有兩個框架，新的格線則有四個。

選取框架時，你從 Insert 或 Shapes 新增的圖層會放進該框架。比框架還大的圖層會縮小以符合框架。

Stack 會把圖層排成一列或一欄。Direction 設定方向，Distribute 沿著該方向分配圖層，Align 讓圖層在垂直方向上對齊，Wrap 則把放不下的圖層移到新的一行。
Grid 會把圖層逐列排進寬度相等的 Columns，並讓每個圖層與欄同寬。Rows 會平分框架的高度，當某一列中有較高的圖層時，該列就會變高。超過最後一列的圖層會新增列，這些列也會平分高度。
Gap 設定圖層之間的間距（格線有欄間距和列間距各一個），Padding 則設定框架邊緣內側的空間。

在堆疊或格線中拖曳圖層，可以把它移到順序中的其他位置。點選 Layout 區段中的 − 可以移除版面配置：圖層會停留在原來的位置。

請求只能變更 visible。

QR 碼

在 Insert 中選擇 QR Code，並在 Content 中輸入文字或網址。請求可以變更 qrcode，它會取代該內容。

條碼

在 Insert 中選擇 Barcode，並在 Content 中輸入值。Bannerify 會繪製 Code 128 條碼，並在條碼下方印出它的值。請求可以變更 barcode。

圖示

選擇 Icon，在 Set 中選擇圖示集，並在 Icon 中選擇名稱。變更圖示集時，如果新的圖示集有相同的圖示，圖層會保留該圖示。

圖層會把圖示儲存為 set:name，例如 lucide:house 或 ph-fill:star。沒有圖示集的名稱，例如 CheckCircle，是 Iconoir 的圖示。每個圖示集都可免費商用。

圖示集	ID	授權
Iconoir	`iconoir`	MIT
Lucide	`lucide`	ISC
Phosphor	`ph`, `ph-fill`	MIT
Heroicons	`heroicons`, `heroicons-solid`	MIT
Feather	`feather`	MIT
Tabler	`tabler`	MIT
Material Symbols	`material-symbols`	Apache 2.0
Bootstrap Icons	`bi`	MIT
Mage	`mage`	Apache 2.0
Basil（Craftwork 製作）	`basil`	CC BY 4.0
Flowbite	`flowbite`	MIT
Meteor	`meteor-icons`	MIT

請求只能變更 visible。

圖示圖層。

路徑

使用 Path 時，點選即可新增每個點。點選第一個點可以封閉路徑，連按兩下或按 Enter 或 Escape 則結束路徑。按住 Shift 可以讓線段維持在 45° 的倍數。Line 會繪製只有兩個點的路徑：從起點拖曳到終點即可。

選取路徑後，可以移動它的點，也可以拖曳兩點之間的小圓點來新增一個點。Points 可以讓線段變成 Straight（直線）或 Curved（曲線），Ends 可封閉路徑，Stroke 和 Fill 則設定顏色和線條寬度。

星級評分

選擇 Star，並在 Rating 區段中設定星星的數量。請求可以變更 star，圖層會為每一個整數畫出一顆星。值為 0 時會被忽略。

排成一列的四顆星，Design 面板中有 Rating — 評分為 4 的星星圖層。

鍵值

選擇 Key Value，可以印出成對的標籤與值，例如發票號碼和到期日。在 Data 中編輯這些配對，並用 Layout 設定方向、大小、標籤寬度和分隔線。

發票號碼、開立日期、到期日和客戶，以標籤與值的配對呈現 — 含有發票明細的鍵值圖層。

請求可以變更 rows，每一行對應一個項目，順序與畫面上相同。格式請見鍵值。

簽名

選擇 Signature，可以印出簽署人區塊。在 Signer 區段中，設定 Layout（Single、Double 或 Inline）、Label、Name、Title 和 Date。

含標籤、姓名、職稱和日期的簽署人區塊，Design 面板中有 Signer 區段 — 簽名圖層。

請求用 text 變更 Name，用 title 變更 Title，用 date 變更 Date。姓名使用 text，是因為 name 已經用來識別圖層。

{ "name": "signature", "text": "An Nguyen", "title": "Director", "date": "2026-02-02" }

提醒

選擇 Alert，可以印出提示方塊，例如付款期限或出貨通知。在 Content 中設定 Variant（Info、Success、Warning 或 Error）、Title 和 Description。你也可以顯示或隱藏圖示和邊框。

關於付款條款的警告提示方塊，Design 面板中有 Content — Warning 樣式的提醒圖層。

請求用 title 變更標題，並用 text 填入 Description。

{ "name": "notice", "title": "Payment terms", "text": "Pay before 31 Jan 2026." }

連結

在 Insert 中選擇 Link，可以新增一段文字，點選後會開啟網頁、電子郵件或電話號碼。請在 PDF link 區段的 URL 中設定位址。它接受 https://、http://、mailto: 或 tel: 網址。Design 面板的其餘部分與文字圖層相同。

連結只在 PDF 中有效：在 PDF 中點選文字就會開啟網址。PNG、JPEG 或 WebP 圖片會繪製相同的文字，但沒有連結。

請求用 text 變更文字，用 color 變更顏色，用 href 變更網址。

{ "name": "pay", "text": "Pay invoice INV-1048", "href": "https://example.com/pay/INV-1048" }

圖表

在 Insert 中選擇 Chart，再到 Data 中編輯資料點。在 Chart 區段中，選擇 Variant（Bar、Horizontal bar、Line、Area、Pie 或 Donut）和 Legend，並設定標題和座標軸標籤。Series colors 可以設定各個資料系列的顏色。

每月訂單數的長條圖，Design 面板中有 Data 和 Chart — 長條圖圖層。

請求可以變更 rows。單一資料系列請傳送資料點，多個系列則傳送各系列的資料。兩種格式請見圖表。

表格

在 Insert 中選擇 Table，再到 Data 中編輯預設的欄和列。在 Table 區段中，選擇 Variant（Line、Grid、Minimal、Striped、Compact、Bordered 或 Primary header）和 Row size（Default 或 Compact）。Stripe rows 和 No wrap 是開關。

請求可以變更 columns 和 rows。格式請見表格。

顯示或隱藏圖層

visible 適用於每一種圖層類型。在 Layers 清單中點選圖層的眼睛圖示即可隱藏它。隱藏的圖層不會出現在繪製的檔案中，直到請求設定 "visible": true；而設定 "visible": false 的請求，則會隱藏正在顯示的圖層。

{ "name": "sale-badge", "visible": true }

請求中沒有列出的欄位，會維持範本中的值。