Common — szczegółowa referencja

W skrócie

Ta strona jest pełną dokumentacją referencyjną przestrzeni nazw NextPDF\Enterprise\Common. Przestrzeń nazw udostępnia jeden symbol publiczny: obiekt wartości BoundingBox. Jest to niemutowalny, znormalizowany prostokąt do niezależnego od rozdzielczości pozycjonowania przestrzennego na stronie. Powierzchnie Enterprise Intelligence i Privacy korzystają z niego dla geometrii komórek tabel, lokalizacji encji oraz stref redakcji. Moduł nie wykonuje żadnych operacji wejścia/wyjścia, nie przechowuje treści dokumentu i nie dotyka kryptografii. Wskazówki dotyczące przepływu pracy znajdziesz najpierw na stronie możliwości Common.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Sam prymityw nie wykonuje żadnego bramkowania licencji; bramkowanie odbywa się na powierzchniach Enterprise, które go wykorzystują. Nie istnieje odpowiednik tej klasy na poziomie Core ani Pro. Jest dostarczany wyłącznie w pakiecie nextpdf/enterprise i nie powiela ani nie zastępuje typów geometrii Core.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
BoundingBox::__construct	float $x, float $y, float $width, float $height	Waliduje każdą wartość względem [0.0, 1.0], następnie waliduje obie sumy krawędzi	BoundingBox	InvalidArgumentException, gdy wartość jest poza zakresem lub suma krawędzi przekracza 1.0 + 1e-9	Wszystkie cztery wartości stają się właściwościami public readonly
BoundingBox::area	brak	Mnoży width przez height	float	Nic zadeklarowanego	Zwraca 0.0 dla zdegenerowanych ramek
BoundingBox::contains	self $other	Sprawdza, czy $other leży w całości wewnątrz tej ramki	bool	Nic zadeklarowanego	Prawa i dolna krawędź tolerują +1e-9; lewa i górna krawędź porównywane są dokładnie
BoundingBox::overlaps	self $other	Sprawdza ścisłe przecięcie prostokątów	bool	Nic zadeklarowanego	Operand o zerowym polu po dowolnej stronie zwraca false

Sygnatura punktu wejścia

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

Kontrakt zachowania

Model współrzędnych

• Wszystkie cztery wartości są ułamkami wymiarów strony, znormalizowanymi do zakresu [0.0, 1.0].
• x wyznacza lewą krawędź, a y górną krawędź ramki. x + width i y + height ograniczają prawą i dolną krawędź.
• Normalizacja sprawia, że każda operacja jest niezależna od rozdzielczości. Ta sama ramka adresuje ten sam obszar strony przy dowolnym rozmiarze renderowania lub DPI.

Konstrukcja

• Konstruktor jest jedynym punktem walidacji. Współrzędna poza [0.0, 1.0] zgłasza InvalidArgumentException; komunikat nazywa wadliwy składnik i otrzymaną wartość.
• Suma krawędzi powyżej 1.0 + 1e-9 zgłasza InvalidArgumentException; komunikat raportuje oba operandy i ich sumę. Tolerancja 1e-9 absorbuje zaokrąglenia zmiennoprzecinkowe z wcześniejszej arytmetyki normalizacji.
• Skonstruowana instancja jest niemutowalna. Klasa jest final readonly, więc zapisy do właściwości kończą się błędem PHP Error, a klasy nie można rozszerzyć.

Predykaty

• area() zwraca width * height. Jest to czyste obliczenie bez efektów ubocznych.
• contains() zwraca true, gdy druga ramka leży w całości wewnątrz tej ramki. Porównania prawej i dolnej krawędzi niosą tolerancję +1e-9; porównania lewej i górnej krawędzi są dokładne. Każda ramka zawiera samą siebie, a ramka o zerowym polu może być zawarta.
• overlaps() zwraca true przy ścisłym przecięciu prostokątów. Wszystkie cztery porównania krawędzi są ścisłe, bez tolerancji. Jeśli którykolwiek z operandów ma zerowe pole, wynikiem jest false.
• Zawieranie nie implikuje więc nakładania: zdegenerowana ramka wewnątrz innej ramki jest zawarta, ale nigdy się nie nakłada.
• Żadna metoda nie wykonuje operacji wejścia/wyjścia, trwałego przechowywania, dostępu do sieci ani logowania i żadna nie przechowuje treści dokumentu ani danych osobowych. Dla tej powierzchni nie istnieje żaden zasób będący w gestii operatora.

