Hỗ trợ tạo hình chữ phức tạp

Tổng quan nhanh

Bản xem trước opt-in. Việc tạo hình chữ phức tạp mặc định tắt. Khi nó tắt, engine kết xuất qua đường codepoint-tới-cmap hiện có — byte-identical với một bản build không có tính năng này. Chỉ bật nó khi bạn có libharfbuzz và một font có khả năng tạo hình, và hãy kiểm chứng kết quả.

Trình kết xuất HTML bổ sung một bộ tạo hình chữ phức tạp opt-in cho Tibetan và Mongolian. Khi bộ tạo hình bật, một run Tibetan hoặc Mongolian trong phạm vi được phát hiện sẽ được tạo hình qua libharfbuzz và phát ra dưới dạng mã glyph Identity-H. Bộ tạo hình bao phủ Tibetan nằm ngang trong các face TrueType và CFF/OTTO, kể cả xuống dòng, và Mongolian dọc đặt từ trên xuống dưới (TTB).

Cài đặt

composer require nextpdf/core:^3

Bộ tạo hình đi kèm gói core. Tùy chọn opt-in CssFeatureFlags::$complexTextShaping là @since 6.1.0. libharfbuzz là một yêu cầu lúc chạy khi cờ bật — bộ tạo hình gọi vào libharfbuzz qua phần mở rộng FFI của PHP. Khi cờ tắt, thư viện không có phụ thuộc libharfbuzz nào.

Tổng quan khái niệm

Các hệ chữ phức tạp sắp xếp lại, thay thế, và đặt lại vị trí các glyph theo ngữ cảnh. Một ánh xạ codepoint-tới-glyph ngây thơ kết xuất chúng sai một cách thấy rõ. Bộ tạo hình trao một run trong phạm vi cho libharfbuzz, vốn áp dụng các bảng tạo hình OpenType của font, và engine phát ra chuỗi glyph kết quả dưới dạng một font composite Type 0 với mã hóa Identity-H (ISO 32000-2 §9.7.4 — chuỗi hiển thị là các CID hai byte).

Phạm vi được chủ ý giới hạn. Bộ tạo hình nhận ra các run Tibetan và Mongolian rồi tạo hình chúng; nó không tuyên bố bao phủ hệ chữ phức tạp nói chung. Tibetan nằm ngang được tạo hình trong các face TrueType và CFF/OTTO, kèm xuống dòng. Mongolian được tạo hình theo chiều dọc, từ trên xuống dưới.

Ranh giới fail-closed — cứng rắn và có kiểu

Bộ tạo hình không bao giờ phát ra các glyph chưa tạo hình, vỡ hình thấy rõ làm lần dự phòng. Một run không thể tạo hình trung thực sẽ làm phát sinh một ngoại lệ có kiểu thay vào đó:

• ComplexScriptShapingException — run không thể tạo hình trung thực: font thiếu các glyph cần thiết (sẽ dẫn tới một .notdef), một face CFF được yêu cầu tạo hình trong đường dọc, run chứa một liên kết, hoặc một cột Mongolian cần xuống dòng (một trường hợp ngoài phạm vi).
• HarfBuzzUnavailableException — cờ bật nhưng libharfbuzz không tiếp cận được qua FFI lúc chạy.

Khi cờ tắt, một run trong phạm vi kết xuất qua đường codepoint-tới-cmap hiện có. Đó là một giới hạn đã ghi tài liệu, không phải một tuyên bố tạo hình: đường tắt không áp dụng tạo hình OpenType, nên các dạng theo ngữ cảnh không được bảo đảm. Đừng mô tả kết quả đường-tắt là “đã tạo hình”.

Ranh giới trung thực — tương đương khách quan, không phải duyệt thẩm mỹ

Độ trung thực tạo hình được xác thực khách quan dựa trên HarfBuzz: các định danh glyph, ánh xạ cluster, và vị trí glyph được phát ra khớp với kết quả tham chiếu của HarfBuzz (tương đương về glyph, cluster, và vị trí). Một lần duyệt thẩm mỹ bởi người bản ngữ — đánh giá liệu kết quả có đọc tự nhiên với một người đọc thành thạo hay không — là một việc theo dõi tiếp nối sau khi xuất bản. NextPDF không đưa ra tuyên bố về chất lượng ngôn ngữ nào trong API này hay trong các tài liệu này. Tương đương khách quan được khẳng định; chất lượng thẩm mỹ thì không.

Bề mặt API

Ký hiệu	Vị trí	Vai trò
CssFeatureFlags::$complexTextShaping	src/Html/CssFeatureFlags.php	Cờ opt-in cho bộ tạo hình Tibetan/Mongolian (mặc định false).
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Gắn tập cờ vào một cấu hình tài liệu.
ComplexScriptShapingException	src/Font/Shaper/ComplexScriptShapingException.php	Được ném ra khi một run trong phạm vi không thể tạo hình trung thực.
HarfBuzzUnavailableException	src/Font/Shaper/HarfBuzzUnavailableException.php	Được ném ra khi cờ bật nhưng libharfbuzz không sẵn có.

