Legal — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

• Sinh các con dấu số Bates tuần tự dưới dạng các đoạn content stream PDF theo từng trang.
• Ba kiểu công khai: BatesNumberConfig (cấu hình bất biến), BatesNumberer (engine), BatesPosition (enum vị trí sáu case).
• Mỗi đoạn đều khép kín. Trạng thái đồ họa được lưu và khôi phục, nên việc nối thêm không bao giờ làm xáo trộn nội dung trang hiện có.
• Đầu ra có tính tất định: một đoạn là hàm thuần túy của cấu hình, văn bản con dấu, và kích thước trang.
• Module không phát sinh ngoại lệ nào. Đầu vào ngoài phạm vi sẽ suy giảm theo các quy tắc dự phòng đã được ghi lại.

Tình trạng sẵn có & cấp phép

Tính năng này đi kèm trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một license envelope hạng Pro. Một triển khai không có quyền đó sẽ không nạp các class của tính năng. So sánh các phiên bản và lấy giấy phép.

Không tồn tại cờ giấy phép theo từng tính năng. Đây là một tính năng của phiên bản Pro.

composer require nextpdf/pro:^3

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
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	Cấu hình diện mạo và đánh số bất biến	BatesNumberConfig	—	Cả mười một thuộc tính đều là public và readonly.
BatesNumberConfig::formatNumber	int $pageIndex (đánh số từ 0)	prefix + đệm số không (startNumber + pageIndex) + suffix	string	—	Một số rộng hơn padding sẽ không bị cắt bớt.
BatesNumberConfig::getRange	int $pageCount	Con dấu định dạng đầu tiên và cuối cùng cho lượt chạy	array{first: string, last: string}	—	Giả định pageCount >= 1; số đếm bằng 0 sẽ định dạng chỉ số trang -1.
BatesNumberer::__construct	BatesNumberConfig $config	Ràng buộc cấu hình	BatesNumberer	—	Class này là final và readonly.
BatesNumberer::generate	int $pageCount, array $pageSizes, string $prefix = '', int $startFrom = 1	Đường tắt tĩnh với diện mạo mặc định	list<string>	—	Suffix, vị trí, phông, độ mờ, và layer giữ nguyên giá trị mặc định.
BatesNumberer::generateStreams	int $pageCount, list<array{width: float, height: float}> $pageSizes	Một đoạn khép kín cho mỗi trang	list<string>	Không bao giờ ném; một mục kích thước bị thiếu sẽ dự phòng về A4 dọc	Số đoạn bằng pageCount; các mục kích thước dư sẽ bị bỏ qua.
BatesNumberer::buildPageStream	string $text, float $pageWidth, float $pageHeight	Xây dựng đoạn con dấu của một trang	string	—	Được bọc q/Q; văn bản con dấu được thoát cho cú pháp literal-string.
BatesNumberer::getConfig	—	Trả về cấu hình đã ràng buộc	BatesNumberConfig	—	—
BatesPosition	các case enum BottomLeft, BottomCenter, BottomRight, TopLeft, TopCenter, TopRight	Từ vựng vị trí được hỗ trợ bởi chuỗi	—	—	Các giá trị nền là kebab-case (ví dụ bottom-right).
BatesPosition::coordinates	float $pageWidth, float $pageHeight, float $textWidth, float $inset = 15.0	X/Y cho đường cơ sở của con dấu trong không gian PDF-native	array{x: float, y: float}	—	Gốc tọa độ ở dưới-trái; các hàng trên đặt đường cơ sở cách mép trên inset.

Chữ ký điểm vào

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

Hợp đồng hành vi

Đánh số

BatesNumberConfig::formatNumber tính startNumber + pageIndex, đệm số không ở bên trái cho đủ padding chữ số, và bọc nó bằng prefix và suffix. getRange trả về con dấu định dạng đầu tiên và cuối cùng cho một số trang. Hãy dùng nó để nối tiếp việc đánh số liên tục qua các đợt production.

Cấu tạo đoạn

Mỗi đoạn, theo thứ tự, gồm: một thao tác lưu trạng thái đồ họa (q), một toán tử màu tô, một điểm bắt đầu marked-content tùy chọn, một khối văn bản định vị và hiển thị con dấu, một điểm kết thúc marked-content tùy chọn, và một thao tác khôi phục (Q). Tọa độ và cỡ chữ được tuần tự hóa với sáu chữ số thập phân, nên đầu vào giống nhau tạo ra byte giống nhau. Văn bản con dấu thoát \, (, và ) trước khi đi vào chuỗi literal.

Ràng buộc phông

