Thêm liên kết và chú thích văn bản

Tổng quan nhanh

Dùng công thức này để thêm ba thành phần tương tác: một liên kết nội bộ nhảy sang trang khác, một liên kết bên ngoài mở Uniform Resource Locator (URL) và một chú thích văn bản, còn gọi là ghi chú dán. Công thức này dựa trên examples/17-links.php và examples/29-annotations.php.

Liên kết có thể nhấp là một chú thích liên kết theo ISO 32000-2: một liên kết siêu văn bản đến một đích đến hoặc một hành động. Ghi chú dán là một chú thích văn bản. Nó hiển thị dưới dạng biểu tượng khi đóng và dưới dạng cửa sổ bật lên khi mở.

Cài đặt

composer require nextpdf/core:^3

Không cần bất kỳ phần mở rộng tùy chọn nào. Giao diện lập trình ứng dụng (API) cho liên kết và chú thích đã ổn định kể từ 1.0.0 và hỗ trợ ma trận backport 8.1–8.4.

Tổng quan khái niệm

Liên kết nội bộ dùng mẫu gồm ba lệnh gọi và hỗ trợ tham chiếu tới phía trước:

addLink() đặt trước một mã định danh liên kết (một int).
link($x, $y, $w, $h, $id) đặt một hình chữ nhật có thể nhấp gắn với id đó.
setLink($id, $pageIndex, $y) gắn id với một trang đích (đánh số từ không) và Y.

Hãy gọi bước 3 sau bước 2 khi bạn liên kết đến một trang chưa tồn tại. Đích đến sử dụng dạng tường minh. ISO 32000-2 §12.3.2.2 định nghĩa [page /XYZ left top zoom], trong đó thành phần null sẽ giữ nguyên giá trị hiện tại của trình đọc.

Với liên kết bên ngoài, hãy truyền một chuỗi URL vào link() thay vì một int. Khi đó, NextPDF phát ra một hành động Uniform Resource Identifier (URI) mà URI của nó là một chuỗi ASCII UTF-8 bắt buộc. Để viết gọn, write($height, $text, $link) vẽ văn bản nội dòng kèm một URL đi kèm, còn annotation($x, $y, $w, $h, $text) đặt một ghi chú dán thuộc kiểu con Text. ISO 32000-2 yêu cầu SubtypeLink đối với một chú thích liên kết và định nghĩa biểu tượng cùng hành vi cửa sổ bật lên của chú thích văn bản.

Bề mặt API

Bề mặt API được sinh từ PHPDoc. Công thức này dựa trên các phương thức sau:

addLink(): int — đặt trước một mã định danh liên kết nội bộ.
setLink(int $linkId, int $pageIndex = -1, float $y = 0): static — gắn một id đến một trang đích (đánh số từ không) và Y.
link(float $x, float $y, float $w, float $h, string|int $link): static — tạo một hình chữ nhật có thể nhấp; id kiểu int là liên kết nội bộ, còn chuỗi là URL bên ngoài.
write(float $height, string $text, string $link = ''): static — viết văn bản nội dòng với một URL tùy chọn.
annotation(float $x, float $y, float $w, float $h, string $text, string $subtype = 'Text'): static — thêm một chú thích ghi chú dán.

Mã mẫu — bắt đầu nhanh

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$jump = $doc->addLink();             // 1. reserve an id (forward reference)

$doc->addPage();
$doc->setFont('helvetica', 'B', 12);
$x = $doc->getX();
$y = $doc->getY();
$doc->cell(60, 10, 'Go to page 2', newLine: true);
$doc->link($x, $y, 60, 10, $jump);   // 2. clickable rectangle -> id

$doc->link($doc->getX(), $doc->getY(), 80, 10, 'https://nextpdf.dev'); // external

$doc->addPage();
$doc->setLink($jump, pageIndex: 1, y: 0); // 3. bind id to page 2 (index 1)
$doc->cell(0, 10, 'Destination (page 2).', newLine: true);
$doc->annotation(x: 180, y: 20, w: 10, h: 10, text: 'A reviewer note.');

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

Mã mẫu — sản xuất

Ví dụ dưới đây hoàn chỉnh và sẵn sàng cho khung kiểm thử. Nó tôn trọng NEXTPDF_COOKBOOK_OUTPUT và không tự thêm bất kỳ độ ngẫu nhiên nào.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Links and Annotations');

// Reserve the internal-link id before its destination page exists.
$linkToPage3 = $doc->addLink();

// Page 1 — source of the internal and external links.
$doc->addPage();
$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Links and Annotations', newLine: true);
$doc->ln(6);

$doc->setFont('helvetica', 'B', 12);
$doc->setTextColor(0, 51, 153);
$linkX = $doc->getX();
$linkY = $doc->getY();
$doc->cell(60, 10, 'Go to Page 3', newLine: true);
$doc->link($linkX, $linkY, 60, 10, $linkToPage3); // internal: int id
$doc->setTextColor(0);
$doc->ln(6);