Konsumenci

Moduły Enterprise współdzielą ten prymityw, zamiast definiować geometrię osobno dla każdego modułu. W Intelligence wynik TableExtractor niesie go na wartościach TableCell i KeyValuePair. W Privacy PiiEntity, RedactionFinding i ZoneRedaction lokalizują treść za jego pomocą, a RedactionEngine konsumuje te lokalizacje. Kontrakty tych powierzchni są udokumentowane na ich własnych stronach referencyjnych.

Przypadki brzegowe i tryby niepowodzenia

• Składnik poza zakresem. Którakolwiek z czterech wartości poniżej 0.0 lub powyżej 1.0 zgłasza InvalidArgumentException podczas konstrukcji. INF i -INF są odrzucane przez to samo zabezpieczenie.
• Przepełnienie sumy krawędzi. x + width lub y + height powyżej 1.0 + 1e-9 zgłasza InvalidArgumentException. Suma mieszcząca się w tolerancji 1e-9 konstruuje się poprawnie.
• Wejście NAN. Zabezpieczenie zakresu używa uporządkowanych porównań, a każde uporządkowane porównanie z NAN jest fałszywe, więc składnik NAN nie jest odrzucany. Taka instancja raportuje pole NAN i zwraca false z obu predykatów. Sanityzuj źródła zmiennoprzecinkowe przed konstrukcją.
• Ramki o zerowym polu. Ramka o zerowej szerokości lub zerowej wysokości nigdy się z niczym nie nakłada, w tym z samą sobą. Nadal może być zawarta przez ramkę niezdegenerowaną. Uwzględnij tę asymetrię w logice przecięcia.
• Ramki stykające się krawędziami. Dwie ramki, które dzielą jedynie krawędź lub róg, nie nakładają się; test przecięcia jest ścisły.
• Asymetria tolerancji zawierania. Wewnętrzna ramka, której lewa lub górna krawędź leży poza ramką zewnętrzną o dowolną wartość, nie przechodzi testu zawierania; tylko prawa i dolna krawędź otrzymują margines 1e-9.
• Tryb FIPS. Ten moduł nie wykonuje żadnych operacji kryptograficznych; tryb FIPS nie zmienia jego zachowania.

Zgodność

Ten moduł nie implementuje żadnego standardu normatywnego i nie formułuje żadnego twierdzenia o zgodności. Jest to zwalidowany prymityw geometryczny. Semantyka przestrzeni współrzędnych PDF dla funkcji, które go wykorzystują, jest udokumentowana na stronach tych funkcji. NextPDF nie posiada żadnej certyfikacji i żadnej nie przyznaje; wsparcie nie jest zgodnością, a zgodność nie jest certyfikacją. Do tej powierzchni nie ma zastosowania żadne ograniczenie kontroli eksportu, a niniejsza dokumentacja nie stanowi opinii prawnej.

Uwagi programistyczne

• Klasa jest dostępna od wersji nextpdf/enterprise 2.2.0; jej powierzchnia publiczna pozostaje niezmieniona w 3.1.0.
• Przekształć bezwzględne współrzędne przestrzeni strony na ułamki względne wobec strony przed konstrukcją. Klasa waliduje zakres, nie semantykę; nie potrafi wykryć wiarygodnego, lecz błędnego obszaru.
• Instancje są zwykłymi obiektami wartości i są tanie w konstrukcji. Nie łącz ich w pule ani nie buforuj.
• Dwie instancje o identycznych współrzędnych są równe przy równości luźnej (==); ścisła tożsamość (===) je rozróżnia. W testach preferuj porównanie współrzędnych.
• Dla geometrii wykraczającej poza predykaty logiczne wyprowadź krawędzie z właściwości publicznych: prawa krawędź x + width, dolna krawędź y + height.
• Testując granice tolerancji, sprawdzaj obie strony 1e-9 na zabezpieczeniu sumy krawędzi oraz na porównaniach prawej/dolnej krawędzi zawierania.

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.

Zobacz także

• Strona możliwości Common
• Intelligence — pełna dokumentacja referencyjna
• Privacy — pełna dokumentacja referencyjna
• Validation — pełna dokumentacja referencyjna
• Evidence — szczegółowa referencja