Pro phiên bản

Font Tools — Tài liệu tham chiếu chuyên sâu

Tổng quan

Trang này là tài liệu tham chiếu ở mức hợp đồng cho NextPDF Pro Font Tools. Bề mặt gồm một bộ quét duy nhất, NextPDF\Pro\FontTools\FontDesubsetter, và hai value object bất biến, SubsetInfo và DesubsetPlan. Bộ quét đọc các byte PDF thô, báo cáo mọi mục /BaseFont riêng biệt, và đánh dấu các mục tuân theo quy ước đặt tên tập con của ISO 32000-2:2020 §9.9.2. Một kế hoạch tổng hợp các tập con được đánh dấu và ước tính chi phí byte để khôi phục các chương trình phông đầy đủ. Module chỉ phân tích và ước tính; nó không bao giờ ghi lại một chương trình phông được nhúng. Trang này nêu API công khai, hợp đồng hành vi quan sát được, và các chế độ lỗi.

Tình trạng khả dụng & cấp phép

Năng lực này có trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một phong bì giấy phép hạng Pro. Một triển khai không có quyền đó sẽ không nạp các class của năng lực này. So sánh các phiên bản và lấy giấy phép.

Không có cờ giấy phép theo từng tính năng nào kiểm soát module này. Các class Font Tools luôn sẵn có bất cứ khi nào nextpdf/pro được cài đặt.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc lỗi với	Ghi chú
`FontDesubsetter`	không có	Bộ quét không trạng thái trên các byte PDF thô	—	—	`final`; an toàn để tái sử dụng qua nhiều tài liệu
`FontDesubsetter::analyzeSubsets()`	`string $pdfData`	Báo cáo mọi mục `/BaseFont` riêng biệt, dù là tập con hay không, được đánh dấu bởi `isSubset`	`list<SubsetInfo>`	`InvalidArgumentException` khi ước tính tập con suy ra từ chiều rộng vượt quá ước tính số-đầy-đủ suy ra từ tên	Quét mức byte; các object stream nén không được giải mã
`FontDesubsetter::isSubsetFont()`	`string $baseFontName`	Khớp quy ước tiền tố sáu-chữ-hoa-cộng-`+`	`bool`	—	Neo ở đầu tên
`FontDesubsetter::extractSubsetPrefix()`	`string $baseFontName`	Trả về thẻ tập con sáu chữ cái	`string`	—	Chuỗi rỗng với tên không phải tập con
`FontDesubsetter::generateDesubsetPlan()`	`list<SubsetInfo> $subsets`	Thu thập các mục có `isSubset` là `true` và cộng dồn ước tính kích thước	`DesubsetPlan`	Không ném	Các mục không phải tập con bị bỏ qua âm thầm
`SubsetInfo`	hàm khởi tạo: `$fontName`, `$baseFont`, `$subsetGlyphCount`, `$fullGlyphCount`, `$isSubset`, `$encoding`	Mô tả bất biến của một mục `/BaseFont`	—	`InvalidArgumentException` khi số glyph âm, hoặc số tập con vượt quá số đầy đủ	`final readonly`; mọi thuộc tính đều public
`SubsetInfo::subsetPrefix()`	không có	Trích thẻ sáu chữ cái từ `fontName`	`string`	—	Chuỗi rỗng khi không phải tập con hoặc `+` không nằm ở vị trí thứ sáu
`SubsetInfo::coveragePercent()`	không có	Tỷ lệ tập con trên toàn bộ tập glyph đầy đủ	`float` trong `[0.0, 100.0]`	—	Trả về `0.0` khi `fullGlyphCount` là `0`
`DesubsetPlan`	hàm khởi tạo: `list<SubsetInfo> $targets`, `int $estimatedSizeIncrease`	Kế hoạch khôi phục tập con bất biến	—	—	`final readonly`; mọi thuộc tính đều public
`DesubsetPlan::count()`	không có	Số phông được nhắm tới	`int`	—	Bằng độ dài của `targets`
`DesubsetPlan::totalGlyphsNeeded()`	không có	Tổng số glyph còn thiếu trên tất cả các mục tiêu	`int`	—	Tổng của `fullGlyphCount - subsetGlyphCount` mỗi mục tiêu

