Optionale Inhaltsebenen (OCG) erstellen

Auf einen Blick

Fassen Sie Inhalte in benannte optionale Inhaltsgruppen (OCGs), üblicherweise Ebenen genannt, zusammen. Der Reader kann jede Ebene in seinem Ebenen-Panel ein- und ausschalten; eine Ebene ist standardmäßig ausgeblendet. Dieses Recipe folgt examples/26-layers.php.

Eine OCG ist ein Wörterbuch für eine optionale Inhaltsgruppe nach ISO 32000-2 mit Type /OCG. NextPDF umschließt die einer Ebene zugeordneten Inhalte zwischen BDC/EMC mit dem Marked-Content-Tag OC.

Installation

composer require nextpdf/core:^3

Es ist keine optionale Erweiterung erforderlich. Die Ebenen-API ist seit 1.0.0 stabil und läuft auf der Backport-Matrix 8.1–8.4.

Konzeptioneller Überblick

startLayer($name, $visible) öffnet eine OCG. Alles, was bis zum zugehörigen endLayer() gezeichnet wird, gehört zu dieser Gruppe. $name ist die Beschriftung, die der Reader in seinem Ebenen-Panel anzeigt. ISO 32000-2 verlangt, dass der Name einer OCG eine erforderliche, für Nutzer sichtbare Zeichenkette ist. Wenn Sie $visible: false übergeben, wird die Gruppe in der Standardkonfiguration im AUS-Zustand registriert, sodass der Reader sie ausblendet, bis der Nutzer sie einschaltet.

Die Sichtbarkeit setzt die Kooperation des Readers voraus. Die Standardrichtlinie für die Sichtbarkeit eines Mitgliedschaftswörterbuchs ist AnyOn; das bedeutet, dass die Ebene sichtbar ist, wenn mindestens eine referenzierte Gruppe EIN ist. Eine ausgeblendete Ebene ist nur nach Reader-Konvention ausgeblendet. Sie wird weder entfernt noch geschützt; sie ist weder eine Schwärzung noch eine Sicherheitsmaßnahme. Um Inhalte zu entfernen, zeichnen Sie sie nicht.

API-Oberfläche

Die API-Oberfläche wird automatisch aus PHPDoc generiert. Dieses Recipe verwendet die folgenden beiden Methoden:

startLayer(string $name, bool $visible = true): static — öffnet eine benannte OCG; $visible: false blendet sie standardmäßig aus.
endLayer(): static — schließt die zuletzt geöffnete Ebene (als Gegenstück zu startLayer()).

Code-Beispiel — Schnellstart

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->startLayer('Content', visible: true);
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Always-visible body content.', newLine: true);
$doc->endLayer();

$doc->startLayer('Debug Grid', visible: false); // hidden until toggled
$doc->setDrawColor(200, 200, 200);
for ($x = 0.0; $x <= 210.0; $x += 10.0) {
    $doc->line($x, 0, $x, 297);
}
$doc->endLayer();

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/layers.pdf');

Code-Beispiel — Produktion

Dies ist das vollständige, Harness-fertige Beispiel. Es berücksichtigt NEXTPDF_COOKBOOK_OUTPUT und setzt keine eigene Entropie fest.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Layer Examples (OCG)');
$doc->addPage();

// Layer 1 — background, visible by default.
$doc->startLayer('Background', visible: true);
$doc->setFillColor(230, 240, 250);
$doc->rect(10, 10, 190, 277, 'F');
$doc->endLayer();

// Layer 2 — watermark, visible by default; can be toggled off.
$doc->startLayer('Watermark', visible: true);
$doc->setFont('helvetica', 'B', 54);
$doc->setTextColor(200, 200, 200);
$doc->startTransform();
$doc->rotate(45, 105, 148);
$doc->setXY(30, 135);
$doc->cell(150, 20, 'DRAFT', align: Alignment::Center);
$doc->stopTransform();
$doc->endLayer();

// Layer 3 — main content, visible by default.
$doc->startLayer('Content', visible: true);
$doc->setTextColor(0);
$doc->setFont('helvetica', 'B', 20);
$doc->setXY(10, 15);
$doc->cell(0, 14, 'Layer Examples (OCG)', newLine: true);
$doc->ln(4);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This document contains four optional content groups. '
    . "Toggle them in your reader's Layers panel.");