Mẫu mã — Khởi đầu nhanh

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(complexTextShaping: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>',
);
$doc->save(__DIR__ . '/tibetan.pdf');

Mẫu mã — Sản phẩm

Đăng ký một font có khả năng tạo hình, chọn vào bộ tạo hình, và xử lý hai chế độ hỏng có kiểu một cách tường minh. Một lần kết xuất trung thực hoặc một ngoại lệ rõ ràng — không bao giờ là một run glyph hỏng âm thầm.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\DocumentFactory;
use NextPDF\Exception\ComplexScriptShapingException;
use NextPDF\Exception\HarfBuzzUnavailableException;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Html\Css\CssFeatureFlags;
use NextPDF\Typography\FontRegistry;

$fontRegistry = new FontRegistry();
$fontRegistry->register('/path/to/NotoSerifTibetan-Regular.ttf', alias: 'NotoSerifTibetan');

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(complexTextShaping: true),
);

$factory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $factory->create($config);
$doc->setLanguage('bo');
$doc->addPage();

try {
    $doc->writeHtml('<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>');
} catch (HarfBuzzUnavailableException $e) {
    // The flag is on but libharfbuzz is not reachable. Install it, or turn the
    // flag off to fall back to the unshaped cmap path.
    throw $e;
} catch (ComplexScriptShapingException $e) {
    // The run cannot be shaped faithfully (missing glyphs, link in run,
    // out-of-scope case). Fix the font or the content; do not ship broken glyphs.
    throw $e;
}

$doc->save($out);

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

• libharfbuzz là bắt buộc khi bật. Khi cờ bật và libharfbuzz vắng mặt, engine ném HarfBuzzUnavailableException. Nó không âm thầm suy giảm.
• Tắt không phải là “đã tạo hình”. Khi cờ tắt, một run trong phạm vi kết xuất qua đường cmap mà không tạo hình OpenType. Đây là một giới hạn đã ghi tài liệu; đừng gọi nó là kết quả đã tạo hình.
• Phạm vi là Tibetan và Mongolian. Các hệ chữ phức tạp khác nằm ngoài phạm vi của lát cắt này.
• Một liên kết trong run thì fail closed. Một run chứa một chú thích liên kết làm phát sinh ComplexScriptShapingException, vì hình chữ nhật của liên kết không thể bám theo việc sắp xếp lại sau tạo hình.
• Không tuyên bố về chất lượng ngôn ngữ. Tương đương với HarfBuzz được khẳng định; chất lượng thẩm mỹ theo người bản ngữ là một việc theo dõi tiếp nối và không được tuyên bố.

Hiệu năng

Tạo hình thêm một lần gọi libharfbuzz cho mỗi run trong phạm vi, cộng với lượt phát glyph, tuyến tính theo số glyph. Ngân sách (wall_ms: 2000, peak_mb: 128) theo hồ sơ CJK/hệ-chữ-phức-tạp, vì các font tạo hình lớn và việc xử lý font chi phối chi phí.

Ghi chú bảo mật

Bật bộ tạo hình đưa vào một lần gọi FFI tới libharfbuzz, một thư viện gốc. Các tệp font vẫn là đầu vào nhị phân không tin cậy được lớp typography xử lý bằng việc xác thực hiện có trước khi chúng đến bộ tạo hình. Bộ tạo hình tiêu thụ các face đã đăng ký, đã được xác thực sẵn. Hãy coi nguồn gốc của các font do người dùng cuối cung cấp là không tin cậy, và hãy cấp libharfbuzz từ một nguồn tin cậy.

Sự tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
Các run đã tạo hình được phát ra dưới dạng CID hai byte Identity-H trong một font composite Type 0.	ISO 32000-2	§9.7.4
Bộ tạo hình áp dụng việc thay thế và đặt vị trí glyph OpenType của font.	OpenType Specification	GSUB / GPOS
Việc hình thành cluster tuân theo các thuộc tính hệ chữ cho Tibetan và Mongolian.	Unicode Standard Annex	Tibetan and Mongolian

Đây là một bản triển khai xem trước được giới hạn ở Tibetan và Mongolian, đã được xác thực để tương đương khách quan với HarfBuzz. Nó không đưa ra tuyên bố về chất lượng ngôn ngữ và không khẳng định tuân thủ PDF đầu-cuối cho tệp tạo ra. Không có văn bản tiêu chuẩn nào được tái tạo.

Xem thêm

• Phân hệ kết xuất HTML
• Mô-đun Typography
• Bố cục dòng theo chế độ viết dọc
• Ma trận hỗ trợ CSS