Chữ ký điểm vào

public function analyzeSubsets(string $pdfData): array

public function isSubsetFont(string $baseFontName): bool

public function extractSubsetPrefix(string $baseFontName): string

public function generateDesubsetPlan(array $subsets): DesubsetPlan

public function __construct(
    public string $fontName,
    public string $baseFont,
    public int $subsetGlyphCount,
    public int $fullGlyphCount,
    public bool $isSubset,
    public string $encoding,
)

public function subsetPrefix(): string

public function coveragePercent(): float

public function __construct(
    public array $targets,
    public int $estimatedSizeIncrease,
) {}

public function count(): int

public function totalGlyphsNeeded(): int

Hợp đồng hành vi

Quét và phát hiện tập con

analyzeSubsets() trích các token tên /BaseFont từ các byte thô bằng một phép khớp mẫu ở mức byte. Các tên trùng lặp gộp thành một mục; thứ tự theo lần xuất hiện đầu tiên. Mỗi tên riêng biệt sinh ra một SubsetInfo, dù nó có phải tập con hay không. Một tên là tập con khi nó bắt đầu bằng đúng sáu chữ cái ASCII viết hoa theo sau bởi +, quy ước §9.9.2. Với các tên tập con, baseFont là tên đã bỏ đi tiền tố bảy ký tự. Với các tên thông thường, baseFont bằng fontName. Mỗi tên tập con riêng biệt được báo cáo như một mục riêng, khớp với hướng dẫn §9.9.2 là coi các tập con như những thực thể độc lập.

Phát hiện bảng mã

Với mỗi phông, bộ quét tìm trong một cửa sổ byte có giới hạn sau lần xuất hiện /BaseFont. Một mục tên /Encoding trong cửa sổ sẽ thắng. Nếu không có, một chuỗi con Identity-H hoặc Identity-V trong cửa sổ sẽ được báo cáo. Nếu cả hai đều không có, mục báo cáo Unknown. Các giá trị bảng mã nằm trong dictionary hoặc được tiếp cận qua tham chiếu gián tiếp sẽ báo cáo Unknown.

Kiểm đếm glyph

Cả hai số glyph đều là ước tính. subsetGlyphCount suy ra từ các mảng chiều rộng thấy được gần mục phông: một mảng /W của CIDFont cho khoảng một glyph trên mỗi bộ ba chiều rộng, và một mảng /Widths của phông đơn giản cho một glyph trên mỗi mục số. Khi không thấy mảng nào trong cửa sổ, một giá trị mặc định cố định nhỏ được áp dụng. Khi không thể định vị lại lần xuất hiện /BaseFont cho phép tìm trong cửa sổ, số đếm là 0. fullGlyphCount suy ra từ heuristic tên họ phông: một bảng các họ Latin nổi tiếng, một tập các chỉ báo tên họ CJK, và một mức sàn tổng quát nếu không thuộc các trường hợp trên. Chương trình phông được nhúng không bao giờ được phân tích. Các bảng, kích thước cửa sổ, và hằng số cụ thể là chi tiết triển khai, không được công bố, và có thể thay đổi giữa các bản phát hành.

Tạo kế hoạch

generateDesubsetPlan() lọc đầu vào chỉ giữ các mục có isSubset là true. Mỗi mục tiêu đóng góp số glyph còn thiếu của nó, nhân với một hằng số số-byte-trung-bình-mỗi-glyph cố định, vào estimatedSizeIncrease. Kế hoạch là một dự phóng cho các quyết định về dung lượng, không phải một delta được đo lường. Việc thực thi một kế hoạch — ghi lại các chương trình phông — nằm ngoài module này.

Tính tất định

Toàn bộ bề mặt là một hàm thuần của đầu vào. Các byte giống nhau tạo ra kết quả giống nhau. Không có tính ngẫu nhiên, không có lời gọi mạng, và không có truy cập hệ thống tệp.

Trường hợp biên & chế độ lỗi

