Flow Layout

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

NextPDF Pro จัดวางลำดับขององค์ประกอบแบบไหล ได้แก่ ข้อความ ภาพ ตาราง ตัวเว้นระยะ ลงบนหน้า โดยกำหนดหน้าและตำแหน่งที่เป็นรูปธรรมให้แต่ละองค์ประกอบ พฤติกรรมการแบ่งหน้าเลือกได้ คือ greedy หลีกเลี่ยง orphan หรือ keep-together

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

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

การติดตั้ง

composer require nextpdf/pro:^3

ภาพรวมเชิงแนวคิด

เอนจินเค้าโครงแบบสตรีมรับรายการขององค์ประกอบแบบไหลและบริเวณเนื้อหา จากนั้นเดินผ่านองค์ประกอบตามลำดับและกำหนดหน้าและตำแหน่งให้แต่ละองค์ประกอบ เมื่อองค์ประกอบไม่พอดีกับพื้นที่แนวตั้งที่เหลือ เอนจินจะเริ่มหน้าใหม่ตามกลยุทธ์ที่กำหนดค่าไว้:

• StreamingLayoutEngine เอนจิน สร้างขึ้นด้วย LayoutRegion (บริเวณเนื้อหาต่อหน้า) และ PageBreakStrategy โดยคืนค่า LayoutResult ขององค์ประกอบที่จัดวางแล้ว
• FlowElement / FlowElementType แบบจำลองขององค์ประกอบ ข้อความและตารางสามารถแบ่งข้ามหน้าได้ เอนจินจัดวางภาพและตัวเว้นระยะแบบอะตอมมิก
• PageBreakStrategy enum ที่มีพฤติกรรมสามแบบ:
  • Greedy แบ่งทันทีที่องค์ประกอบถัดไปไม่พอดี
  • AvoidOrphans แบ่งก่อนกำหนดเมื่อเหลือพื้นที่เพียงเล็กน้อย เพื่อหลีกเลี่ยงการทิ้งองค์ประกอบเดียวไว้ที่ส่วนบนของหน้าใหม่
  • KeepTogether ปฏิบัติตามแฟล็ก keep-with-next เพื่อให้องค์ประกอบที่จับคู่กันอยู่บนหน้าเดียวกันเมื่อเป็นไปได้

Flow Layout คือเอนจินการจัดวางองค์ประกอบ โดยคำนวณการกำหนดหน้าและตำแหน่ง ไม่ใช่เอนจินการเรนเดอร์ HTML หรือ CSS สำหรับ HTML เป็น PDF ให้ใช้ไปป์ไลน์ HTML ของ Core

เหตุใดจึงทำงานเช่นนี้

เอนจินกำหนดหน้าและตำแหน่งให้แต่ละองค์ประกอบในการเดินไปข้างหน้าเพียงรอบเดียว โดยไม่บัฟเฟอร์ tree ของเอกสารทั้งหมดไว้เพื่อจัดใหม่ภายหลัง จึงทำให้หน่วยความจำถูกจำกัดไม่ว่าเอกสารจะยาวเพียงใด และทำให้ต้นทุนเป็นเชิงเส้นตามจำนวนองค์ประกอบ การตัดสินใจแบ่งหน้าแต่ละครั้งเป็นเพรดิเคตเฉพาะที่บนเคอร์เซอร์ปัจจุบันและกลยุทธ์ที่เลือก ดังนั้น greedy การหลีกเลี่ยง orphan และ keep-together จึงคลี่คลายได้ภายในการเดินแบบสตรีมเดียวกัน ข้อแลกเปลี่ยนคือการผูกมัดไปข้างหน้า องค์ประกอบที่สูงเกินไปจะล้นแทนที่จะปรับขนาดใหม่ และ keep-together จะคงอยู่เฉพาะเมื่อองค์ประกอบที่จับคู่กันทั้งคู่อยู่บนหน้าเดียวกัน

ภูมิหลังการออกแบบ: การสร้างเอกสารปริมาณสูง

พื้นผิว API

Class	Responsibility
StreamingLayoutEngine	กำหนดหน้าและตำแหน่งให้องค์ประกอบแบบไหล
FlowElement, FlowElementType	แบบจำลองและ enum ชนิดขององค์ประกอบ
LayoutRegion	บริเวณเนื้อหาต่อหน้า
PageBreakStrategy	enum พฤติกรรมการแบ่งหน้า
LayoutResult, PlacedElement	เอาต์พุตการจัดวาง

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

