跳转到内容
NextPDF
getnextpdf.com

Enum 参考

概览

标题为“概览”的章节

NextPDF 的若干编写方法接受的是带类型的 enum，而不是裸字符串或整数。enum 就是契约：它把参数约束在一个固定且有效的集合内，IDE 与 PHPStan 会拒绝该集合之外的任何取值。本页是你通过公共 Document 与 Config API 设置（或接收）的那些 enum 的允许取值查询表——外加一个引擎级颜色 enum（RenderingIntent），之所以收录它，是因为它的 case 属于公共颜色契约的一部分，并会在出现处标注为引擎级。

这是配置参考的配套页面。如果说 Config 对象 告诉你该转哪个旋钮，那么本页就告诉你那个旋钮接受哪些取值。每个条目都列出该 enum 的完全限定类名（FQCN）、它的底层类型、从源码原样复制的精确 case 列表，以及接受它的公共方法。

深层的引擎内部 enum（HTML/CSS 布局、抽象语法树、CLI、整形器内部）被刻意排除在外——你从不设置这些。下文几乎所有内容都是你通过公共 API 传入的取值；唯一的例外 RenderingIntent 是一个没有公共 setter 的引擎级颜色 enum，为完整起见列出，并在出现处如此标注。

底层类型

标题为“底层类型”的章节

PHP enum 有两种形态，而形态会改变你书写取值的方式：

  • backed enum（enum X: string 或 enum X: int）的每个 case 都有一个标量 value，因此它可以通过 X::from('...') / $case->value 往返转换。这里的大多数 enum 都是 backed 的。
  • pure enum（enum X 没有底层类型）有 case 但没有标量值；你始终通过 case 来引用它（X::SomeCase）。只有 UnderlineStyle 是 pure 的。

在这两种形态下，你传入的都是 case 本身——例如 $pdf->addPage(orientation: Orientation::Landscape)。底层类型仅在你需要把选择序列化、或从配置中读回时才有意义。

页面设置

标题为“页面设置”的章节

Orientation

标题为“Orientation”的章节

纵向或横向页面几何。在添加页面时传入；引擎会交换宽度与高度以匹配。

属性取值
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。

属性取值
FQCNNextPDF\Graphics\LineCap
Backingint
Set viaLineStyle 配置对象（new LineStyle(cap: ...)），通过 Document::setLineStyle(LineStyle $style) 应用
CaseBacking value含义
Butt0端点处为方形收尾，无任何延伸。
Round1端点处为半圆弧。
Square2方形延伸，超出端点半个线宽。

LineJoin

标题为“LineJoin”的章节

两个描边线段在转角处如何相接。ISO 32000-2:2020 §8.4.3.4。

属性取值
FQCNNextPDF\Graphics\LineJoin
Backingint
Set viaLineStyle 配置对象（new LineStyle(join: ...)），通过 Document::setLineStyle(LineStyle $style) 应用
CaseBacking value含义
Miter0尖角延伸至斜接限制（miter limit）。
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。

属性取值
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（表 71）。

与本页其他 enum 不同，RenderingIntent 没有公共的 Document 或 Config setter——它是一个引擎级 enum。它直接应用在内部绘图引擎（DrawingEngine::setRenderingIntent()）上，该引擎会把 ri 运算符发出到当前内容流中。我们在此列出它是为了完整性，因为它的 case 属于公共颜色契约的一部分，但它并不属于本页其余部分所记录的面向开发者的编写 API；请把绘图引擎当作一个内部类，而不是你所编程对接的入口点。

属性取值
FQCNNextPDF\Graphics\RenderingIntent
Backingstring
Set via仅限引擎级——应用在内部绘图引擎上；没有公共的 Document/Config setter。
CaseBacking value含义
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 的配置对象上设置它。

属性取值
FQCNNextPDF\Core\OutputColorProfile
Backingstring
Set viaConfig::withOutputColorProfile(OutputColorProfile $profile)（即 Config 构造函数的 $outputColorProfile 参数）
CaseBacking value说明
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，表 104。

属性取值
FQCNNextPDF\Content\TextRenderingMode
Backingint
Set viaDocument::setTextRenderingMode(TextRenderingMode $mode)
CaseBacking value含义
Fill0填充字形。
Stroke1描边字形轮廓。
FillStroke2先填充后描边。
Invisible3不可见渲染（可搜索 OCR 图层）。
FillClip4填充并加入裁剪路径。
StrokeClip5描边并加入裁剪路径。
FillStrokeClip6填充、描边并裁剪。
Clip7仅加入裁剪路径（无可见渲染）。

UnderlineStyle

标题为“UnderlineStyle”的章节

下划线装饰如何绘制。这是本页唯一的 pure enum，因此你始终通过 case 来引用它。

属性取值
FQCNNextPDF\Contracts\UnderlineStyle
Backingpure（无底层取值）
Set viaDocument::setUnderlineStyle(UnderlineStyle $style)
Case含义
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 各部分。

属性取值
FQCNNextPDF\Conformance\ConformanceMode
Backingstring
Set viaDocument::setConformanceMode(ConformanceMode $mode)（较低层的应急通道；在 Core 中针对 PDF/UA-2 优先使用 enableTaggedPdf()，针对 PDF/A 优先使用 enablePdfA()——仅 Premium 提供）
CaseBacking value契约
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 profile 判别符）。
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 profile 判别符）。
PdfA4e'pdfa4e'ISO 19005-4:2020 PDF/A-4e（Engineering）。
PdfA4f'pdfa4f'ISO 19005-4:2020 PDF/A-4f（File attachments）。

该 enum 自带断言式辅助方法——isTagged()、isAccessibility()、isArchival() 与 pdfaPart()——因此写入器侧的门控会基于该模式分支，而不必重新推导它。

仅 Core 的构建实际能使用哪些 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 包，并在该包缺失时以失败关闭（fail closed）的方式抛出 InvalidConfigException（“install the nextpdf/pro package”）。

setConformanceMode() 是较低层的应急通道，它只写入判别符字段——它不会安装 PDF/A 机制。因此，在仅 Core 的构建中通过它设置某个 PdfA* case，只会给文档贴上标签，而不会赋予 enablePdfA() 所提供的归档保证，所以仅 Premium 的模式在仅 Core 的构建中绝不可依赖。请使用 enableTaggedPdf() / enablePdfA() 来获得真正的合规性路径，并在需要 PDF/A 交付物时取用 Premium 包。

use NextPDF\Conformance\ConformanceMode;


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

附件

标题为“附件”的章节

AFRelationship

标题为“AFRelationship”的章节

嵌入的关联文件的 /AFRelationship 取值。不符合规范的取值会使 PDF/A-3 与 PDF/A-4 校验失败，因此该 enum 是安全的设置方式。ISO 32000-2:2020 §14.13.5（表 401）。

属性取值
FQCNNextPDF\Navigation\AFRelationship
Backingstring
Set viaDocument::embedFile(string $path, string $description = '', AFRelationship|string $afRelationship = AFRelationship::Unspecified)
CaseBacking value用途
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() 既接受 enum 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);

另请参阅

标题为“另请参阅”的章节