Việc khởi tạo SubsetInfo từ chối các trạng thái không hợp lệ: một số glyph âm, hoặc một số tập con vượt quá số đầy đủ, sẽ ném InvalidArgumentException.
analyzeSubsets() có thể truyền tiếp ngoại lệ đó trong một trường hợp góc: một phông có tên khớp với một họ đã biết nhưng mảng chiều rộng thấy được của nó cho ra ước tính tập con lớn hơn con số số-đầy-đủ của họ đó.
Việc phát hiện hoạt động trên biểu diễn byte. Các mục /BaseFont được tuần tự hóa bên trong các object stream nén là vô hình; hãy giải nén các stream đó trước khi quét.
Các mục có khóa và giá trị /BaseFont cách nhau bởi khoảng trắng khác một dấu cách đơn vẫn được phát hiện, nhưng phép tìm cửa sổ theo từng phông không định vị lại được chúng. Các mục như vậy báo cáo bảng mã Unknown và số glyph tập con là 0.
Các tên PDF dùng byte thoát bằng # được báo cáo ở dạng thoát thô; các chuỗi thoát không được giải mã.
Các tên /BaseFont trùng lặp gộp thành một mục duy nhất. Hai object phông khác nhau dùng chung một tên là không phân biệt được với bộ quét này.
generateDesubsetPlan() không bao giờ thất bại trên đầu vào không phải tập con; các mục có isSubset đặt là false chỉ đơn giản bị loại khỏi targets.
Mọi số đếm và estimatedSizeIncrease đều là heuristic. Đừng coi chúng như các giá trị được đo lường; chỉ dùng chúng cho phân loại và lập kế hoạch dung lượng.
Không có thao tác mã hóa nào xảy ra trong module này, nên không có hành vi riêng cho chế độ FIPS.

Tính phù hợp

Tuyên bố	Tiêu chuẩn	Điều khoản
Việc phát hiện tập con khớp với quy ước đặt tên tập con: một thẻ gồm sáu chữ cái viết hoa theo sau bởi `+` được thêm vào trước giá trị `BaseFont`.	ISO 32000-2:2020	§9.9.2
Mỗi tên tập con riêng biệt được báo cáo độc lập, theo khuyến nghị coi nhiều tập con như những thực thể riêng.	ISO 32000-2:2020	§9.9.2

Mọi điều khoản đều được diễn giải lại; NextPDF không tái tạo văn bản quy phạm. Đây là các tuyên bố về năng lực, không phải chứng nhận. NextPDF không giữ chứng nhận nào và không cấp chứng nhận nào. Module khẳng định việc phát hiện quy ước đặt tên và báo cáo tất định; nó không khẳng định độ chính xác của các ước tính số-glyph hay kích thước.

Ghi chú phát triển

Cài đặt bằng composer require nextpdf/pro:^3. Có từ nextpdf/pro 1.9.0; hiện hành trong nextpdf/pro 3.1.0.
FontDesubsetter không trạng thái. Khởi tạo một lần và tái sử dụng qua nhiều tài liệu và luồng công việc.
Cấp cho analyzeSubsets() các byte đã giải nén khi độ phủ tập con quan trọng; nếu không, các dictionary phông đóng gói trong object stream sẽ bị bỏ sót.
Rẽ nhánh theo SubsetInfo::isSubset trước khi hành động; danh sách kết quả cố ý bao gồm các phông không phải tập con cho mục đích kiểm kê.
Dùng DesubsetPlan::totalGlyphsNeeded() và estimatedSizeIncrease để quyết định liệu việc khôi phục tập con có đáng với chi phí kích thước tệp hay không, trước khi tìm nguồn các chương trình phông đầy đủ.
Việc quét là tuyến tính theo độ dài đầu vào với các phép tìm cửa sổ theo từng phông có giới hạn. Module không lưu gì và không phát ra telemetry.

Ranh giới công bố

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, class trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket đều nằm ngoài phạm vi.

Xem thêm

Font Tools (năng lực) — cài đặt, khởi đầu nhanh, và các mẫu quy trình lập kế hoạch.
Optimizer — Tài liệu tham chiếu chuyên sâu — bề mặt giảm kích thước tương ứng, bao gồm cả tối ưu hóa liên quan đến phông.
Module phông của Core — nhúng và tạo tập con phông trong quá trình tạo tài liệu ở NextPDF Core.