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	—	Все одиннадцать свойств публичные и readonly.
BatesNumberConfig::formatNumber	int $pageIndex (с нуля)	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 portrait	Число фрагментов равно 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	X/Y базовой линии штампа в PDF-нативном пространстве	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, где несловесные символы заменены подчёркиваниями. Заключение в скобки происходит только на уровне фрагмента: регистрация соответствующей группы опционального содержимого в документе — шаг, который делает слой переключаемым в просмотрщике, — относится к встраивающему писателю.

Непрозрачность

opacity ниже 1.0 выводится как более светлая заливка в оттенках серого. Полностью непрозрачный штамп отображается чёрным.

Область применения

Движок применяет нумерацию Bates ровно так, как настроено. Он не утверждает, что нумерованный документ допустим в суде или юридически действителен. Схема нумерации, хранение и обращение с доказательствами остаются ответственностью заказчика; проконсультируйтесь со своими юридическими командами и командами по соответствию относительно процедурной достаточности.

Граничные случаи и режимы отказа

• generateStreams никогда не выбрасывает исключение при несоответствии pageSizes. Отсутствующая запись откатывается к A4 portrait, 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 в журнал передачи.
• Имена слоёв санируются до словесных символов. Предпочитайте ASCII-имена слоёв, чтобы имя маркированного содержимого оставалось читаемым в инструментах инспекции.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области рассмотрения.

См. также

• Обзор возможности Legal
• Merge — глубокий справочник
• Security — глубокий справочник