Pro edycja

Legal — szczegółowa dokumentacja referencyjna

W skrócie

Generuje sekwencyjne stemple numeracji Batesa jako fragmenty strumienia treści PDF dla poszczególnych stron.
Trzy typy publiczne: BatesNumberConfig (niemutowalna konfiguracja), BatesNumberer (silnik), BatesPosition (enum pozycji o sześciu przypadkach).
Każdy fragment jest samodzielny. Stan grafiki jest zapisywany i przywracany, więc dołączanie nigdy nie narusza istniejącej treści strony.
Wynik jest deterministyczny: fragment jest czystą funkcją konfiguracji, tekstu stempla i rozmiaru strony.
Moduł nie zgłasza żadnych wyjątków. Dane wejściowe spoza zakresu są degradowane zgodnie z udokumentowanymi regułami awaryjnymi.

Dostępność i licencjonowanie

Ta funkcjonalność jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się przy użyciu koperty licencyjnej w warstwie Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcjonalności. Porównaj edycje i uzyskaj licencję.

Nie istnieje flaga licencji dla poszczególnych funkcji. Jest to funkcjonalność edycji Pro.

composer require nextpdf/pro:^3

Powierzchnia publicznego API

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się błędem	Uwagi
`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`	Niemutowalna konfiguracja wyglądu i numeracji	`BatesNumberConfig`	—	Wszystkie jedenaście właściwości jest publicznych i readonly.
`BatesNumberConfig::formatNumber`	`int $pageIndex` (liczony od 0)	`prefix` + uzupełnione zerami (`startNumber + pageIndex`) + `suffix`	`string`	—	Liczba szersza niż `padding` nie jest obcinana.
`BatesNumberConfig::getRange`	`int $pageCount`	Pierwszy i ostatni sformatowany stempel dla przebiegu	`array{first: string, last: string}`	—	Zakłada `pageCount >= 1`; liczba 0 formatuje indeks strony -1.
`BatesNumberer::__construct`	`BatesNumberConfig $config`	Wiąże konfigurację	`BatesNumberer`	—	Klasa jest final i readonly.
`BatesNumberer::generate`	`int $pageCount`, `array $pageSizes`, `string $prefix = ''`, `int $startFrom = 1`	Statyczna szybka ścieżka z domyślnym wyglądem	`list<string>`	—	Sufiks, pozycja, czcionka, krycie i warstwa pozostają wartościami domyślnymi.
`BatesNumberer::generateStreams`	`int $pageCount`, `list<array{width: float, height: float}> $pageSizes`	Jeden samodzielny fragment na stronę	`list<string>`	Nigdy nie zgłasza wyjątku; brakujący wpis rozmiaru używa domyślnie A4 pionowo	Liczba fragmentów równa się `pageCount`; nadmiarowe wpisy rozmiarów są ignorowane.
`BatesNumberer::buildPageStream`	`string $text`, `float $pageWidth`, `float $pageHeight`	Buduje fragment stempla dla jednej strony	`string`	—	Owinięte w `q`/`Q`; tekst stempla poddany sekwencji ucieczki na potrzeby składni literału łańcuchowego.
`BatesNumberer::getConfig`	—	Zwraca powiązaną konfigurację	`BatesNumberConfig`	—	—
`BatesPosition`	przypadki enum `BottomLeft`, `BottomCenter`, `BottomRight`, `TopLeft`, `TopCenter`, `TopRight`	Słownik pozycji oparty na łańcuchach (string-backed)	—	—	Wartości bazowe są w kebab-case (na przykład `bottom-right`).
`BatesPosition::coordinates`	`float $pageWidth`, `float $pageHeight`, `float $textWidth`, `float $inset = 15.0`	X/Y dla linii bazowej stempla w przestrzeni natywnej PDF	`array{x: float, y: float}`	—	Początek układu w lewym dolnym rogu; górne rzędy umieszczają linię bazową w odległości `inset` od górnej krawędzi.

Sygnatury punktów wejścia

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

Kontrakt zachowania

Numeracja

BatesNumberConfig::formatNumber oblicza startNumber + pageIndex, uzupełnia liczbę zerami z lewej strony do padding cyfr i otacza ją wartościami prefix oraz suffix. getRange zwraca pierwszy i ostatni sformatowany stempel dla danej liczby stron. Użyj go, aby połączyć numerację kontynuowaną między kolejnymi produkcjami dokumentów.

Anatomia fragmentu

Każdy fragment składa się, w kolejności, z: zapisania stanu grafiki (q), operatora koloru wypełnienia, opcjonalnego początku treści oznaczonej, bloku tekstu, który pozycjonuje i wyświetla stempel, opcjonalnego końca treści oznaczonej oraz przywrócenia stanu (Q). Współrzędne i rozmiar czcionki są serializowane z sześcioma miejscami po przecinku, więc identyczne dane wejściowe dają identyczne bajty. Tekst stempla poddaje sekwencji ucieczki znaki \, ( oraz ), zanim trafi do literału łańcuchowego.

