İsteğe bağlı içerik katmanları (OCG) oluşturma

Bir bakışta

İçeriği, genellikle katman olarak anılan adlandırılmış isteğe bağlı içerik gruplarının (OCG) içine alın. Bir PDF okuyucusu her katmanı kendi Katmanlar panelinde açıp kapatabilir; bir katman da varsayılan olarak gizli başlayabilir. Bu tarif examples/26-layers.php dosyasını temel alır.

Bir OCG, Type /OCG içeren ISO 32000-2 isteğe bağlı içerik grubu sözlüğüdür. NextPDF, katmanlı işaretli içeriği BDC/EMC arasına alır ve OC işaretli içerik etiketini kullanır.

Kurulum

composer require nextpdf/core:^3

Herhangi bir isteğe bağlı uzantıya ihtiyacınız yoktur. Katman API’si 1.0.0 sürümünden beri kararlıdır ve 8.1–8.4 geri taşıma matrisinde çalışır.

Kavramsal genel bakış

startLayer($name, $visible) bir OCG’yi açar. Eşleşen endLayer() çağrısına kadar çizdiğiniz her şey o gruba aittir. $name, PDF okuyucusunun Katmanlar panelinde gösterdiği etikettir. ISO 32000-2, kullanıcıya yönelik dize olan OCG’nin Name alanını zorunlu kılar. $visible: false değerinin geçirilmesi, grubu varsayılan yapılandırmada KAPALI duruma kaydeder; böylece okuyucu, kullanıcı onu açana kadar gizler.

Görünürlük, okuyucunun iş birliğine bağlıdır. İsteğe bağlı içerik üyelik sözlüğü (OCMD) için varsayılan görünürlük politikası AnyOn şeklindedir. Başvurulan gruplardan herhangi biri AÇIK ise katman görünür olur. Gizli bir katman yalnızca okuyucunun bu davranışa uymasıyla gizli kalır. Kaldırılmaz veya korunmaz; redaksiyon da güvenlik denetimi de değildir. İçeriği kaldırmanız gerekiyorsa onu hiç çizmeyin.

API yüzeyi

API yüzeyi PHPDoc tarafından otomatik olarak oluşturulur. Bu tarifte şu iki yöntem kullanılır:

startLayer(string $name, bool $visible = true): static — adlandırılmış bir OCG’yi açar; $visible: false onu varsayılan olarak gizli yapar.
endLayer(): static — en son açılan katmanı kapatır (startLayer() ile dengeli olacak şekilde).

Kod örneği — hızlı başlangıç

<?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');

Kod örneği — üretim

Eksiksiz ve test koşumuna hazır bu örneği kullanın. NEXTPDF_COOKBOOK_OUTPUT değişkenini dikkate alır ve kendisi hiçbir entropi eklemez.

<?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";

Uç durumlar ve dikkat edilecek noktalar

Her startLayer() çağrısını bir endLayer() ile dengeleyin. Kapatılmamış bir katman, arkada kapanmamış bir BDC bırakır; onu sonlandıracak bir EMC bulunmaz ve bu da belge yapısını bozar. Her açılış çağrısını kendi kapanış çağrısıyla eşleştirin.
Gizli bir katman kaldırılmaz. visible: false içeriği yalnızca okuyucunun bu davranışa uymasıyla gizler. İşaretler ve her türlü metin dosyada kalır ve kurtarılabilir. Bu bir redaksiyon değildir. Hassas veriler için bu içeriği hiç çizmeyin.
Katman paneli desteği değişkenlik gösterir. Katmanları açıp kapatmak, isteğe bağlı içeriği sunan bir okuyucu gerektirir. Yazdırma işlem hatları ve sade görüntüleyiciler, varsayılan olarak kapalı katmanları her zaman gösterebilir ya da her zaman gizleyebilir.
İç içe yerleştirme. İç içe katmanlara izin verilir, ancak her iç grubun görünürlüğü bağımsız kalır. Bir üyelik politikası ilişkilendirmediğiniz sürece, dıştaki KAPALI bir katmanın içteki AÇIK bir grubu gizlediğini varsaymayın.

Performans

Her katman, bir OCG sözlüğü ekler ve işaretlerinin etrafına bir BDC/EMC çifti yerleştirir. Ek yük ihmal edilebilir düzeydedir. Maliyet, katman sayısıyla değil katmanların içindeki içerikle ölçeklenir; bu nedenle 2000 ms / 64 MB bütçesinin oldukça altında kalır.

Güvenlik notları

İsteğe bağlı içerik görünürlüğü okuyucunun iş birliğine bağlıdır, bir erişim denetimi değildir. Bir katmanı gizlemek, içeriğini şifrelemez, redakte etmez veya kaldırmaz. Herkes katmanı yeniden etkinleştirebilir veya baytları çıkarabilir. Gizli metin saklamak için asla gizlenmiş bir katman kullanmayın; bunun yerine içeriği tamamen dışarıda bırakın. Bu tarif hiçbir girdiyi ayrıştırmaz ve hiçbir ağ isteği yapmaz.

Uygunluk

İfade	Belirtim	Madde
Bir OCG sözlüğünde `Type /OCG` bulunur.	ISO 32000-2	§8.11.2
OCG `Name` alanı, zorunlu olan kullanıcıya yönelik etikettir.	ISO 32000-2	§8.11.2
İsteğe bağlı içerik, `BDC`/`EMC` arasına `OC` etiketiyle alınır.	ISO 32000-2	§8.11.3.2
OCMD politikaları AllOn/AnyOn/AnyOff/AllOff şeklindedir (varsayılan AnyOn).	ISO 32000-2	§8.11.4.3

Yeniden üretilebilirlik profili — yapısal. Fragman (trailer) /ID alanı ve tarih atomları her kayıtta değişir. Test koşumu bu atomları ayıklar ve qpdf ile normalleştirilmiş yapıyı karşılaştırır. Bu tarif, NextPDF uygulamasının bu yapıyı nasıl ürettiğini açıklar. Genel ISO 32000-2 uygunluğunu iddia etmez.

Ticari bağlam

Geçerli değildir. İsteğe bağlı içerik grupları, Premium kapısı olmayan bir Core yeteneğidir.