Converter — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

NextPDF\Pro\Converter ส่งออก PDF ที่มีอยู่ไปเป็น HTML ที่จัดตำแหน่งแล้ว SVG แบบย่อ หรือข้อความล้วน และแบ่งเนื้อหาเอกสารออกเป็นพื้นที่โครงสร้างแบบมีชนิด การอ้างอิงเชิงลึกนี้ระบุพื้นผิว API สาธารณะ เมทริกซ์ความครอบคลุมของตัวดำเนินการ ข้อกำหนดด้านพฤติกรรม และโหมดความล้มเหลว เป็นตัวส่งออกเพื่อสกัดเนื้อหา ไม่ใช่ตัวเรนเดอร์ที่ตรงทุกพิกเซล

การมีให้ใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

ไม่มีแฟล็กความสามารถขณะรันที่จำกัดโมดูลนี้ คลาส converter จะถูกแปลงเมื่อใดก็ตามที่แพ็กเกจ Pro ถูกติดตั้งและมีใบอนุญาต

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ยกข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
PdfToHtmlConverter::convert()	string $pdfData, ?ConversionConfig $config = null	ส่งออกทุกหน้าที่มีข้อความไปยังเอกสาร HTML5 ที่สมบูรณ์ในตัวเองหนึ่งไฟล์	ConversionResult (เป้าหมาย Html5)	InvalidArgumentException เมื่อ $pdfData ว่าง	config ที่เป็น null จะใช้ค่าเริ่มต้นเป็น ConversionTarget::Html5
PdfToSvgConverter::convert()	string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null	ส่งออกหนึ่งหน้าไปยังเอกสาร SVG แบบสแตนด์อโลน	ConversionResult (เป้าหมาย Svg; pageCount เป็น 1 เสมอ)	InvalidArgumentException เมื่อ $pdfData ว่าง	$pageIndex ที่อยู่นอกช่วงจะให้ SVG ที่มีเฉพาะพื้นหลัง
PdfToTextConverter::convert()	string $pdfData	สกัดข้อความที่ถอดรหัสแล้วจากทุกหน้า คั่นด้วยเครื่องหมายแบ่งหน้า	ConversionResult (เป้าหมาย PlainText)	InvalidArgumentException เมื่อ $pdfData ว่าง	มีเพียงเป้าหมายนี้ที่ถอดรหัส escape ของสตริงตัวอักษร
PdfToTextConverter::extractPage()	string $pdfData, int $pageIndex	สกัดข้อความที่ถอดรหัสแล้วสำหรับหนึ่งหน้าโดยนับดัชนีเริ่มจากศูนย์	string	ไม่ยกข้อยกเว้น; คืนค่า '' สำหรับหน้าที่ไม่มีหรืออินพุตว่าง	ต่างจาก convert() ตรงที่ไม่มีการป้องกันอินพุตว่าง
DocumentSegmentationEngine::segment()	string $pdfData	จำแนกเนื้อหาของหน้าออกเป็นเซกเมนต์โครงสร้างแบบมีชนิดโดยใช้ฮิวริสติกเชิงพื้นที่และฟอนต์	NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation	InvalidArgumentException เมื่ออินพุตว่างหรือไม่สามารถแจงโครงสร้าง PDF ได้	อิงกฎ; ไม่ทำการอนุมานด้วย 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	—	ฟิลด์ readonly สาธารณะ: 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 ตัวแปลงสำหรับส่งออกทั้งสามใช้แบบจำลองการสแกนร่วมกัน ได้แก่ ระบุขอบเขต stream/endstream แยกบล็อกข้อความ BT/ET และแจงตัวดำเนินการที่แสดงข้อความ ตัวแปลงเหล่านี้ไม่แจงตารางการอ้างอิงข้าม และไม่คลายสตรีมที่บีบอัด DocumentSegmentationEngine แตกต่างออกไป คือจะแปลง trailer, catalog และ page tree แล้วคลายเนื้อหาหน้าแบบ FlateDecode ก่อนการจำแนก

ความครอบคลุมของตัวดำเนินการ:

PDF operator	HTML	SVG	Text
Tj (show string)	มี	มี	มี
TJ (show array)	มี	มี	มี
' (move + show)	ไม่มี	ไม่มี	มี
Td / Tm (position)	มี	มี	ไม่เกี่ยวข้อง
Tf (font size)	มี	มี	ไม่เกี่ยวข้อง
re (rectangle)	ไม่มี	มี	ไม่มี
m / l (line)	ไม่มี	มี	ไม่มี
RG (RGB stroke)	ไม่มี	มี (ใช้กับ stroke ของ rect/line)	ไม่มี
curves, shading, clipping, images	ไม่มี	ไม่มี	ไม่มี

