透過 NextPDF Connect 控制字型與文字樣式

概覽

你可以在文字區塊之間切換字型，建立多種樣式的文件。set_font 會設定目前使用的字型、樣式與尺寸。在你變更之前，這個狀態會持續套用到後續每一次 add_text。這裡會用到的工具是 create_pdf、set_font、add_text 與 output_pdf — 全部都屬於 Core。文字狀態參數會決定字符的算繪方式（ISO 32000-2 §9）。

安裝

composer require nextpdf/server

請綁定一個傳輸。有三種內建字型家族可用，不需要額外的字型檔：helvetica、times 與 courier。

概念總覽

set_font 接受 family、style（""、"B"、"I"、"BI"、"U"）與 size。你設定的字型會套用到後續每一次 add_text 呼叫，直到下一次 set_font 為止；它不會自動重設。當 add_text 帶有 font_size 時，該值會覆寫目前使用的尺寸，僅限於那一次呼叫；下一次呼叫會回到 set_font 的尺寸。文字是由顯示文字的運算子依內容串流順序輸出（ISO 32000-2 §9.4）。add_text 沒有顏色參數。文字顏色來自文件圖形狀態的繪墨顏色。

API 介面

工具	角色	風險層級
`create_pdf`	開啟工作階段	安全
`set_font`	設定目前使用的 typeface/style/size	注意
`add_text`	以使用中的字型寫入文字	注意
`output_pdf`	算繪並回傳 PDF	需要核准/審查（base64）

工具型錄是正式的型錄依據。你可以使用的工具取決於已安裝的層級。

程式碼範例 — 快速開始

create_pdf（A4 直向）→ document_id。
set_font（helvetica、B、24），接著 add_text（標題，置中）。
set_font（helvetica、""、12），接著 add_text（左右對齊的內文）。
set_font（courier、I、10），接著 add_text（一段程式碼片段）。
output_pdf。

程式碼範例 — 生產環境

在每個排版要求明確的區塊之前，請明確設定字型。切勿在不同邏輯區段之間依賴繼承下來的狀態。每次呼叫的 font_size 覆寫只應用於一次性強調，因為它不會持續保留。請逐段建構，並驗證每一次 add_text 都會回傳一個 position。

邊界情況與陷阱

未知的字型家族。 helvetica/times/courier 以外的任何值（例如 arial）都會被拒絕。
空的字型家族。 family 必須是非空字串。
無效的樣式。 請使用大寫代碼。 "bold" 會被拒絕。
非正數的尺寸。 size 必須是正數。
每次呼叫的尺寸是暫時的。 它不會改變 set_font 狀態。

效能

使用內建字型造成的檔案增量很小，輸出僅有幾 KB。此設定檔為 structural。

安全性注意事項

base64 模式不會產生任何檔案系統副作用。內建字型不會匯入任何外部字型檔，因此本範例沒有字型剖析攻擊面。

符合性

陳述	規格	條款	reference_id
文字由顯示文字的運算子依串流順序顯示。	ISO 32000-2	§9.4
文字狀態參數決定字符的算繪方式。	ISO 32000-2	§9

商業情境

不適用 — 所有工具都屬於 Core。

傳輸可用性

傳輸	可用	備註
MCP（stdio）	是	每個工具一次 `tools/call`。
REST	是	每個工具對應一個操作。
gRPC	是	每個工具各一次一元呼叫。

HITL 風險層級

create_pdf 為安全；set_font/add_text 為注意；output_pdf 為需要核准，在 base64 模式下會降級為審查（HITL 風險層級）。

確認閘門 JSON 封包

Base64 輸出：

{ "allowed": true }