Tạo các lớp nội dung tùy chọn (OCG)

Tổng quan nhanh

Bọc nội dung trong các nhóm nội dung tùy chọn có tên (OCG), thường được gọi là lớp. Trình đọc PDF có thể bật/tắt từng lớp trong bảng Layers, và một lớp sẽ được ẩn theo mặc định. Công thức này dựa trên examples/26-layers.php.

OCG là từ điển nhóm nội dung tùy chọn theo ISO 32000-2 với Type /OCG. NextPDF bọc các marker phân lớp giữa BDC/EMC và dùng thẻ marked-content OC.

Cài đặt

composer require nextpdf/core:^3

Bạn không cần tiện ích mở rộng tùy chọn nào. API lớp đã ổn định từ 1.0.0 và chạy trên ma trận backport 8.1–8.4.

Tổng quan khái niệm

startLayer($name, $visible) mở một OCG. Mọi thứ bạn vẽ cho đến lệnh endLayer() tương ứng đều thuộc về nhóm đó. $name là nhãn mà trình đọc PDF hiển thị trong bảng Layers. ISO 32000-2 yêu cầu OCG phải có Name, tức chuỗi hiển thị cho người dùng. Truyền $visible: false sẽ đăng ký nhóm ở trạng thái OFF trong cấu hình mặc định, vì vậy trình đọc sẽ ẩn nhóm đó cho đến khi người dùng bật lại.

Khả năng hiển thị phụ thuộc vào việc trình đọc có tuân thủ cơ chế này hay không. Đối với từ điển thành viên nội dung tùy chọn (OCMD), chính sách hiển thị mặc định là AnyOn. Lớp sẽ hiển thị nếu bất kỳ nhóm nào được tham chiếu đang ở trạng thái ON. Một lớp ẩn chỉ được ẩn theo quy ước của trình đọc. Lớp đó không bị xóa, không được bảo vệ, và không phải là biện pháp che thông tin (redaction) hay kiểm soát an ninh. Để loại bỏ nội dung, đừng vẽ nội dung đó.

Bề mặt API

PHPDoc tự động tạo bề mặt API. Công thức này dùng hai phương thức sau:

startLayer(string $name, bool $visible = true): static — mở một OCG có tên; $visible: false khiến lớp đó ẩn theo mặc định.
endLayer(): static — đóng lớp được mở gần nhất (cân bằng với startLayer()).

Ví dụ mã — bắt đầu nhanh

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

Ví dụ mã — bản dùng cho production

Hãy dùng ví dụ đầy đủ, sẵn sàng cho harness này. Ví dụ này tôn trọng NEXTPDF_COOKBOOK_OUTPUT và không tự thêm bất kỳ yếu tố ngẫu nhiên nào.

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

Trường hợp đặc biệt & điểm cần lưu ý

Cân bằng mỗi startLayer() bằng một endLayer(). Một lớp chưa đóng sẽ để lại một BDC lửng lơ không có EMC và làm hỏng cấu trúc tài liệu. Hãy ghép mỗi lệnh mở với lệnh đóng tương ứng.
Một lớp ẩn không bị xóa. visible: false chỉ ẩn nội dung theo quy ước của trình đọc. Các marker và mọi văn bản vẫn còn trong tệp và có thể khôi phục được. Đây không phải là che thông tin (redaction). Với dữ liệu nhạy cảm, đừng vẽ dữ liệu đó.
Mức hỗ trợ bảng lớp khác nhau tùy trình đọc. Việc bật/tắt cần một trình đọc có hỗ trợ nội dung tùy chọn. Các luồng in và trình xem tối giản có thể luôn hiển thị, hoặc luôn ẩn, những lớp bị tắt theo mặc định.
Lồng nhau. Các lớp lồng nhau được cho phép, nhưng khả năng hiển thị của mỗi nhóm bên trong vẫn độc lập. Đừng cho rằng một lớp ngoài đang OFF sẽ ẩn một nhóm bên trong đang ON, trừ khi bạn thiết lập chính sách thành viên.

Hiệu năng

Mỗi lớp thêm một từ điển OCG và một cặp BDC/EMC bao quanh các marker của lớp đó. Chi phí phát sinh không đáng kể. Chi phí tỷ lệ với nội dung bên trong các lớp, không phải số lượng lớp, nên vẫn nằm trong giới hạn 2000 ms / 64 MB.

Ghi chú bảo mật

Khả năng hiển thị của nội dung tùy chọn là dựa vào việc trình đọc tuân thủ cơ chế này, không phải kiểm soát truy cập. Việc ẩn một lớp không mã hóa, không che thông tin, cũng không loại bỏ nội dung của lớp đó. Bất kỳ ai cũng có thể bật lại lớp đó hoặc trích xuất các byte. Đừng bao giờ dùng lớp ẩn để che giấu văn bản bí mật; thay vào đó, hãy bỏ hẳn nội dung đó. Công thức này không phân tích bất kỳ đầu vào nào và không thực hiện yêu cầu mạng nào.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Một từ điển OCG có `Type /OCG`.	ISO 32000-2	§8.11.2
Mục `Name` của OCG là nhãn bắt buộc hiển thị cho người dùng.	ISO 32000-2	§8.11.2
Nội dung tùy chọn được bao giữa `BDC`/`EMC` với thẻ `OC`.	ISO 32000-2	§8.11.3.2
Các chính sách OCMD là AllOn/AnyOn/AnyOff/AllOff (mặc định AnyOn).	ISO 32000-2	§8.11.4.3

Hồ sơ khả năng tái lập — theo cấu trúc. /ID trong trailer và các atom ngày tháng thay đổi sau mỗi lần lưu. Harness sẽ loại bỏ các atom đó và so sánh cấu trúc đã được chuẩn hóa bằng qpdf. Công thức này mô tả cách NextPDF tạo ra cấu trúc đó. Nó không khẳng định mức tuân thủ ISO 32000-2 tổng quát.

Bối cảnh thương mại

Không áp dụng. Các nhóm nội dung tùy chọn là tính năng của Core, không bị giới hạn bởi Premium.