Pro phiên bản

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

Tổng quan nhanh

NextPDF\Pro\Converter xuất một PDF hiện có ra HTML có định vị, SVG đơn giản hóa hoặc văn bản thuần, và phân đoạn nội dung tài liệu thành các vùng cấu trúc được phân loại. Tài liệu tham chiếu chuyên sâu này liệt kê bề mặt API công khai, ma trận phạm vi toán tử, hợp đồng hành vi và các chế độ lỗi. Đây là một bộ xuất trích xuất nội dung, không phải một bộ render chính xác từng pixel.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một envelope giấy phép hạng Pro. Một triển khai không có quyền dùng đó sẽ không nạp các lớp 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ờ năng lực lúc chạy nào kiểm soát module này. Các lớp converter phân giải được bất cứ khi nào gói Pro đã được cài đặt và cấp phép.

Bề mặt API công khai

Symbol	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Xuất mọi trang có văn bản thành một tài liệu HTML5 độc lập	`ConversionResult` (đích `Html5`)	`InvalidArgumentException` khi `$pdfData` rỗng	Config null mặc định về `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Xuất một trang thành một tài liệu SVG độc lập	`ConversionResult` (đích `Svg`; `pageCount` luôn là 1)	`InvalidArgumentException` khi `$pdfData` rỗng	`$pageIndex` ngoài phạm vi cho ra một SVG chỉ có nền
`PdfToTextConverter::convert()`	`string $pdfData`	Trích xuất văn bản đã giải mã từ mọi trang, ngăn cách bằng một dấu ngắt trang	`ConversionResult` (đích `PlainText`)	`InvalidArgumentException` khi `$pdfData` rỗng	Chỉ đích này giải mã các escape của chuỗi literal
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Trích xuất văn bản đã giải mã cho một trang đánh số từ 0	`string`	Không ném; trả về `''` cho một trang thiếu hoặc đầu vào rỗng	Khác với `convert()`, không có kiểm tra đầu vào rỗng
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Phân loại nội dung trang thành các phân đoạn cấu trúc được phân loại bằng heuristic không gian và font	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException` khi đầu vào rỗng hoặc không phân tích được cấu trúc PDF	Dựa trên luật; không thực hiện suy luận AI
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Thiết lập chuyển đổi bất biến	`ConversionConfig`	—	`embedFonts` và `embedImages` được chấp nhận nhưng không được dùng trong 3.1.0
`ConversionResult::size()`	—	Độ dài byte của đầu ra được tạo	`int`	—	Các trường readonly công khai: `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Báo cáo đầu ra có khác rỗng hay không	`bool`	—	Vỏ tài liệu HTML và SVG không bao giờ rỗng; hãy kiểm tra `pageCount` thay vào đó
`ConversionTarget`	Các case backing bằng chuỗi `Html5`, `Svg`, `PlainText`	Chọn đích xuất	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` ánh xạ tới `html`, `svg`, `txt`

Chữ ký các điểm vào:

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

Hợp đồng hành vi

Đầu vào là các byte PDF thô; đầu ra là một value object ConversionResult. Ba bộ converter xuất dùng chung một mô hình quét: định vị các ranh giới stream/endstream, cô lập các khối văn bản BT/ET, và phân tích các toán tử hiển thị văn bản. Chúng không phân tích bảng tham chiếu chéo và không giải nén các stream đã nén. DocumentSegmentationEngine thì khác: nó phân giải trailer, catalog và cây trang, rồi giải nén nội dung trang FlateDecode trước khi phân loại.

Phạm vi toán tử:

PDF operator	HTML	SVG	Text
`Tj` (show string)	có	có	có
`TJ` (show array)	có	có	có
`'` (move + show)	không	không	có
`Td` / `Tm` (position)	có	có	n/a
`Tf` (font size)	có	có	n/a
`re` (rectangle)	không	có	không
`m` / `l` (line)	không	có	không
`RG` (RGB stroke)	không	có (áp cho nét vẽ rect/line)	không
đường cong, đổ bóng, cắt, ảnh	không	không	không