$doc->setFont('helvetica', 'B', 12);
$doc->setTextColor(0, 102, 204);
$doc->write(10, 'Visit https://nextpdf.dev', link: 'https://nextpdf.dev');
$doc->setTextColor(0);
$doc->ln(6);

$urlX = $doc->getX();
$urlY = $doc->getY();
$doc->cell(80, 10, 'NextPDF on GitHub', newLine: true);
$doc->link($urlX, $urlY, 80, 10, 'https://github.com/nextpdf-labs/nextpdf');

// Page 2 — intermediate.
$doc->addPage();
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Internal links can jump across pages; this page is '
    . 'skipped by the link on page 1.');

// Page 3 — destination + a sticky note.
$doc->addPage();
$doc->setLink($linkToPage3, pageIndex: 2, y: 0); // bind id to page 3 (index 2)
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 14, 'Page 3 — Link Target', newLine: true);
$doc->ln(4);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'You arrived via the internal link on page 1.');
$doc->annotation(
    x: 185, y: 40, w: 10, h: 10,
    text: 'Sticky note: appears as an icon; click to read this text.',
);

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

echo "Created links.pdf\n";

Trường hợp biên và điểm cần lưu ý

pageIndex được đánh số từ không. setLink($id, pageIndex: 2, …) nhắm tới trang thứ ba. Sai lệch một đơn vị ở đây là lỗi phổ biến nhất.
String và int trong link(). Một int là id đích đến nội bộ từ addLink(). Một chuỗi là URL bên ngoài. Nếu truyền sai kiểu, bạn sẽ nhận được loại liên kết sai mà không có lỗi nào được báo.
Hãy gắn mọi id đã đặt trước. Một id từ addLink() mà bạn không bao giờ gắn bằng setLink() thì không có đích đến. Hình chữ nhật có thể nhấp nhưng không có tác dụng. Hãy gắn id đó trước save().
Vùng có thể nhấp là hình chữ nhật, không phải văn bản. link() nhận x, y, w, h tường minh. Hãy định kích thước cho nó để bao phủ phần văn bản hiển thị. Engine không đo glyph giúp bạn.
Liên kết bên ngoài không được xác thực. NextPDF lưu URI nguyên văn. Nó không kiểm tra xem đích đến có phân giải được hay có an toàn không. Trình đọc sẽ phân giải nó.

Hiệu năng

Mỗi liên kết hoặc chú thích thêm một từ điển chú thích vào trang. Chi phí là O(1) cho mỗi thành phần. Hàng trăm thành phần trên mỗi trang vẫn dễ dàng nằm trong ngân sách 2000 ms / 64 MB.

Ghi chú bảo mật

Đích đến của liên kết bên ngoài được lưu nguyên văn và do trình đọc phân giải, không phải thư viện. Hãy coi các URL do người dùng cung cấp là không đáng tin cậy. Hãy đưa scheme vào danh sách cho phép, thường là https. Hãy từ chối javascript: và file: trước khi truyền chúng vào link(). Văn bản chú thích xuất hiện trong giao diện người dùng (UI) của trình đọc, vì vậy hãy giới hạn độ dài và làm sạch nội dung ghi chú do người dùng kiểm soát. Công thức này không thực hiện phân tích đầu vào hay truy cập mạng.

Mức độ tuân thủ

Phát biểu	Đặc tả	Điều khoản
Một chú thích liên kết là một liên kết siêu văn bản đến một đích đến hoặc một hành động.	ISO 32000-2	§12.5.6.5
`Subtype` là `Link` đối với một chú thích liên kết.	ISO 32000-2	§12.5.6.5
Trường `URI` của một hành động URI là một chuỗi ASCII UTF-8 bắt buộc.	ISO 32000-2	§12.6.4.8
Một chú thích văn bản là một ghi chú dán (đóng = biểu tượng, mở = cửa sổ bật lên).	ISO 32000-2	§12.5.6.4
Đích đến tường minh `[page /XYZ left top zoom]`; null giữ nguyên giá trị hiện tại.	ISO 32000-2	§12.3.2.2

Hồ sơ khả tái lập — cấu trúc. Trường /ID trong trailer và các thành phần ngày tháng thay đổi sau mỗi lần lưu. Khung kiểm thử loại bỏ các thành phần đó rồi so sánh cấu trúc đã được qpdf chuẩn hóa. Công thức này mô tả cách NextPDF tạo cấu trúc. Nó không khẳng định việc tuân thủ ISO 32000-2 như một tuyên bố bao trùm.

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

Không áp dụng. Liên kết và chú thích văn bản là các tính năng Core, không bị giới hạn bởi Premium.