Legal — 深度参考

一览

• 生成顺序 Bates 编号印记，作为逐页的 PDF 内容流片段。
• 三个公共类型：BatesNumberConfig（不可变配置）、BatesNumberer（引擎）、BatesPosition（六值位置枚举）。
• 每个片段都是自包含的。图形状态会被保存并恢复，因此追加操作绝不会扰动现有的页面内容。
• 输出是确定性的：片段是配置、印记文本与页面尺寸的纯函数。
• 本模块不抛出任何异常。超出范围的输入会按文档所述的回退规则降级处理。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）一同发布，并通过 Pro 层级的授权信封激活。缺少该授权的部署不会加载此能力的类。比较版本并获取授权。

不存在逐功能的授权标记。这是一项 Pro 版本能力。

composer require nextpdf/pro:^3

公共 API 接口面

符号	参数	默认行为	返回	抛出或失败于	说明
BatesNumberConfig::__construct	string $prefix = '', string $suffix = '', int $startNumber = 1, int $padding = 5, BatesPosition $position = BatesPosition::BottomRight, float $fontSize = 9.0, string $fontFamily = 'Courier', float $opacity = 1.0, bool $useLayer = true, string $layerName = 'Bates Numbers', float $inset = 15.0	不可变的外观与编号配置	BatesNumberConfig	—	全部十一个属性均为 public 且 readonly。
BatesNumberConfig::formatNumber	int $pageIndex（从 0 起）	prefix + 补零后的（startNumber + pageIndex）+ suffix	string	—	宽度超过 padding 的编号不会被截断。
BatesNumberConfig::getRange	int $pageCount	本次运行的首个与最后一个格式化印记	array{first: string, last: string}	—	假定 pageCount >= 1；计数为 0 时会格式化页索引 -1。
BatesNumberer::__construct	BatesNumberConfig $config	绑定该配置	BatesNumberer	—	该类为 final 且 readonly。
BatesNumberer::generate	int $pageCount, array $pageSizes, string $prefix = '', int $startFrom = 1	使用默认外观的静态快捷路径	list<string>	—	后缀、位置、字体、不透明度与图层保持默认值。
BatesNumberer::generateStreams	int $pageCount, list<array{width: float, height: float}> $pageSizes	每页一个自包含片段	list<string>	绝不抛出；缺失的尺寸条目回退为 A4 纵向	片段数量等于 pageCount；多余的尺寸条目会被忽略。
BatesNumberer::buildPageStream	string $text, float $pageWidth, float $pageHeight	构建单页的印记片段	string	—	以 q/Q 包裹；印记文本按字面字符串语法进行转义。
BatesNumberer::getConfig	—	返回所绑定的配置	BatesNumberConfig	—	—
BatesPosition	枚举值 BottomLeft、BottomCenter、BottomRight、TopLeft、TopCenter、TopRight	以字符串为背衬的位置词汇表	—	—	背衬值为 kebab-case（例如 bottom-right）。
BatesPosition::coordinates	float $pageWidth, float $pageHeight, float $textWidth, float $inset = 15.0	PDF 原生空间中印记基线的 X/Y	array{x: float, y: float}	—	原点位于左下角；顶部各行将基线置于距顶边 inset 处。

入口点签名

public function __construct(
    public string $prefix = '',
    public string $suffix = '',
    public int $startNumber = 1,
    public int $padding = 5,
    public BatesPosition $position = BatesPosition::BottomRight,
    public float $fontSize = 9.0,
    public string $fontFamily = 'Courier',
    public float $opacity = 1.0,
    public bool $useLayer = true,
    public string $layerName = 'Bates Numbers',
    public float $inset = 15.0,
) {}

public static function generate(
    int $pageCount,
    array $pageSizes,
    string $prefix = '',
    int $startFrom = 1,
): array
public function generateStreams(int $pageCount, array $pageSizes): array
public function buildPageStream(string $text, float $pageWidth, float $pageHeight): string

public function coordinates(
    float $pageWidth,
    float $pageHeight,
    float $textWidth,
    float $inset = 15.0,
): array