• การจัดตำแหน่ง บล็อก BT/ET แต่ละบล็อกจะแปลงค่าตำแหน่งหนึ่งค่าจากการจับคู่ Td หรือ Tm ตัวแรก; Tm มีลำดับความสำคัญเหนือกว่าเมื่อปรากฏทั้งคู่ แกน Y ถูกพลิกจากพื้นที่ผู้ใช้ PDF ไปยังพื้นที่เอาต์พุตที่มีจุดกำเนิดมุมบนซ้าย ขนาดฟอนต์ใช้ค่าเริ่มต้น 12 pt เมื่อไม่มี Tf
• เรขาคณิตของหน้า HTML และ SVG ถือว่ากล่องหน้าเป็น A4 (595 x 842 pt) คูณด้วย scaleFactor ราก SVG มีแอตทริบิวต์ viewBox ความกว้าง และความสูงที่สอดคล้องกัน อยู่เหนือสี่เหลี่ยมพื้นหลังสีขาว
• สี stroke ตัวดำเนินการ RG ถูกแปลงตามตำแหน่ง ดังนั้นสตรีมที่เปลี่ยนสี stroke มากกว่าหนึ่งครั้งจะให้สีแก่แต่ละสี่เหลี่ยมและเส้นตามตัวดำเนินการก่อนหน้าที่ใกล้ที่สุด องค์ประกอบถูกจำกัดให้อยู่ในช่วง 0..1 ก่อนแปลงเป็นเลขฐานสิบหก การเติมสีสี่เหลี่ยมเป็นสีดำเสมอ; ตัวดำเนินการเติมสี rg ไม่ถูกประเมิน
• การถอดรหัสสตริง เป้าหมายข้อความถอดรหัส escape ของสตริงตัวอักษรตาม ISO 32000-2:2020 §7.3.4.2 ได้แก่ escape แบบมีชื่อ รหัสฐานแปด \ddd ที่มาสก์เหลือหนึ่งไบต์ การต่อบรรทัดด้วยแบ็กสแลช และการลบแบ็กสแลชเดี่ยว เป้าหมาย HTML และ SVG ปล่อยไบต์ดิบระหว่างวงเล็บออกมาหลังการ escape แบบ HTML หรือ XML; ทั้งสองไม่ถอดรหัส escape
• การประกอบเอาต์พุต เป้าหมายข้อความเชื่อมข้อความของแต่ละบล็อกด้วยช่องว่าง และเชื่อมหน้าด้วย --- Page Break --- ที่คั่นด้วยบรรทัดว่าง เป้าหมาย HTML ปล่อย <div> ที่จัดตำแหน่งแบบสัมบูรณ์หนึ่งตัวต่อบล็อกข้อความ ภายในคอนเทนเนอร์ของแต่ละหน้าที่มีคลาส CSS ที่กำหนดไว้และแอตทริบิวต์ data-page
• ความเป็นดีเทอร์มินิสติก สำหรับอินพุตและการกำหนดค่าที่เหมือนกัน ไบต์ HTML, SVG หรือข้อความที่สร้างขึ้นจะเสถียร processingTimeMs เป็นการวัดเวลาตามนาฬิกาจริงและถูกยกเว้นจากพื้นผิวที่เป็นดีเทอร์มินิสติก

กรณีขอบและโหมดความล้มเหลว

