跳到內容
NextPDF
getnextpdf.com

列舉參考

快速概覽

標題為「快速概覽」的區段

有幾個 NextPDF 編寫方法接受一個有型別的 enum，而不是裸字串或整數。這個列舉就是合約：它把引數約束在一個固定、有效的集合內，而 IDE 與 PHPStan 會拒絕落在其外的任何值。本頁是你透過公開 Document 與 Config API 設定（或接收）的那些列舉的允許值查詢表——再加上一個引擎層級的色彩列舉 （RenderingIntent），收錄它是因為它的 case 屬於公開色彩合約的一部分，並在出現之處標記為引擎層級。

這是設定參考的姊妹頁。其中 Config 物件 告訴你 該轉哪個旋鈕， 本頁則告訴你 那個旋鈕接受哪些值。每一筆都列出該列舉的完整限定類別名稱（FQCN）、其 backing 型別、從原始碼照抄的確切 case 清單，以及接受它的公開方法。

引擎內部的深層列舉（HTML/CSS 版面、抽象語法樹、CLI、 shaper 內部）刻意排除在外——你絕不會去設定那些。下面幾乎所有內容都是你透過公開 API 傳入的值；唯一的例外 RenderingIntent 是一個沒有公開 setter 的引擎層級色彩列舉， 列在這裡是為了完整起見，並在它出現之處如此標示。

backing 型別

標題為「backing 型別」的區段

PHP 列舉有兩種形狀，而形狀會改變你寫出該值的方式：

  • 一個 backed 列舉（enum X: string 或 enum X: int）每個 case 都有一個純量 value，因此可透過 X::from('...') / $case->value 來回轉換。本頁大多數列舉都是 backed。
  • 一個 pure 列舉（沒有 backing 型別的 enum X）有 case 但沒有純量值； 你一律以 case 來引用它（X::SomeCase）。只有 UnderlineStyle 是 pure。

兩種形狀下你都是傳入 case 本身——例如 $pdf->addPage(orientation: Orientation::Landscape)。backing 型別只在你需要序列化該選擇，或從設定中讀回它時才重要。

頁面設定

標題為「頁面設定」的區段

Orientation

標題為「Orientation」的區段

直向或橫向的頁面幾何。在你新增頁面時傳入；引擎會互換寬與高以相符。

PropertyValue
FQCNNextPDF\Contracts\Orientation
Backingstring
Set viaDocument::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait)
CaseBacking value
Portrait'P'
Landscape'L'
use NextPDF\Contracts\Orientation;
use NextPDF\ValueObjects\PageSize;


$pdf->addPage(PageSize::a4(), Orientation::Landscape);

繪圖與圖形

標題為「繪圖與圖形」的區段

LineCap

標題為「LineCap」的區段

描邊的開放路徑如何結束。ISO 32000-2:2020 §8.4.3.3。

PropertyValue
FQCNNextPDF\Graphics\LineCap
Backingint
Set viaLineStyle 設定物件（new LineStyle(cap: ...)），以 Document::setLineStyle(LineStyle $style) 套用
CaseBacking valueMeaning
Butt0端點處為方形收尾，不延伸。
Round1端點處為半圓弧。
Square2方形延伸，超出端點達線寬的一半。

LineJoin

標題為「LineJoin」的區段

兩段描邊在轉角處如何相接。ISO 32000-2:2020 §8.4.3.4。

PropertyValue
FQCNNextPDF\Graphics\LineJoin
Backingint
Set viaLineStyle 設定物件（new LineStyle(join: ...)），以 Document::setLineStyle(LineStyle $style) 套用
CaseBacking valueMeaning
Miter0尖角延伸到斜接限值。
Round1以圓弧接合外緣。
Bevel2以對角線連接外緣。

LineCap 與 LineJoin 不會直接傳給某個 Document 方法——它們是不可變的 NextPDF\Graphics\LineStyle 值物件的欄位，你再把該值物件交給 setLineStyle()：

use NextPDF\Graphics\{LineStyle, LineCap, LineJoin};


$style = new LineStyle(width: 1.5, cap: LineCap::Round, join: LineJoin::Bevel);
$pdf->setLineStyle($style);
$pdf->line(20, 20, 120, 20);

BlendMode

標題為「BlendMode」的區段

套用到後續繪圖的透明度混合函式。前十二個 case 是可分離的；最後四個是不可分離的 HSL 模式。ISO 32000-2:2020 §11.3.5。

PropertyValue
FQCNNextPDF\Graphics\BlendMode
Backingstring
Set viaDocument::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal)
CaseBacking valueCaseBacking value
Normal'Normal'HardLight'HardLight'
Multiply'Multiply'SoftLight'SoftLight'
Screen'Screen'Difference'Difference'
Overlay'Overlay'Exclusion'Exclusion'
Darken'Darken'Hue'Hue'
Lighten'Lighten'Saturation'Saturation'
ColorDodge'ColorDodge'Color'Color'
ColorBurn'ColorBurn'Luminosity'Luminosity'
use NextPDF\Graphics\BlendMode;