Định vị. Mỗi khối BT/ET phân giải một vị trí từ khớp Td hoặc Tm đầu tiên của nó; Tm được ưu tiên khi cả hai cùng xuất hiện. Trục Y bị lật từ không gian người dùng PDF sang không gian đầu ra góc trên-trái. Cỡ font mặc định là 12 pt khi không có Tf.
Hình học trang. HTML và SVG giả định một hộp trang A4 (595 x 842 pt) nhân với scaleFactor. Gốc SVG mang các thuộc tính viewBox, width và height khớp nhau trên một hình chữ nhật nền trắng.
Màu nét vẽ. Các toán tử RG được phân giải theo vị trí, nên một stream đổi màu nét vẽ nhiều hơn một lần sẽ tô mỗi hình chữ nhật và đường thẳng bằng toán tử đứng trước gần nhất. Các thành phần được kẹp về khoảng 0..1 trước khi chuyển sang hex. Màu tô hình chữ nhật luôn là đen; toán tử tô rg không được đánh giá.
Giải mã chuỗi. Đích văn bản giải mã các escape của chuỗi literal theo ISO 32000-2:2020 §7.3.4.2: các escape có tên, mã octal \ddd được mask về một byte, dấu gạch chéo ngược nối dòng, và loại bỏ dấu gạch chéo ngược đơn lẻ. Đích HTML và SVG phát ra các byte thô nằm giữa các dấu ngoặc đơn sau khi escape HTML hoặc XML; chúng không giải mã các escape.
Lắp ráp đầu ra. Đích văn bản nối văn bản các khối bằng một dấu cách, và nối các trang bằng --- Page Break --- được đóng khung bằng các dòng trống. Đích HTML phát ra một <div> định vị tuyệt đối cho mỗi khối văn bản bên trong một container mỗi trang mang lớp CSS đã cấu hình và một thuộc tính data-page.
Tính tất định. Với cùng đầu vào và cấu hình, các byte HTML, SVG hoặc văn bản được tạo là ổn định. processingTimeMs là một phép đo thời gian thực và được loại khỏi bề mặt tất định.

Trường hợp ngoại lệ & chế độ lỗi

Đầu vào rỗng: mọi điểm vào convert() và segment() phát sinh InvalidArgumentException (“PDF data must not be empty”). Không có đầu ra một phần nào được tạo. extractPage() là ngoại lệ: nó trả về '' mà không ném.
Các stream không có BT/ET bị các bộ converter HTML và text bỏ qua. Một PDF chỉ gồm các stream như vậy cho ra một pageCount bằng không với đầu ra văn bản rỗng hoặc một vỏ HTML không có trang.
isValid() chỉ kiểm tra đầu ra khác rỗng. Các bộ converter HTML và SVG luôn phát ra một vỏ tài liệu, nên isValid() vẫn true ngay cả khi không tìm thấy văn bản; dùng pageCount (HTML, text) để phát hiện việc trích xuất rỗng.
Nội dung FlateDecode không được ba bộ converter xuất giải nén. Các PDF chỉ có nội dung nén xuất ra rất ít hoặc không có nội dung qua chúng. segment() thì có giải nén các stream trang FlateDecode.
segment() giới hạn việc giải nén theo kích thước mỗi stream, tỷ lệ nén và một hạn mức tích lũy. Một stream vượt trần sẽ suy giảm về nội dung trang rỗng thay vì làm cạn bộ nhớ; nó không ném.
segment() phát sinh InvalidArgumentException khi không phân giải được trailer, offset tham chiếu chéo, catalog tài liệu hoặc cây trang.
Cách đánh số trang khác nhau tùy converter. Các bộ converter HTML và text chỉ đếm các stream có văn bản; bộ converter SVG đếm các stream chứa bất kỳ toán tử đồ họa hoặc văn bản được nhận diện nào. Do đó cùng một $pageIndex có thể trỏ tới các stream khác nhau.
Các điều chỉnh kerning số của TJ bị loại bỏ; các chuỗi của mảng được nối liền mà không có khoảng cách giữa các glyph.
Ánh xạ glyph-sang-Unicode không được áp dụng. Văn bản đặt trong các font có encoding tùy biến sẽ xuất ra dưới dạng chuỗi byte thô.
Văn bản xoay, các phép biến đổi phi văn bản và luồng cột được xấp xỉ bằng định vị theo khớp đầu tiên và có thể không tái tạo bố cục gốc.
Không có thao tác mật mã nào xảy ra trong module này, nên chế độ FIPS không có hành vi đặc thù cho module.