• อินพุตว่าง: จุดเข้าใช้งาน convert() และ segment() ทุกจุดจะยก InvalidArgumentException (“PDF data must not be empty”) ไม่มีการสร้างเอาต์พุตบางส่วน extractPage() เป็นข้อยกเว้น: จะคืนค่า '' โดยไม่ยกข้อยกเว้น
• สตรีมที่ไม่มี BT/ET จะถูกข้ามโดยตัวแปลง HTML และข้อความ ไฟล์ PDF ที่มีเฉพาะสตรีมเช่นนั้นจะให้ pageCount เป็นศูนย์ พร้อมเอาต์พุตข้อความว่างหรือเชลล์ HTML ที่ไม่มีหน้า
• isValid() ตรวจเฉพาะว่าเอาต์พุตไม่ว่างเท่านั้น ตัวแปลง HTML และ SVG ปล่อยเชลล์เอกสารเสมอ ดังนั้น isValid() ยังคงเป็น true แม้เมื่อไม่พบข้อความ; ให้ใช้ pageCount (HTML, ข้อความ) เพื่อตรวจจับการสกัดที่ว่างเปล่า
• เนื้อหาแบบ FlateDecode ไม่ถูกคลายโดยตัวแปลงสำหรับส่งออกทั้งสาม ไฟล์ PDF ที่บีบอัดล้วนจะส่งออกเนื้อหาผ่านตัวแปลงเหล่านี้ได้น้อยหรือไม่ได้เลย segment() คลายสตรีมหน้าแบบ FlateDecode
• segment() จำกัดการคลายบีบอัดด้วยขนาดต่อสตรีม อัตราส่วนการบีบอัด และงบประมาณสะสม สตรีมที่ทะลุเพดานจะลดระดับเป็นเนื้อหาหน้าว่างแทนที่จะใช้หน่วยความจำจนหมด; และจะไม่ยกข้อยกเว้น
• segment() จะยก InvalidArgumentException เมื่อไม่สามารถแปลง trailer, ออฟเซตการอ้างอิงข้าม, แคตาล็อกเอกสาร หรือ page tree ได้
• การทำดัชนีหน้าแตกต่างกันในแต่ละตัวแปลง ตัวแปลง HTML และข้อความนับเฉพาะสตรีมที่มีข้อความ; ตัวแปลง SVG นับสตรีมที่มีตัวดำเนินการกราฟิกหรือข้อความที่รู้จักใดๆ ดังนั้น $pageIndex เดียวกันอาจอ้างถึงสตรีมที่ต่างกัน
• การปรับ kerning เชิงตัวเลขของ 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	ตรวจสอบแล้ว (ชุดทดสอบยูนิต)
ถอดรหัส escape ของสตริงตัวอักษรแล้ว (เฉพาะเป้าหมายข้อความ)	ISO 32000-2:2020 §7.3.4.2	นำไปใช้แล้ว; คืนไบต์ตามเดิม การตีความชุดอักขระเป็นงานปลายทาง
รู้จักการสร้างเส้นทาง re, m, l (เป้าหมาย SVG)	ISO 32000-2:2020 §8.5.2	บางส่วน: เซตย่อยที่ไม่มีเส้นโค้ง การปิดเส้นทาง หรือการประเมินโหมดการลงสี
สเตตแมชชีนข้อความเต็มรูปแบบและการเรนเดอร์หน้า	—	ไม่รองรับ (อยู่นอกขอบเขต)

ตัวแปลงแจงตัวดำเนินการที่แสดงข้อความเพื่อกู้คืนเนื้อหา; ไม่ได้นำสเตตแมชชีนของข้อความมาใช้อย่างครบถ้วน ดังนั้นการจัดตำแหน่งกลีฟจึงเป็นค่าโดยประมาณ ไม่ใช่ค่าที่ตรงตามสเปกแบบเป๊ะ

บันทึกสำหรับนักพัฒนา

• การแจงเป็นเชิงเส้นตามความยาวไบต์ของ PDF หน่วยความจำเป็นสัดส่วนกับอินพุตบวกกับสตริงเอาต์พุตที่สร้างขึ้น front matter performance_budget เป็นค่าอ้างอิงต่อการเรียกหนึ่งครั้งสำหรับเอกสารสำนักงานทั่วไป
• ตัวแปลงแจงไบต์ PDF ที่ไม่น่าเชื่อถือด้วยการสแกน strpos/substr ที่มีขอบเขตจำกัด ไม่รัน JavaScript ที่ฝังอยู่และไม่ตามการอ้างอิงภายนอกใดๆ ให้ถือว่า HTML ที่ส่งออกเป็นเนื้อหาที่ไม่น่าเชื่อถือและ escape ให้เหมาะกับปลายทาง
• เอาต์พุต HTML ถูก escape ด้วย htmlspecialchars (ENT_QUOTES, HTML5); ข้อความ SVG ถูก escape แบบ XML cssClass ที่กำหนดไว้ถูก escape ก่อนปล่อยออกมา
• การใช้ค่าคอนฟิก: scaleFactor ใช้กับเป้าหมาย HTML และ SVG; cssClass ใช้กับ HTML เท่านั้น; embedFonts และ embedImages ถูกสงวนไว้และยังไม่ถูกใช้งาน; ฟิลด์ target ไม่ลบล้างรูปแบบเอาต์พุตของตัวแปลงเอง
• ตัวแปลงสำหรับส่งออกมีให้ใช้ตั้งแต่ 1.9.0; DocumentSegmentationEngine มีให้ใช้ตั้งแต่ 2.1.0 และรองรับเครื่องมือ segment_document ของ Pro MCP และสัญญาการแบ่งเซกเมนต์ของ Interop
• PdfPageExtractor และ PdfPageData ในเนมสเปซเดียวกันเป็นส่วนภายในของเอนจินการแบ่งเซกเมนต์ และไม่ใช่ API สาธารณะ

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทางเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าตั๋วอยู่นอกขอบเขต

ดูเพิ่มเติม

• ภาพรวมความสามารถของ Converter
• Extraction
• Diff
• Interop
• ไปป์ไลน์ HTML ของ Core