Tham chiếu enum
Tổng quan nhanh
Phần tiêu đề “Tổng quan nhanh”Một số phương thức soạn thảo của NextPDF nhận một enum có kiểu thay vì một chuỗi
hoặc số nguyên trần. Enum chính là hợp đồng: nó ràng buộc đối số vào một tập cố
định, hợp lệ, và IDE cùng PHPStan từ chối mọi giá trị nằm ngoài tập đó. Trang này
là nơi tra cứu các giá trị được phép cho những enum bạn đặt (hoặc nhận) thông qua
API Document và Config công khai — cộng thêm một enum màu ở cấp engine
(RenderingIntent), được đưa vào vì các case của nó là một phần của hợp đồng màu
công khai và được đánh dấu là cấp engine ở những chỗ nó xuất hiện.
Đây là trang đồng hành của tài liệu tham chiếu cấu hình. Trong khi
đối tượng Config cho bạn biết nút nào cần xoay,
trang này cho bạn biết nút đó chấp nhận giá trị nào. Mỗi mục liệt kê tên lớp đầy
đủ (FQCN) của enum, kiểu nền của nó, danh sách case chính xác sao chép từ mã
nguồn, và phương thức công khai nhận nó.
Các enum sâu trong nội bộ engine (bố cục HTML/CSS, cây cú pháp trừu tượng, CLI,
nội bộ của shaper) bị loại trừ một cách có chủ đích — bạn không bao giờ đặt chúng.
Hầu hết mọi thứ bên dưới là một giá trị bạn truyền vào qua API công khai; ngoại lệ
duy nhất, RenderingIntent, là một enum màu cấp engine không có setter công khai,
được liệt kê cho đầy đủ và được gắn nhãn như vậy ở chỗ nó xuất hiện.
Kiểu nền
Phần tiêu đề “Kiểu nền”Enum của PHP có hai dạng, và dạng đó thay đổi cách bạn viết giá trị:
- Một enum backed (
enum X: stringhoặcenum X: int) có mộtvaluevô hướng cho mỗi case, nên nó đi vòng quaX::from('...')/$case->value. Hầu hết enum ở đây là backed. - Một enum pure (
enum Xkhông có kiểu nền) có các case nhưng không có giá trị vô hướng; bạn luôn tham chiếu nó qua case (X::SomeCase). ChỉUnderlineStylelà pure.
Ở cả hai dạng, bạn truyền chính case đó — ví dụ
$pdf->addPage(orientation: Orientation::Landscape). Kiểu nền chỉ quan trọng khi
bạn cần tuần tự hóa lựa chọn hoặc đọc nó lại từ cấu hình.
Thiết lập trang
Phần tiêu đề “Thiết lập trang”Orientation
Phần tiêu đề “Orientation”Hình học trang dọc hoặc ngang. Được truyền khi bạn thêm một trang; engine hoán đổi chiều rộng và chiều cao cho khớp.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Contracts\Orientation |
| Backing | string |
| Đặt qua | Document::addPage(?PageSize $size = null, Orientation $orientation = Orientation::Portrait) |
| Case | Giá trị nền |
|---|---|
Portrait | 'P' |
Landscape | 'L' |
use NextPDF\Contracts\Orientation;use NextPDF\ValueObjects\PageSize;
$pdf->addPage(PageSize::a4(), Orientation::Landscape);Vẽ và đồ họa
Phần tiêu đề “Vẽ và đồ họa”LineCap
Phần tiêu đề “LineCap”Cách một đường mở được nét (stroke) kết thúc. ISO 32000-2:2020 §8.4.3.3.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Graphics\LineCap |
| Backing | int |
| Đặt qua | đối tượng cấu hình LineStyle (new LineStyle(cap: ...)), áp dụng bằng Document::setLineStyle(LineStyle $style) |
| Case | Giá trị nền | Ý nghĩa |
|---|---|---|
Butt | 0 | Đầu vuông tại điểm cuối, không nhô ra. |
Round | 1 | Cung bán nguyệt tại điểm cuối. |
Square | 2 | Phần nhô vuông kéo dài thêm nửa độ rộng đường vượt qua điểm cuối. |
LineJoin
Phần tiêu đề “LineJoin”Cách hai đoạn được nét gặp nhau tại một góc. ISO 32000-2:2020 §8.4.3.4.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Graphics\LineJoin |
| Backing | int |
| Đặt qua | đối tượng cấu hình LineStyle (new LineStyle(join: ...)), áp dụng bằng Document::setLineStyle(LineStyle $style) |
| Case | Giá trị nền | Ý nghĩa |
|---|---|---|
Miter | 0 | Góc nhọn kéo dài tới giới hạn miter. |
Round | 1 | Cung tròn nối các cạnh ngoài. |
Bevel | 2 | Đường chéo nối các cạnh ngoài. |
LineCap và LineJoin không được truyền trực tiếp vào một phương thức Document —
chúng là các trường của đối tượng giá trị bất biến NextPDF\Graphics\LineStyle,
mà bạn rồi trao cho 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
Phần tiêu đề “BlendMode”Hàm hòa trộn trong suốt áp dụng cho phần vẽ tiếp theo. Mười hai case đầu là tách được (separable); bốn case cuối là các chế độ HSL không tách được. ISO 32000-2:2020 §11.3.5.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Graphics\BlendMode |
| Backing | string |
| Đặt qua | Document::setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal) |
| Case | Giá trị nền | Case | Giá trị nền |
|---|---|---|---|
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');Màu sắc
Phần tiêu đề “Màu sắc”RenderingIntent
Phần tiêu đề “RenderingIntent”Cách các màu ngoài gam (out-of-gamut) được ánh xạ lại trong quá trình chuyển đổi
màu. Được phát ra dưới dạng toán tử ri. ISO 32000-2:2020 §8.6.5.8 (Bảng 71).
Khác với các enum khác trên trang này, RenderingIntent không có setter công
khai trên Document hay Config — nó là một enum cấp engine. Nó được áp dụng
trực tiếp trên engine vẽ nội bộ (DrawingEngine::setRenderingIntent()), engine
này phát toán tử ri vào luồng nội dung hiện tại. Chúng tôi liệt kê nó ở đây cho
đầy đủ vì các case của nó là một phần của hợp đồng màu công khai, nhưng nó không
phải là một phần của API soạn thảo hướng tới nhà phát triển mà phần còn lại của
trang này ghi lại; hãy xem engine vẽ như một lớp nội bộ chứ không phải điểm vào mà
bạn lập trình lên.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Graphics\RenderingIntent |
| Backing | string |
| Đặt qua | Chỉ ở cấp engine — áp dụng trên engine vẽ nội bộ; không có setter công khai trên Document/Config. |
| Case | Giá trị nền | Ý nghĩa |
|---|---|---|
RelativeColorimetric | 'RelativeColorimetric' | Bảo toàn các màu trong gam; cắt phần ngoài gam. |
AbsoluteColorimetric | 'AbsoluteColorimetric' | Bảo toàn chính xác các giá trị đo màu, kể cả màu trắng giấy. |
Saturation | 'Saturation' | Bảo toàn độ bão hòa rực rỡ, đánh đổi sắc độ/độ sáng. |
Perceptual | 'Perceptual' | Bảo toàn các quan hệ thị giác; nén gam mượt mà. |
OutputColorProfile
Phần tiêu đề “OutputColorProfile”Hồ sơ màu không gian làm việc được khai báo trên /OutputIntent của tài liệu.
Giá trị mặc định DeviceRGB bảo toàn hành vi cũ “không thêm OutputIntent”; chọn
bất kỳ case nào khác khiến trình ghi phát ra một OutputIntent /GTS_PDFX cùng hồ
sơ ICC đi kèm (ISO 32000-2:2020 §14.11.5). Đây là một giá trị Config, không
phải một phương thức theo từng lệnh gọi — đặt nó trên đối tượng cấu hình bạn truyền
vào Document.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Core\OutputColorProfile |
| Backing | string |
| Đặt qua | Config::withOutputColorProfile(OutputColorProfile $profile) (tham số $outputColorProfile của hàm khởi tạo Config) |
| Case | Giá trị nền | Ghi chú |
|---|---|---|
DeviceRGB | 'device-rgb' | Mặc định. Không phát thêm OutputIntent. |
Srgb | 'srgb' | OutputIntent sRGB tường minh (IEC 61966-2-1). Không phải gam rộng. |
DisplayP3 | 'display-p3' | Display-P3 gam rộng (D65). |
Rec2020 | 'rec2020' | ITU-R BT.2020 / Rec.2020 gam rộng. |
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);Văn bản
Phần tiêu đề “Văn bản”TextRenderingMode
Phần tiêu đề “TextRenderingMode”Liệu các glyph được tô, được nét, được cắt, hay được kết xuất vô hình (chế độ vô hình là nền tảng cho các lớp OCR có thể tìm kiếm). ISO 32000-2:2020 §9.3.6, Bảng 104.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Content\TextRenderingMode |
| Backing | int |
| Đặt qua | Document::setTextRenderingMode(TextRenderingMode $mode) |
| Case | Giá trị nền | Ý nghĩa |
|---|---|---|
Fill | 0 | Tô các glyph. |
Stroke | 1 | Nét theo viền glyph. |
FillStroke | 2 | Tô rồi nét. |
Invisible | 3 | Kết xuất vô hình (các lớp OCR có thể tìm kiếm). |
FillClip | 4 | Tô và thêm vào đường cắt. |
StrokeClip | 5 | Nét và thêm vào đường cắt. |
FillStrokeClip | 6 | Tô, nét, và cắt. |
Clip | 7 | Chỉ thêm vào đường cắt (không kết xuất nhìn thấy). |
UnderlineStyle
Phần tiêu đề “UnderlineStyle”Cách một trang trí gạch dưới được vẽ. Đây là enum pure duy nhất ở đây, nên bạn luôn tham chiếu nó qua case.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Contracts\UnderlineStyle |
| Backing | pure (no backing value) |
| Đặt qua | Document::setUnderlineStyle(UnderlineStyle $style) |
| Case | Ý nghĩa |
|---|---|
RectFill | Hình chữ nhật được tô bên dưới đường cơ sở (mặc định tương thích TCPDF). |
StrokeLine | Đường được nét bên dưới đường cơ sở (vẽ đường theo ngữ nghĩa). |
use NextPDF\Content\TextRenderingMode;use NextPDF\Contracts\UnderlineStyle;
$pdf->setTextRenderingMode(TextRenderingMode::Invisible); // OCR text layer$pdf->setUnderlineStyle(UnderlineStyle::StrokeLine);Tuân thủ
Phần tiêu đề “Tuân thủ”ConformanceMode
Phần tiêu đề “ConformanceMode”Hợp đồng tuân thủ ở cấp tài liệu: phần ISO nào trình ghi phải tôn trọng, và liệu
việc gắn thẻ cấu trúc có bắt buộc hay không. Mặc định Plain là đầu ra PDF 2.0
không ràng buộc. ISO 14289-2:2024 (PDF/UA-2) và các phần PDF/A của ISO 19005.
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Conformance\ConformanceMode |
| Backing | string |
| Đặt qua | Document::setConformanceMode(ConformanceMode $mode) (lối thoát ở cấp thấp hơn; nên dùng enableTaggedPdf() cho PDF/UA-2 trong Core, hoặc enablePdfA() — chỉ Premium — cho PDF/A) |
| Case | Giá trị nền | Hợp đồng |
|---|---|---|
Plain | 'plain' | PDF 2.0, không ràng buộc (mặc định). |
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 (bộ phân biệt profile PDF/A-3). |
PdfA3b | 'pdfa3b' | ISO 19005-3 PDF/A-3b (Basic). |
PdfA3u | 'pdfa3u' | ISO 19005-3 PDF/A-3u (trích xuất được Unicode). |
PdfA4 | 'pdfa4' | ISO 19005-4:2020 (bộ phân biệt profile PDF/A-4). |
PdfA4e | 'pdfa4e' | ISO 19005-4:2020 PDF/A-4e (Engineering). |
PdfA4f | 'pdfa4f' | ISO 19005-4:2020 PDF/A-4f (File attachments). |
Enum này mang theo các hàm trợ giúp dạng predicate — isTagged(),
isAccessibility(), isArchival(), và pdfaPart() — để các cổng kiểm tra phía
trình ghi rẽ nhánh theo chế độ thay vì suy diễn lại nó.
Những case mà một bản build chỉ-Core thực sự có thể dùng. Kiểu enum liệt kê
mọi case, nhưng việc liệt kê một case không đồng nghĩa với việc có thể tạo ra sự
tuân thủ đó từ Core:
- Core (không gói thêm):
Plain,PdfUa1, vàPdfUa2. Lối Tagged PDF / PDF/UA được tích hợp sẵn trong Core —enableTaggedPdf()chọn lối soạn thảo PDF/UA (PdfUa2mặc định) và đấu nối cây cấu trúc mà không cần bất kỳ kiểm tra giấy phép nào. - Chỉ Premium: mọi case PDF/A (
PdfA2,PdfA3,PdfA3b,PdfA3u,PdfA4,PdfA4e,PdfA4f). Đầu ra PDF/A thực sự được tạo bởienablePdfA(), vốn là một tính năng cấp Premium (ADR-011): nó yêu cầu góinextpdf/provà thất bại đóng (fail closed) với mộtInvalidConfigException(“install the nextpdf/pro package”) khi gói đó vắng mặt.
setConformanceMode() là một lối thoát ở cấp thấp hơn, chỉ ghi trường phân biệt —
nó không cài đặt bộ máy PDF/A. Vì vậy, việc đặt một case PdfA* qua nó trong
một bản build chỉ-Core sẽ gắn nhãn cho tài liệu mà không trao cho nó những bảo đảm
lưu trữ mà enablePdfA() cung cấp, nên các chế độ chỉ-Premium không được dựa
vào trong một bản build chỉ-Core. Hãy dùng
enableTaggedPdf() / enablePdfA() cho các lối tuân thủ thật sự, và với tới gói
Premium bất cứ khi nào cần một sản phẩm PDF/A.
use NextPDF\Conformance\ConformanceMode;
$pdf->setConformanceMode(ConformanceMode::PdfUa2);Tệp đính kèm
Phần tiêu đề “Tệp đính kèm”AFRelationship
Phần tiêu đề “AFRelationship”Giá trị /AFRelationship cho một tệp liên kết được nhúng. Một giá trị không tuân
thủ sẽ thất bại khi xác thực PDF/A-3 và PDF/A-4, nên enum là cách an toàn để đặt
nó. ISO 32000-2:2020 §14.13.5 (Bảng 401).
| Thuộc tính | Giá trị |
|---|---|
| FQCN | NextPDF\Navigation\AFRelationship |
| Backing | string |
| Đặt qua | Document::embedFile(string $path, string $description = '', AFRelationship|string $afRelationship = AFRelationship::Unspecified) |
| Case | Giá trị nền | Công dụng |
|---|---|---|
Source | 'Source' | Tài liệu nguồn mà PDF được tạo ra từ đó. |
Data | 'Data' | Dữ liệu thô mà PDF được dẫn xuất từ đó (ví dụ XML Factur-X / ZUGFeRD). |
Alternative | 'Alternative' | Trình bày thay thế (chữ nổi braille, phụ đề, SVG). |
Supplement | 'Supplement' | Tài liệu bổ sung. |
EncryptedPayload | 'EncryptedPayload' | Một blob mã hóa mờ đục mà PDF bao bọc. |
FormData | 'FormData' | Dữ liệu biểu mẫu (XFDF, FDF, XML). |
Schema | 'Schema' | Schema mô tả một tệp Data (XSD, JSON Schema). PDF 2.0. |
Unspecified | 'Unspecified' | Không chỉ định quan hệ nào (mặc định). |
embedFile() chấp nhận hoặc case enum hoặc chuỗi literal của nó (có hoặc không có
dấu gạch chéo đầu), nên AFRelationship::Data và '/Data' là tương đương. Truyền
case là lựa chọn an toàn về kiểu.
use NextPDF\Navigation\AFRelationship;
// e-invoice payload: declare the XML as the source data$pdf->embedFile('invoice.xml', 'Factur-X invoice data', AFRelationship::Data);Xem thêm
Phần tiêu đề “Xem thêm”- Tham chiếu cấu hình — đối tượng
Configmà những enum này ràng buộc các giá trị của nó, bao gồmwithOutputColorProfile(). - Module Graphics —
LineStyle,BlendMode,RenderingIntent, và engine vẽ. - Module Typography — kết xuất văn bản và trang trí gạch dưới.
- Module Conformance — bộ phân biệt
ConformanceModevà các lối kích hoạt PDF/UA / PDF/A. - Module Navigation — các tệp liên kết và cơ
chế
/AF. - Chỉ mục tham chiếu — điểm vào cho tài liệu tham chiếu API, cấu hình, và tương thích.