Tính phù hợp

NextPDF ghi nhận năng lực đối chiếu với các điều khoản được trích dẫn. Các phát biểu hỗ trợ mô tả hành vi đã hiện thực; chúng không phải là kết quả kiểm thử phù hợp và không phải chứng nhận, và NextPDF không giữ chứng nhận nào.

Tuyên bố	Điều khoản đặc tả	Trạng thái
Toán tử hiển thị văn bản `Tj` được phân tích	ISO 32000-2:2020 §9.4	Đã kiểm chứng (bộ unit)
Toán tử hiển thị văn bản mảng `TJ` được phân tích	ISO 32000-2:2020 §9.4	Đã kiểm chứng (bộ unit)
Toán tử move-and-show `'` được phân tích (chỉ đích text)	ISO 32000-2:2020 §9.4	Đã kiểm chứng (bộ unit)
Các escape của chuỗi literal được giải mã (chỉ đích text)	ISO 32000-2:2020 §7.3.4.2	Đã hiện thực; byte trả về nguyên trạng, việc diễn giải charset thuộc phía sau
Xây dựng path `re`, `m`, `l` được nhận diện (đích SVG)	ISO 32000-2:2020 §8.5.2	Một phần: tập con không có đường cong, khép kín hoặc đánh giá chế độ vẽ
Máy trạng thái văn bản đầy đủ và render trang	—	Không hỗ trợ (ngoài phạm vi)

Converter phân tích các toán tử hiển thị văn bản để khôi phục nội dung; nó không hiện thực máy trạng thái văn bản đầy đủ, nên việc định vị glyph là gần đúng chứ không chính xác theo đặc tả.

Ghi chú phát triển

Việc phân tích là tuyến tính theo độ dài byte PDF. Bộ nhớ theo sát đầu vào cộng với chuỗi đầu ra được tạo. Front matter performance_budget là tham chiếu mỗi lần gọi cho một tài liệu văn phòng điển hình.
Các bộ converter phân tích các byte PDF không tin cậy bằng quét strpos/substr có giới hạn. Chúng không thực thi JavaScript nhúng nào và không đi theo tham chiếu ngoài nào. Hãy coi HTML được xuất là nội dung không tin cậy và escape nó cho đích đến của nó.
Đầu ra HTML được escape bằng htmlspecialchars (ENT_QUOTES, HTML5); văn bản SVG được escape XML. cssClass đã cấu hình được escape trước khi phát ra.
Tiêu thụ config: scaleFactor áp cho đích HTML và SVG; cssClass chỉ áp cho HTML; embedFonts và embedImages được dành riêng và hiện chưa dùng; trường target không ghi đè định dạng đầu ra riêng của một converter.
Các bộ converter xuất đi kèm từ 1.9.0; DocumentSegmentationEngine đi kèm từ 2.1.0 và làm nền cho công cụ MCP segment_document của Pro cùng hợp đồng phân đoạn Interop.
PdfPageExtractor và PdfPageData trong cùng namespace là nội bộ của engine phân đoạn và không phải API công khai.

Ranh giới công bố

Trang này chỉ ghi nhận hành vi có thể quan sát 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ộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket đều ngoài phạm vi.