Converter — 深入參考

速覽

NextPDF\Pro\Converter 會將既有 PDF 匯出為定位後的 HTML、簡化的 SVG 或純文字，並將文件內容分段為具型別的結構區域。本深入參考逐項列出公開 API 介面、運算子涵蓋矩陣、行為合約與失敗模式。它是一個內容擷取匯出器，而非像素級精準的算繪器。

供應與授權

此功能隨 NextPDF Pro（nextpdf/pro）提供，並以 Pro 層級的授權封套啟用。未具備該權利的部署不會載入此功能的類別。比較版本並取得授權。

沒有任何執行階段能力旗標控管此模組。只要安裝並授權了 Pro 套件，這些 converter 類別即可解析使用。

公開 API 介面

Symbol	Parameters	預設行為	回傳	拋出或失敗於	備註
PdfToHtmlConverter::convert()	string $pdfData, ?ConversionConfig $config = null	將每個含文字的頁面匯出為單一自足的 HTML5 文件	ConversionResult（目標 Html5）	$pdfData 為空時拋出 InvalidArgumentException	config 為 null 時預設為 ConversionTarget::Html5
PdfToSvgConverter::convert()	string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null	將單一頁面匯出為獨立的 SVG 文件	ConversionResult（目標 Svg；pageCount 恆為 1）	$pdfData 為空時拋出 InvalidArgumentException	超出範圍的 $pageIndex 會產出僅含背景的 SVG
PdfToTextConverter::convert()	string $pdfData	從所有頁面擷取解碼後的文字，並以分頁標記分隔	ConversionResult（目標 PlainText）	$pdfData 為空時拋出 InvalidArgumentException	只有此目標會解碼字面字串跳脫序列
PdfToTextConverter::extractPage()	string $pdfData, int $pageIndex	擷取單一頁面（以零為起始索引）的解碼後文字	string	不會拋出例外；頁面不存在或輸入為空時回傳 ''	與 convert() 不同，沒有空白輸入防護
DocumentSegmentationEngine::segment()	string $pdfData	以空間與字型啟發法將頁面內容分類為具型別的結構區段	NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation	輸入為空或無法剖析 PDF 結構時拋出 InvalidArgumentException	以規則為基礎；不進行 AI 推論
ConversionConfig::__construct()	ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page'	不可變的轉換設定	ConversionConfig	—	embedFonts 與 embedImages 會被接受，但在 3.1.0 中並未使用
ConversionResult::size()	—	所產出輸出的位元組長度	int	—	公開唯讀欄位：output、target、pageCount、processingTimeMs
ConversionResult::isValid()	—	回報輸出是否非空	bool	—	HTML 與 SVG 文件外殼永不為空；請改為檢查 pageCount
ConversionTarget	以字串支援的列舉案例 Html5、Svg、PlainText	選擇匯出目標	mimeType(): string, fileExtension(): string	—	fileExtension() 對應到 html、svg、txt

進入點簽章：

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

行為合約

輸入是原始 PDF 位元組；輸出是一個 ConversionResult 值物件。這三個匯出 converter 共用相同的掃描模型：定位 stream/endstream 邊界、隔離 BT/ET 文字區塊，並剖析文字呈現運算子。它們不會剖析交互參照表，也不會解壓縮壓縮串流。DocumentSegmentationEngine 則不同：它會解析 trailer、catalog 與頁面樹，並在分類前解壓縮 FlateDecode 頁面內容。

運算子涵蓋範圍：

PDF 運算子	HTML	SVG	Text
Tj（呈現字串）	是	是	是
TJ（呈現陣列）	是	是	是
'（移動 + 呈現）	否	否	是
Td / Tm（定位）	是	是	不適用
Tf（字型大小）	是	是	不適用
re（矩形）	否	是	否
m / l（線段）	否	是	否
RG（RGB 描邊）	否	是（套用至矩形/線段描邊）	否
曲線、漸層、裁切、影像	否	否	否

• 定位。 每個 BT/ET 區塊會從其第一個 Td 或 Tm 相符項解析出一個位置；兩者皆出現時 Tm 優先。Y 軸會從 PDF 使用者空間翻轉至左上原點的輸出空間。當沒有 Tf 時，字型大小預設為 12 pt。
• 頁面幾何。 HTML 與 SVG 假設 A4 頁面框（595 x 842 pt）乘以 scaleFactor。SVG 根元素帶有相符的 viewBox、width 與 height 屬性，並置於一個白色背景矩形之上。
• 描邊顏色。 RG 運算子依位置解析，因此若一個串流多次變更描邊顏色，每個矩形與線段會以其之前最近的運算子上色。各分量在轉換為十六進位前會被夾限至 0..1 範圍。矩形填色恆為黑色；rg 填色運算子不會被求值。
• 字串解碼。 文字目標會依 ISO 32000-2:2020 §7.3.4.2 解碼字面字串跳脫序列：具名跳脫、遮罩為單一位元組的八進位 \ddd 代碼、反斜線行接續，以及移除孤立反斜線。HTML 與 SVG 目標則會在經 HTML 或 XML 跳脫後，發出括號之間的原始位元組；它們不會解碼跳脫序列。
• 輸出組裝。 文字目標會以一個空格串接各區塊文字，並以前後空白行包夾的 --- Page Break --- 串接各頁面。HTML 目標會在每頁的容器內，為每個文字區塊發出一個絕對定位的 <div>，該容器帶有所設定的 CSS 類別與 data-page 屬性。
• 決定性。 對於相同的輸入與設定，所產出的 HTML、SVG 或文字位元組是穩定的。processingTimeMs 是掛鐘時間量測值，不納入決定性介面範圍。