Khối văn bản chọn tên tài nguyên phông cố định /BatesFont. Resource dictionary của trang nhúng phải ánh xạ tên đó tới một phông khớp với fontFamily đã cấu hình, và họ phông phải phân giải được trong font registry. Bản thân việc sinh đoạn không bao giờ tra cứu registry.

Vị trí đặt

BatesPosition::coordinates tính đường cơ sở của con dấu trong không gian PDF-native; gốc tọa độ ở dưới-trái. Vị trí giữa và phải trừ đi một chiều rộng văn bản ước lượng: độ dài byte nhân 0.6 nhân cỡ chữ, một phép xấp xỉ cho phông monospace. Phông tỷ lệ và văn bản đa byte làm lệch ước lượng đó. Vị trí trái không phụ thuộc vào nó.

Layer

Khi useLayer được bật (mặc định), đoạn bao văn bản giữa các toán tử marked-content BDC và EMC. Tên marked-content có dạng /Lyr_<name>, dẫn xuất từ layerName với các ký tự không phải ký tự chữ được thay bằng dấu gạch dưới. Việc bao này chỉ ở mức đoạn: việc đăng ký nhóm nội dung tùy chọn tương ứng trong tài liệu — bước làm cho layer có thể bật/tắt trong trình xem — thuộc về writer nhúng.

Độ mờ

Một opacity dưới 1.0 được phát ra dưới dạng màu tô thang xám nhạt hơn. Một con dấu hoàn toàn mờ đục hiển thị màu đen.

Phạm vi

Engine áp dụng việc đánh số Bates đúng như đã cấu hình. Nó không khẳng định rằng một tài liệu đã đánh số là được tòa án chấp nhận hay có hiệu lực pháp lý. Sơ đồ đánh số, việc lưu giữ, và việc xử lý chứng cứ vẫn là trách nhiệm của khách hàng; hãy tham vấn các nhóm pháp lý và tuân thủ của bạn về tính đầy đủ về thủ tục.

Trường hợp biên & chế độ lỗi

• generateStreams không bao giờ ném khi pageSizes không khớp. Một mục bị thiếu sẽ dự phòng về A4 dọc, 595.276 nhân 841.890 điểm; các mục dư bị bỏ qua.
• Số đoạn luôn bằng pageCount.
• Một số rộng hơn padding sẽ không bị cắt bớt; văn bản con dấu chỉ đơn giản là dài ra.
• getRange giả định pageCount >= 1. Số đếm bằng 0 sẽ định dạng chỉ số trang -1, tức là startNumber - 1.
• Độ mờ là một việc làm sáng thang xám, không phải độ trong suốt ExtGState; nội dung chồng lấp bên dưới con dấu không được hòa trộn.
• Các byte con dấu khác ngoài \, (, và ) được truyền qua mà không mã hóa. Tính đúng đắn của việc mã hóa cho văn bản không phải ASCII phụ thuộc vào phông đã ràng buộc.
• Các dấu Bates là nội dung phủ. Chúng không biên tập che, xóa, hay mã hóa bất cứ thứ gì trên trang.
• Module không thực hiện thao tác mã hóa nào; chế độ FIPS không thay đổi hành vi của nó.

Tính phù hợp

Hành vi	Tham chiếu	Trạng thái
Bao layer qua các toán tử marked-content BDC/EMC	ISO 32000-2:2020 §8.11.3.2	Một phần — đoạn phát ra việc bao; việc đăng ký nhóm nội dung tùy chọn là bước của writer nhúng

Các hàng này ghi lại đặc tả mà module được xây dựng theo, không phải một chứng nhận; NextPDF không nắm giữ chứng nhận phù hợp nào. Bảng này cũng không phải là một tuyên bố về hiệu lực pháp lý hay tính đầy đủ về chứng cứ.

Ghi chú phát triển

• Các đoạn là những giá trị chuỗi thuần túy. Hãy kiểm thử chúng bằng cách so sánh byte trực tiếp; không cần bối cảnh tài liệu nào.
• buildPageStream là public và có thể unit-test một cách độc lập: truyền văn bản đã định dạng sẵn và kích thước trang tường minh.
• Để đánh số liên tục qua các đợt production, hãy khởi tạo startNumber từ lượt chạy trước và ghi lại đầu ra của getRange vào nhật ký production của bạn.
• Tên layer được làm sạch về các ký tự chữ. Hãy ưu tiên tên layer ASCII để tên marked-content vẫn dễ đọc trong các công cụ kiểm tra.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, class hỗ trợ, bảng cơ chế, tên tệp runbook, và tiền tố ticket đều nằm ngoài phạm vi.

Xem thêm

• Tổng quan tính năng Legal
• Merge — Tài liệu tham chiếu chuyên sâu
• Security — Tài liệu tham chiếu chuyên sâu