Legal — 深入參考

概覽

• 以每頁一段 PDF 內容串流片段的形式，產生循序的 Bates 編號戳記。
• 三個公開型別：BatesNumberConfig（不可變設定）、BatesNumberer（引擎）、BatesPosition（六種 case 的位置列舉）。
• 每個片段都自包含。圖形狀態會被儲存與還原，因此附加它絕不會干擾既有的頁面內容。
• 輸出具決定性：片段是設定、戳記文字與頁面尺寸的純函式。
• 此模組不會拋出任何例外。超出範圍的輸入會依文件記載的回退規則降級處理。

供應與授權

此功能隨 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>	—	suffix、position、font、opacity 與 layer 皆維持預設值。
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	列舉 case 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 會回傳某個頁數的首個與末個格式化戳記。用它來跨多批交付串接延續編號。

片段結構

每個片段依序為：一個圖形狀態儲存（q）、一個填色運算子、一個選用的標記內容開始、一個定位並顯示戳記的文字區塊、一個選用的標記內容結束，以及一個還原（Q）。座標與字型大小會以六位小數序列化，因此相同的輸入會產生相同的位元組。戳記文字在進入字面字串前，會逸出 \、( 與 )。

字型綁定

文字區塊會選用固定的字型資源名稱 /BatesFont。嵌入頁面的資源字典必須將該名稱對應到符合所設定 fontFamily 的字型，且該家族必須能在字型登錄中解析。片段產生本身絕不會查詢該登錄。

放置

BatesPosition::coordinates 會在 PDF 原生空間中計算戳記基線；原點在左下角。置中與靠右放置會減去一個估算的文字寬度：位元組長度乘以 0.6 再乘以字型大小，這是一個等寬近似值。比例字型與多位元組文字會使該估算值偏移。靠左放置則不依賴它。

圖層

當 useLayer 啟用時（預設），片段會將文字包夾在 BDC 與 EMC 標記內容運算子之間。標記內容名稱的形式為 /Lyr_<name>，由 layerName 衍生，其中非 word 字元會替換為底線。此包夾僅止於片段層級：在文件中註冊對應的選用內容群組——也就是讓該圖層在檢視器中可切換的步驟——屬於嵌入寫入器的職責。

不透明度

低於 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 是公開的，且可獨立進行單元測試：傳入預先格式化的文字與明確的頁面尺寸。
• 若要跨多批交付進行延續編號，請以上一批的結果作為 startNumber 的起始值，並將 getRange 的輸出記錄在你的交付日誌中。
• 圖層名稱會被淨化為 word 字元。優先使用 ASCII 圖層名稱，讓標記內容名稱在檢視工具中維持可讀。

出版邊界

本頁僅記錄外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、操作手冊檔名與工單前綴皆不在範圍內。

另請參閱

• Legal 功能總覽
• Merge — 深入參考
• Security — 深入參考