Wiązanie czcionki

Blok tekstu wybiera stałą nazwę zasobu czcionki /BatesFont. Słownik zasobów strony osadzającej musi odwzorować tę nazwę na czcionkę odpowiadającą skonfigurowanej wartości fontFamily, a rodzina musi rozwiązać się w rejestrze czcionek. Samo generowanie fragmentu nigdy nie odwołuje się do rejestru.

Rozmieszczenie

BatesPosition::coordinates oblicza linię bazową stempla w przestrzeni natywnej PDF; początek układu jest w lewym dolnym rogu. Rozmieszczenie do środka i do prawej odejmuje szacowaną szerokość tekstu: długość w bajtach razy 0,6 razy rozmiar czcionki, co jest przybliżeniem dla czcionki monospace. Czcionki proporcjonalne i tekst wielobajtowy przesuwają to oszacowanie. Rozmieszczenie do lewej od niego nie zależy.

Warstwy

Gdy useLayer jest włączone (wartość domyślna), fragment ujmuje tekst między operatorami treści oznaczonej BDC i EMC. Nazwa treści oznaczonej ma postać /Lyr_<name>, wyprowadzoną z layerName przez zastąpienie znaków niebędących znakami słowa podkreśleniami. Ujmowanie odbywa się wyłącznie na poziomie fragmentu: zarejestrowanie odpowiadającej grupy treści opcjonalnej w dokumencie — krok, który sprawia, że warstwa staje się przełączalna w przeglądarce — należy do modułu zapisującego, który dokonuje osadzenia.

Krycie

Wartość opacity poniżej 1.0 jest emitowana jako jaśniejsze wypełnienie w skali szarości. W pełni nieprzezroczysty stempel renderuje się na czarno.

Zakres

Silnik stosuje numerację Batesa dokładnie tak, jak skonfigurowano. Nie twierdzi, że ponumerowany dokument jest dopuszczalny w sądzie ani ważny prawnie. Schemat numeracji, przechowywanie oraz obsługa dowodowa pozostają obowiązkiem klienta; w sprawie wystarczalności proceduralnej skonsultuj się z własnymi zespołami prawnymi i ds. zgodności.

Przypadki brzegowe i tryby awarii

generateStreams nigdy nie zgłasza wyjątku przy niezgodności pageSizes. Brakujący wpis używa domyślnie A4 pionowo, 595.276 na 841.890 punktów; nadmiarowe wpisy są ignorowane.
Liczba fragmentów zawsze równa się pageCount.
Liczba szersza niż padding nie jest obcinana; tekst stempla po prostu się wydłuża.
getRange zakłada pageCount >= 1. Liczba 0 formatuje indeks strony -1, czyli startNumber - 1.
Krycie to rozjaśnienie w skali szarości, a nie przezroczystość ExtGState; treść nachodząca pod stemplem nie jest mieszana (blended).
Bajty stempla inne niż \, ( oraz ) przechodzą bez kodowania. Poprawność kodowania tekstu spoza ASCII zależy od powiązanej czcionki.
Znaki Batesa to treść nakładkowa. Nie maskują, nie usuwają ani nie szyfrują niczego na stronie.
Moduł nie wykonuje żadnych operacji kryptograficznych; tryb FIPS nie zmienia jego zachowania.

Zgodność ze standardami

Zachowanie	Odniesienie	Status
Ujmowanie warstwy za pomocą operatorów treści oznaczonej `BDC`/`EMC`	ISO 32000-2:2020 §8.11.3.2	Częściowe — fragment emituje ujmowanie; zarejestrowanie grupy treści opcjonalnej jest krokiem modułu zapisującego, który dokonuje osadzenia

Te wiersze rejestrują specyfikację, względem której zbudowano moduł, a nie certyfikację; NextPDF nie posiada żadnego certyfikatu zgodności. Tabela nie jest również oświadczeniem o ważności prawnej ani wystarczalności dowodowej.

Uwagi programistyczne

Fragmenty to czyste wartości łańcuchowe. Testuj je przez bezpośrednie porównanie bajtów; kontekst dokumentu nie jest wymagany.
buildPageStream jest publiczna i można ją testować jednostkowo w izolacji: przekaż wstępnie sformatowany tekst i jawne wymiary strony.
W przypadku numeracji kontynuowanej między produkcjami dokumentów zainicjuj startNumber z poprzedniego przebiegu i zapisz wynik getRange w dzienniku produkcji.
Nazwy warstw są oczyszczane do znaków słowa. Preferuj nazwy warstw w ASCII, aby nazwa treści oznaczonej pozostała czytelna w narzędziach inspekcyjnych.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.