$pdf->setAlpha(0.6, BlendMode::Multiply);
$pdf->rect(20, 20, 80, 40, 'F');

色彩

標題為「色彩」的區段

RenderingIntent

標題為「RenderingIntent」的區段

色彩轉換期間，超出色域的色彩如何重新映射。發射為 ri 運算子。ISO 32000-2:2020 §8.6.5.8（Table 71）。

與本頁其他列舉不同，RenderingIntent 沒有公開的 Document 或 Config setter——它是一個 引擎層級 列舉。它直接套用在內部繪圖引擎上（DrawingEngine::setRenderingIntent()），由它把 ri 運算子發射進目前的內容串流。我們在這裡列出它是為了完整起見，因為它的 case 屬於公開色彩合約的一部分，但它不屬於本頁其餘部分所記錄的開發者導向編寫 API； 請把繪圖引擎當成內部類別，而非你撰寫程式所對接的進入點。

PropertyValue
FQCNNextPDF\Graphics\RenderingIntent
Backingstring
Set via僅限引擎層級——套用在內部繪圖引擎上；沒有公開的 Document/Config setter。
CaseBacking valueMeaning
RelativeColorimetric'RelativeColorimetric'保留色域內的色彩；裁切色域外的色彩。
AbsoluteColorimetric'AbsoluteColorimetric'精確保留色度值，包含紙白。
Saturation'Saturation'以犧牲色相/亮度為代價，保留鮮明的飽和度。
Perceptual'Perceptual'保留視覺關係；平滑地壓縮色域。

OutputColorProfile

標題為「OutputColorProfile」的區段

宣告在文件 /OutputIntent 上的工作空間色彩設定檔。 預設的 DeviceRGB 保留舊有的「不加額外 OutputIntent」行為； 選用其他任何 case 都會讓寫入器發射一個帶有所附 ICC 設定檔的 /GTS_PDFX OutputIntent（ISO 32000-2:2020 §14.11.5）。這是一個 Config 值，而非逐次呼叫的方法——把它設定在你傳給 Document 的設定物件上。

PropertyValue
FQCNNextPDF\Core\OutputColorProfile
Backingstring
Set viaConfig::withOutputColorProfile(OutputColorProfile $profile)（Config 建構式的 $outputColorProfile 參數）
CaseBacking valueNotes
DeviceRGB'device-rgb'預設。不發射額外的 OutputIntent。
Srgb'srgb'明確的 sRGB OutputIntent（IEC 61966-2-1）。非廣色域。
DisplayP3'display-p3'Display-P3 廣色域（D65）。
Rec2020'rec2020'ITU-R BT.2020 / Rec.2020 廣色域。
A98RGB'a98-rgb'Adobe RGB 1998。
ProphotoRGB'prophoto-rgb'ProPhoto RGB / ROMM RGB（D50）。
use NextPDF\Core\{Config, OutputColorProfile};


$config = (new Config())->withOutputColorProfile(OutputColorProfile::DisplayP3);

文字

標題為「文字」的區段

TextRenderingMode

標題為「TextRenderingMode」的區段

字符是被填滿、描邊、裁切，還是以不可見方式繪製（不可見模式是可搜尋 OCR 圖層的底層機制）。ISO 32000-2:2020 §9.3.6， Table 104。

PropertyValue
FQCNNextPDF\Content\TextRenderingMode
Backingint
Set viaDocument::setTextRenderingMode(TextRenderingMode $mode)
CaseBacking valueMeaning
Fill0填滿字符。
Stroke1描邊字符外框。
FillStroke2先填滿再描邊。
Invisible3以不可見方式繪製（可搜尋 OCR 圖層）。
FillClip4填滿並加入裁切路徑。
StrokeClip5描邊並加入裁切路徑。
FillStrokeClip6填滿、描邊並裁切。
Clip7僅加入裁切路徑（不做可見繪製）。

UnderlineStyle

標題為「UnderlineStyle」的區段

底線裝飾如何繪製。這是本頁唯一的 pure 列舉，因此你一律以 case 來引用它。

PropertyValue
FQCNNextPDF\Contracts\UnderlineStyle
Backingpure（無 backing 值）
Set viaDocument::setUnderlineStyle(UnderlineStyle $style)
CaseMeaning
RectFill在基線下方填滿的矩形（TCPDF 相容的預設值）。
StrokeLine在基線下方描邊的線條（語意性線條繪製）。
use NextPDF\Content\TextRenderingMode;
use NextPDF\Contracts\UnderlineStyle;


$pdf->setTextRenderingMode(TextRenderingMode::Invisible); // OCR text layer
$pdf->setUnderlineStyle(UnderlineStyle::StrokeLine);

符合性

標題為「符合性」的區段

ConformanceMode

標題為「ConformanceMode」的區段