邊界案例與失敗模式

• 空白輸入：每個 convert() 與 segment() 進入點都會引發 InvalidArgumentException（「PDF data must not be empty」）。不會產出部分輸出。extractPage() 是例外：它會回傳 '' 而不拋出。
• 不含 BT/ET 的串流會被 HTML 與文字 converter 略過。若一份 PDF 僅由這類串流組成，會產出零值的 pageCount，並帶有空白文字輸出或無頁面的 HTML 外殼。
• isValid() 只檢查輸出是否非空。HTML 與 SVG converter 一律會發出文件外殼，因此即使找不到文字，isValid() 仍維持 true；請使用 pageCount（HTML、文字）來偵測空白擷取。
• 這三個匯出 converter 不會解壓縮 FlateDecode 內容。僅含壓縮內容的 PDF 透過它們匯出的內容極少，甚至沒有。segment() 則會解壓縮 FlateDecode 頁面串流。
• segment() 會以每個串流的大小、壓縮比與累計預算來限制解壓縮。突破上限的串流會退化為空白頁面內容，而非耗盡記憶體；它不會拋出例外。
• 當無法解析 trailer、交互參照位移、文件 catalog 或頁面樹時，segment() 會引發 InvalidArgumentException。
• 頁面索引因 converter 而異。HTML 與文字 converter 只計算含文字的串流；SVG converter 則計算含有任何可辨識圖形或文字運算子的串流。因此相同的 $pageIndex 可能指向不同的串流。
• TJ 的數值字距調整會被捨棄；陣列字串會串接在一起而沒有字符間距。
• 不會套用字符對 Unicode 的對應。以自訂編碼字型排版的文字會以原始位元組序列匯出。
• 旋轉文字、非文字變換與分欄流會以第一相符定位近似處理，可能無法重現原始版面。
• 此模組不執行任何密碼學運算，因此 FIPS 模式沒有任何模組專屬行為。

一致性

NextPDF 依所引用的條款記載其功能。支援聲明描述的是已實作的行為；它們並非一致性測試結果，也不是認證，且 NextPDF 未持有任何認證。

主張	規格條款	狀態
Tj 文字呈現運算子已剖析	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
TJ 陣列文字呈現運算子已剖析	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
' 移動並呈現運算子已剖析（僅文字目標）	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
字面字串跳脫序列已解碼（僅文字目標）	ISO 32000-2:2020 §7.3.4.2	已實作；位元組原樣回傳，字元集解讀交由下游處理
re、m、l 路徑建構已辨識（SVG 目標）	ISO 32000-2:2020 §8.5.2	部分：不含曲線、封閉或繪製模式求值的子集
完整文字狀態機與頁面算繪	—	不支援（超出範圍）

Converter 剖析文字呈現運算子以還原內容；它並未實作完整的文字狀態機，因此字符定位是近似的，而非符合規格的精確值。

開發備註

• 剖析的時間與 PDF 位元組長度成線性關係。記憶體用量隨輸入加上所產出的輸出字串而變化。前置資料中的 performance_budget 是針對典型辦公文件的每次呼叫參考值。
• 這些 converter 以有界的 strpos/substr 掃描剖析不受信任的 PDF 位元組。它們不會執行任何內嵌 JavaScript，也不會追隨任何外部參照。請將匯出的 HTML 視為不受信任的內容，並針對其目的地進行跳脫。
• HTML 輸出以 htmlspecialchars（ENT_QUOTES、HTML5）跳脫；SVG 文字則經 XML 跳脫。所設定的 cssClass 會在發出前被跳脫。
• 設定的使用方式：scaleFactor 套用於 HTML 與 SVG 目標；cssClass 僅套用於 HTML；embedFonts 與 embedImages 為保留欄位，目前未使用；target 欄位不會覆寫 converter 本身的輸出格式。
• 匯出 converter 自 1.9.0 起提供；DocumentSegmentationEngine 自 2.1.0 起提供，並支撐 Pro MCP segment_document 工具與 Interop 分段合約。
• 同一命名空間中的 PdfPageExtractor 與 PdfPageData 屬於分段引擎的內部實作，並非公開 API。

發布邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名與工單前綴皆超出範圍。

另請參閱

• Converter 功能總覽
• Extraction
• Diff
• Interop
• Core HTML 管線