行为契约

编号

BatesNumberConfig::formatNumber 计算 startNumber + pageIndex，将该编号左侧补零至 padding 位，并以 prefix 与 suffix 包裹。getRange 返回给定页数的首个与最后一个格式化印记。可用它在各次文档提交（production）之间衔接连续编号。

片段结构

每个片段依次包含：一次图形状态保存（q）、一个填充色操作符、一个可选的标记内容起始、一个用于定位并显示印记的文本块、一个可选的标记内容结束，以及一次恢复（Q）。坐标与字号会以六位小数序列化，因此相同的输入产生相同的字节。印记文本在进入字面字符串之前会转义 \、( 与 )。

字体绑定

文本块会选用固定的字体资源名 /BatesFont。嵌入页面的资源字典必须将该名称映射到与所配置 fontFamily 匹配的字体，且该字体族必须能在字体注册表中解析。片段生成本身绝不查询该注册表。

摆放

BatesPosition::coordinates 在 PDF 原生空间中计算印记基线；原点位于左下角。居中与靠右摆放会减去一个估算的文本宽度：字节长度乘以 0.6 再乘以字号，这是一个等宽字体的近似。比例字体与多字节文本会使该估算发生偏移。靠左摆放不依赖于它。

图层

当启用 useLayer（默认）时，片段会用 BDC 与 EMC 标记内容操作符将文本括起。标记内容名形如 /Lyr_<name>，由 layerName 将非单词字符替换为下划线得到。这种括起仅在片段层级：在文档中注册对应的可选内容组——即让图层在查看器中可切换的那一步——属于嵌入写入器的职责。

不透明度

低于 1.0 的 opacity 会以更浅的灰度填充输出。完全不透明的印记渲染为黑色。

适用范围

引擎会完全按照配置应用 Bates 编号。它不会主张一份已编号的文档可被法庭采信或在法律上有效。编号方案、留存与证据处理仍是客户的责任；请就程序上的充分性咨询你的法律与合规团队。

边界情形与失败模式

• generateStreams 在 pageSizes 不匹配时绝不抛出。缺失的条目回退为 A4 纵向，595.276 × 841.890 点；多余的条目会被忽略。
• 片段数量始终等于 pageCount。
• 宽度超过 padding 的编号不会被截断；印记文本只会随之变长。
• getRange 假定 pageCount >= 1。计数为 0 时会格式化页索引 -1，即 startNumber - 1。
• 不透明度是一种灰度提亮，而非 ExtGState 透明度；印记下方被覆盖的内容不会被混合。
• 除 \、( 与 ) 之外的印记字节会原样透传、不作编码。非 ASCII 文本的编码正确性取决于所绑定的字体。
• Bates 标记是覆盖层内容。它们不会对页面上的任何内容进行涂黑、移除或加密。
• 本模块不执行任何密码学操作；FIPS 模式不会改变其行为。

一致性

行为	参考	状态
通过 BDC/EMC 标记内容操作符进行图层括起	ISO 32000-2:2020 §8.11.3.2	部分——片段发出括起；可选内容组的注册是嵌入写入器的步骤

这些行记录的是本模块所依据构建的规范，而非一项认证；NextPDF 未持有任何一致性认证。此表也不是关于法律有效性或证据充分性的声明。

开发说明

• 片段是纯字符串值。可通过直接字节比较来测试它们；无需任何文档上下文。
• buildPageStream 是 public 的，可独立进行单元测试：传入预格式化的文本与明确的页面尺寸。
• 如需在各次文档提交之间衔接连续编号，请以上一次运行的结果为 startNumber 播种，并将 getRange 的输出记入你的提交日志。
• 图层名会被净化为单词字符。请优先使用 ASCII 图层名，以便标记内容名在检查工具中保持可读。

发布边界

本页仅记录外部可观察的行为与受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、运行手册文件名与工单前缀均不在范围之内。

另请参阅

• Legal 能力概览
• Merge — 深度参考
• Security — 深度参考