$doc->endLayer();

// Layer 4 — debug grid, hidden by default.
$doc->startLayer('Debug Grid', visible: false);
$doc->setDrawColor(180, 180, 180);
$doc->setLineWidth(0.15);
for ($x = 0.0; $x <= 210.0; $x += 10.0) {
    $doc->line($x, 0, $x, 297);
}
for ($y = 0.0; $y <= 297.0; $y += 10.0) {
    $doc->line(0, $y, 210, $y);
}
$doc->endLayer();

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/layers.pdf';
$doc->save($out);

echo "Created layers.pdf\n";

Grenzfälle & Fallstricke

Gleichen Sie jedes startLayer() mit einem endLayer() aus. Eine nicht geschlossene Ebene hinterlässt ein hängendes BDC ohne EMC, wodurch die Dokumentstruktur fehlerhaft wird. Stellen Sie jedem öffnenden Aufruf den zugehörigen schließenden Aufruf gegenüber.
Eine ausgeblendete Ebene wird nicht entfernt. visible: false blendet den Inhalt nur nach Reader-Konvention aus. Die Markierungen und jeglicher Text bleiben weiterhin in der Datei und sind wiederherstellbar. Dies ist keine Schwärzung. Zeichnen Sie sensible Daten nicht.
Die Unterstützung des Ebenen-Panels variiert. Das Umschalten setzt einen Reader voraus, der optionale Inhalte verfügbar macht. Druck-Pipelines und minimale Viewer zeigen standardmäßig ausgeschaltete Ebenen womöglich immer an oder blenden sie immer aus.
Verschachtelung. Verschachtelte Ebenen sind erlaubt, aber die Sichtbarkeit jeder inneren Gruppe bleibt weiterhin unabhängig. Gehen Sie nicht davon aus, dass eine äußere, ausgeschaltete Ebene eine innere, eingeschaltete Gruppe ausblendet, sofern Sie keine Mitgliedschaftsrichtlinie verdrahten.

Performance

Jede Ebene fügt ein OCG-Wörterbuch sowie ein BDC/EMC-Paar um ihre Inhalte hinzu. Dieser Overhead ist vernachlässigbar. Die Kosten skalieren mit dem Inhalt innerhalb der Ebenen, nicht mit der Anzahl der Ebenen; damit bleibt dies deutlich innerhalb des Budgets von 2000 ms / 64 MB.

Sicherheitshinweise

Die Sichtbarkeit optionaler Inhalte setzt die Kooperation des Readers voraus; sie ist keine Zugriffskontrolle. Das Ausblenden einer Ebene verschlüsselt, schwärzt oder entfernt ihren Inhalt nicht. Jeder kann die Ebene wieder einschalten oder die Bytes extrahieren. Verwenden Sie niemals eine ausgeblendete Ebene, um vertraulichen Text zu verbergen; lassen Sie den Inhalt stattdessen vollständig weg. Dieses Recipe führt kein Eingabeparsing durch und greift nicht auf das Netzwerk zu.

Konformität

Aussage	Spezifikation	Abschnitt
Ein OCG-Wörterbuch hat `Type /OCG`.	ISO 32000-2	§8.11.2
Der `Name` einer OCG ist eine erforderliche, für Nutzer sichtbare Beschriftung.	ISO 32000-2	§8.11.2
Optionaler Inhalt wird zwischen `BDC`/`EMC` mit dem `OC`-Tag eingeschlossen.	ISO 32000-2	§8.11.3.2
OCMD-Richtlinien sind AllOn/AnyOn/AnyOff/AllOff (Standard AnyOn).	ISO 32000-2	§8.11.4.3

Reproduzierbarkeitsprofil — strukturell. Die /ID im Trailer sowie die Datumsatome ändern sich bei jedem Speichern. Das Harness entfernt diese Atome und vergleicht die qpdf-normalisierte Struktur. Dieses Recipe beschreibt, wie NextPDF diese Struktur erzeugt. Es erhebt keinen Anspruch auf allgemeine Konformität mit ISO 32000-2.

Kommerzieller Kontext

Nicht zutreffend. Optionale Inhaltsgruppen sind eine Core-Fähigkeit ohne Premium-Gate.