use NextPDF\Pro\FlowLayout\{StreamingLayoutEngine, LayoutRegion, PageBreakStrategy};

$engine = new StreamingLayoutEngine(
    region:   new LayoutRegion(/* x, y, width, height */),
    strategy: PageBreakStrategy::AvoidOrphans,
);
$result = $engine->layout($elements);

ตัวอย่างโค้ด — สำหรับใช้งานจริง

$result = $engine->layout($elements);
foreach ($result->placements as $placed) {
    $logger->debug('flow.placed', [
        'page' => $placed->pageIndex,
        'type' => $placed->element->type->value,
    ]);
}

กรณีขอบและข้อควรระวัง

• เอนจินยังคงจัดวางองค์ประกอบที่สูงกว่าบริเวณ แต่อาจล้น ให้กำหนดขนาดองค์ประกอบภายในความสูงของบริเวณ
• KeepTogether คงคู่ไว้ด้วยกันเฉพาะเมื่อทั้งคู่พอดีบนหน้าเดียว
• AvoidOrphans สำรองความสูงขององค์ประกอบอย่างน้อยสองเท่าก่อนแบ่ง

ประสิทธิภาพ

เค้าโครงเป็นเชิงเส้นตามจำนวนองค์ประกอบ เอนจินเป็นแบบสตรีม โดยไม่เก็บ tree ของเอกสารแบบเต็มไว้

บันทึกด้านความปลอดภัย

Flow Layout ดำเนินการบนเมทาดาทาขององค์ประกอบที่คุณจัดหาให้ โดยไม่ทำ I/O

ความสอดคล้องกับมาตรฐาน

Flow Layout นำพฤติกรรมการจัดวางของ NextPDF ไปใช้ โดยไม่มุ่งเป้าไปยังมาตรฐานเค้าโครงภายนอก

สัญญาพฤติกรรม

• StreamingLayoutEngine สร้างขึ้นด้วย LayoutRegion และ PageBreakStrategy และคืนค่า LayoutResult ขององค์ประกอบที่จัดวางแล้วพร้อมการกำหนดหน้าและตำแหน่งที่เป็นรูปธรรม
• PageBreakStrategy มีพฤติกรรมสามแบบ ได้แก่ Greedy (แบ่งเมื่อองค์ประกอบถัดไปไม่พอดี) AvoidOrphans (แบ่งก่อนกำหนด โดยสำรองความสูงขององค์ประกอบอย่างน้อยสองเท่า) และ KeepTogether (ปฏิบัติตาม keep-with-next เพื่อให้องค์ประกอบที่จับคู่กันอยู่บนหน้าเดียวเมื่อทั้งคู่พอดี)
• ข้อความและตารางสามารถแบ่งข้ามหน้าได้ ภาพและตัวเว้นระยะถูกจัดวางแบบอะตอมมิก องค์ประกอบที่สูงกว่าบริเวณยังคงถูกจัดวางแต่อาจล้น
• เอนจินเป็นแบบสตรีม โดยไม่เก็บ tree ของเอกสารแบบเต็มไว้และไม่ทำ I/O
• นี่คือเอนจินการจัดวางองค์ประกอบ โดยคำนวณการกำหนดหน้าและตำแหน่ง ไม่ใช่เอนจินการเรนเดอร์ HTML หรือ CSS

บันทึกขอบเขตของ Enterprise

Enterprise ไม่เปลี่ยนพฤติกรรมของ Flow Layout Enterprise เพิ่มฟีเจอร์ระดับสูงขึ้นที่บันทึกแยกต่างหาก โดยไม่จำเป็นสำหรับการใช้เอนจินการจัดวาง

ทางสำรอง / ทางเลือกของ Core

ไม่มีเอนจินการจัดวางองค์ประกอบใน Core ที่มีกลยุทธ์การแบ่งหน้า สำหรับการเรนเดอร์ HTML เป็น PDF ให้ใช้ไปป์ไลน์ HTML ของ Core แบบโอเพนซอร์ส ดู /modules/html/

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

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

ดูเพิ่มเติม

• Flow Layout — Deep Reference — การอ้างอิงคลาสและเมท็อดฉบับเต็ม
• Document — การประกอบเอกสาร
• Core HTML module — การเรนเดอร์ HTML เป็น PDF