文件層級的符合性合約：寫入器必須遵守哪一個 ISO 部分， 以及是否需要結構標記。預設的 Plain 是無約束的 PDF 2.0 輸出。ISO 14289-2:2024（PDF/UA-2）與 ISO 19005 PDF/A 各部分。

PropertyValue
FQCNNextPDF\Conformance\ConformanceMode
Backingstring
Set viaDocument::setConformanceMode(ConformanceMode $mode)（較低階的逃生口；在 Core 中產出 PDF/UA-2 請優先用 enableTaggedPdf()，產出 PDF/A 則用 enablePdfA()——僅 Premium）
CaseBacking valueContract
Plain'plain'PDF 2.0，無約束（預設）。
PdfUa1'pdfua1'ISO 14289-1（Tagged PDF/UA-1）。
PdfUa2'pdfua2'ISO 14289-2:2024（Tagged PDF/UA-2）。
PdfA2'pdfa2'ISO 19005-2（PDF/A-2）。
PdfA3'pdfa3'ISO 19005-3（PDF/A-3 設定檔判別子）。
PdfA3b'pdfa3b'ISO 19005-3 PDF/A-3b（Basic）。
PdfA3u'pdfa3u'ISO 19005-3 PDF/A-3u（可擷取 Unicode）。
PdfA4'pdfa4'ISO 19005-4:2020（PDF/A-4 設定檔判別子）。
PdfA4e'pdfa4e'ISO 19005-4:2020 PDF/A-4e（Engineering）。
PdfA4f'pdfa4f'ISO 19005-4:2020 PDF/A-4f（File attachments）。

這個列舉帶有述詞輔助方法——isTagged()、isAccessibility()、 isArchival() 與 pdfaPart()——讓寫入器端的閘門依模式分支， 而不必重新推導它。

Core-only 建置實際上能用哪些 case。 這個 enum 型別列出每一個 case，但列出一個 case 並不等於能從 Core 產出 那個符合性：

  • Core（不加額外套件）： Plain、PdfUa1 與 PdfUa2。Tagged PDF / PDF/UA 路徑已內建於 Core——enableTaggedPdf() 會選取 PDF/UA 編寫路徑（預設 PdfUa2），並接好結構樹， 不需任何授權檢查。
  • 僅 Premium： 每一個 PDF/A case（PdfA2、PdfA3、PdfA3b、PdfA3u、 PdfA4、PdfA4e、PdfA4f）。真正的 PDF/A 輸出由 enablePdfA() 產出，它是一項 Premium 級功能（ADR-011）：它需要 nextpdf/pro 套件，並在該套件不存在時以 InvalidConfigException fail closed （「install the nextpdf/pro package」）。

setConformanceMode() 是一個較低階的逃生口，它只會寫入判別子欄位——它 不會 安裝 PDF/A 機制。因此在 Core-only 建置中透過它設定 PdfA* case，只會替文件貼上標籤，卻不會給它 enablePdfA() 所提供的封存保證，所以 Premium-only 模式在 Core-only 建置中 不可 依賴。請用 enableTaggedPdf() / enablePdfA() 來走真正的符合性路徑，並在需要 PDF/A 交付物時取用 Premium 套件。

use NextPDF\Conformance\ConformanceMode;


$pdf->setConformanceMode(ConformanceMode::PdfUa2);

附件

標題為「附件」的區段

AFRelationship

標題為「AFRelationship」的區段

內嵌相關檔案的 /AFRelationship 值。不符合的值會使 PDF/A-3 與 PDF/A-4 驗證失敗，因此這個列舉是設定它的安全方式。ISO 32000-2:2020 §14.13.5（Table 401）。

PropertyValue
FQCNNextPDF\Navigation\AFRelationship
Backingstring
Set viaDocument::embedFile(string $path, string $description = '', AFRelationship|string $afRelationship = AFRelationship::Unspecified)
CaseBacking valueUse
Source'Source'產出此 PDF 的來源文件。
Data'Data'此 PDF 衍生自的原始資料（例如 Factur-X / ZUGFeRD XML）。
Alternative'Alternative'替代呈現（點字、字幕、SVG）。
Supplement'Supplement'補充材料。
EncryptedPayload'EncryptedPayload'此 PDF 所包覆的一個不透明加密 blob。
FormData'FormData'表單資料（XFDF、FDF、XML）。
Schema'Schema'描述某個 Data 檔案的 Schema（XSD、JSON Schema）。PDF 2.0。
Unspecified'Unspecified'未指定關係（預設）。

embedFile() 接受列舉 case 或它的字串字面值（前面有沒有斜線都可以），因此 AFRelationship::Data 與 '/Data' 是等價的。傳入 case 是型別安全的選擇。

use NextPDF\Navigation\AFRelationship;


// e-invoice payload: declare the XML as the source data
$pdf->embedFile('invoice.xml', 'Factur-X invoice data', AFRelationship::Data);

另請參閱

標題為「另請參閱」的區段