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

ภาพรวมโดยสรุป

หน้านี้เป็นการอ้างอิงเชิงลึกสำหรับโมดูล Pro Flow Layout ครอบคลุมเอนจินการจัดวาง แบบจำลองอิลิเมนต์ กลยุทธ์การแบ่งหน้า ข้อกำหนดด้านพฤติกรรม และโหมดความล้มเหลวของกลยุทธ์เหล่านั้น StreamingLayoutEngine เดินอ่านรายการค่า FlowElement ตามลำดับ กำหนดดัชนีหน้าแบบเริ่มที่ศูนย์และตำแหน่งภายใน LayoutRegion ให้แต่ละตัว ผลลัพธ์คือ LayoutResult ของเรกคอร์ด PlacedElement ที่ไม่เปลี่ยนแปลง โมดูลนี้คำนวณเฉพาะการจัดวางเท่านั้น ไม่เรนเดอร์สิ่งใดและไม่ทำ I/O

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

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

ไม่มีแฟล็กใบอนุญาตรายฟีเจอร์ นี่คือความสามารถของรุ่น Pro

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

สัญลักษณ์ทั้งหมดอยู่ในเนมสเปซ NextPDF\Pro\FlowLayout วัตถุค่าทั้งหมดเป็น final และไม่เปลี่ยนแปลง

สัญลักษณ์	พารามิเตอร์	พฤติกรรมปริยาย	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
StreamingLayoutEngine::__construct	LayoutRegion $region, PageBreakStrategy $strategy = PageBreakStrategy::Greedy	ผูกบริเวณเนื้อหารายหน้าเข้ากับกลยุทธ์การแบ่ง	StreamingLayoutEngine	—	กลยุทธ์มีค่าปริยายเป็น Greedy
StreamingLayoutEngine::layout	list<FlowElement> $elements	เดินอ่านไปข้างหน้ารอบเดียว จัดวางตามลำดับพร้อมการแบ่งหน้าที่ขับเคลื่อนด้วยกลยุทธ์	LayoutResult	ไม่โยนเลย	รายการว่างให้ผลเป็นหนึ่งหน้าว่าง
StreamingLayoutEngine::withStrategy	PageBreakStrategy $strategy	สร้างเอนจินใหม่ที่ใช้บริเวณเดิม	self	—	ตัวรับไม่เปลี่ยนแปลง
StreamingLayoutEngine::withRegion	LayoutRegion $region	สร้างเอนจินใหม่ที่ใช้กลยุทธ์เดิม	self	—	ตัวรับไม่เปลี่ยนแปลง
FlowElement::__construct	FlowElementType $type, string $content, float $widthPt = 0, float $heightPt = 0, float $marginTopPt = 0, float $marginBottomPt = 0, bool $keepWithNext = false	วัตถุค่าอิลิเมนต์ที่ไม่เปลี่ยนแปลง	FlowElement	—	เป็นเส้นทางการสร้างเดียวสำหรับอิลิเมนต์ Table
FlowElement::text	string $content, float $height	อิลิเมนต์ข้อความที่มีความสูงซึ่งผู้เรียกวัดมา	self (static)	—	ความกว้าง 0 จะถูกแทนด้วยความกว้างของบริเวณขณะจัดวาง
FlowElement::image	string $path, float $width, float $height	อิลิเมนต์ภาพ โดย content เก็บพาธไว้	self (static)	—	เอนจินไม่เปิดไฟล์เลย
FlowElement::spacer	float $height	ช่องว่างแนวตั้งที่มีเนื้อหาว่าง	self (static)	—	—
FlowElement::pageBreak	—	ตัวทำเครื่องหมายการแบ่งแบบชัดแจ้ง	self (static)	—	ไม่ปล่อย PlacedElement
FlowElement::totalHeight	—	ความสูงรวมกับมาร์จินบนและล่าง	float	—	การตรวจความพอดีทั้งหมดใช้ค่านี้
FlowElementType	enum cases Text, Image, Table, Spacer, PageBreak	รองรับด้วยสตริง: text, image, table, spacer, page_break	—	—	—
FlowElementType::isBreakable	—	Text และ Table คืนค่า true ส่วนที่เหลือคืนค่า false	bool	—	เป็นการจัดหมวดเท่านั้น ดูข้อกำหนดการจัดวางแบบอะตอมด้านล่าง
LayoutRegion::__construct	float $x, float $y, float $width, float $height	กล่องเนื้อหาที่มีจุดกำเนิดมุมบนซ้าย วัดเป็นพอยต์	LayoutRegion	—	ไม่มีการตรวจสอบ ค่าจะถูกรับตามที่ให้มา
LayoutRegion::contains	float $px, float $py	การทดสอบจุดในบริเวณแบบรวมขอบเขต	bool	—	—
LayoutRegion::remainingHeight	float $currentY	ความสูงของบริเวณลบด้วยระยะแนวตั้งที่ใช้ไป	float	—	เป็นศูนย์หรือค่าติดลบเมื่อเคอร์เซอร์ล้นออกไปแล้ว
LayoutResult::__construct	list<PlacedElement> $placements, int $pageCount, float $totalHeightPt	ผลลัพธ์การจัดวางที่ไม่เปลี่ยนแปลง	LayoutResult	—	—
LayoutResult::placementsOnPage	int $pageIndex	กรองการจัดวางตามดัชนีหน้าแบบเริ่มที่ศูนย์	list<PlacedElement>	—	รายการที่คืนมาจะถูกจัดดัชนีใหม่
LayoutResult::isEmpty	—	เป็น true เมื่อไม่มีอิลิเมนต์ถูกจัดวาง	bool	—	เป็น true สำหรับอินพุตว่างและอินพุตที่มีแต่การแบ่ง
PageBreakStrategy	enum cases Greedy, AvoidOrphans, KeepTogether	รองรับด้วยสตริง: greedy, avoid_orphans, keep_together	—	—	—
PageBreakStrategy::label	—	ป้ายกำกับกลยุทธ์ที่อ่านเข้าใจได้	string	—	—
PlacedElement::__construct	FlowElement $element, int $pageIndex, float $x, float $y, float $width, float $height	เรกคอร์ดการจัดวางที่ไม่เปลี่ยนแปลง	PlacedElement	—	พิกัดเป็นพอยต์ จุดกำเนิดมุมบนซ้าย

public function layout(array $elements): LayoutResult
public function withStrategy(PageBreakStrategy $strategy): self
public function withRegion(LayoutRegion $region): self

public static function text(string $content, float $height): self
public static function image(string $path, float $width, float $height): self
public static function spacer(float $height): self
public static function pageBreak(): self

ข้อกำหนดด้านพฤติกรรม

StreamingLayoutEngine::layout() เดินอ่านไปข้างหน้ารอบเดียวบนรายการอินพุต สำหรับแต่ละอิลิเมนต์จะตรวจความพอดี แบ่งหน้าเมื่อจำเป็น แล้วบันทึก PlacedElement รายการอินพุตว่างจะคืน LayoutResult ที่ไม่มีการจัดวาง จำนวนหน้าเป็น 1 และความสูงรวมเป็น 0

เรขาคณิตของการจัดวางเป็นแบบกำหนดได้แน่นอน:

• x คือขอบซ้ายของบริเวณ
• y คือตำแหน่งเคอร์เซอร์ปัจจุบันบวกกับมาร์จินบนของอิลิเมนต์
• width คือ widthPt ของอิลิเมนต์เมื่อเป็นค่าบวก มิฉะนั้นเป็นความกว้างของบริเวณ
• height คือ heightPt ของอิลิเมนต์ตรงตามที่ให้มาทุกประการ

หลังการจัดวางแต่ละครั้ง เคอร์เซอร์จะเลื่อนไปตาม totalHeight() รวมมาร์จินด้วย จำนวนเดียวกันนี้จะสะสมเข้าไปใน LayoutResult::totalHeightPt

กฎการแบ่งหน้า เรียงตามลำดับการประเมิน:

• อิลิเมนต์ PageBreak แบบชัดแจ้งจะเพิ่มดัชนีหน้าและรีเซ็ตเคอร์เซอร์ไปที่ด้านบนของบริเวณ ไม่ปล่อยการจัดวางและไม่เพิ่มค่าใดเข้าไปในความสูงรวม
• เมื่อ totalHeight() ของอิลิเมนต์เกินความสูงที่เหลือ เอนจินจะแบ่ง เว้นแต่เคอร์เซอร์อยู่ที่ด้านบนของหน้าอยู่แล้ว
• Greedy ไม่เพิ่มเงื่อนไขใดอีก อิลิเมนต์ที่พอดีจะถูกจัดวางเสมอ
• AvoidOrphans แบ่งก่อนอิลิเมนต์ที่พอดี เมื่อพื้นที่ที่เหลือหลังการจัดวางจะเป็นค่าบวกแต่ต่ำกว่าครึ่งหนึ่งของความสูงที่อิลิเมนต์นั้นต้องการ ความสูงของอิลิเมนต์เองคือหน่วยอ้างอิง โดยมีตัวหารคงที่เป็นสอง ไม่เกี่ยวข้องกับเมตริกฟอนต์ใดๆ และไม่แบ่งที่ด้านบนของหน้าเลย
• KeepTogether แบ่งก่อนอิลิเมนต์ที่พอดี เมื่อแฟล็ก keepWithNext ถูกตั้ง มีอิลิเมนต์ถัดไปอยู่ เคอร์เซอร์ไม่อยู่ที่ด้านบนของหน้า และ totalHeight() รวมของอิลิเมนต์ทั้งสองเกินพื้นที่ที่เหลือ แฟล็กบนอิลิเมนต์ตัวสุดท้ายไม่มีผล

การจัดวางแบบอะตอม: เอนจินจัดวางทุกอิลิเมนต์เป็นหน่วยเดียว ไม่แบ่งเนื้อหาอิลิเมนต์ข้ามหน้าเลย FlowElementType::isBreakable() จัดหมวดว่าชนิดใดที่ผู้เรียกอาจแบ่งล่วงหน้าเป็นอิลิเมนต์เล็กลง ตัวเอนจินเองไม่อ้างอิงค่านี้

ความไร้สถานะและความกำหนดได้แน่นอน: เอนจินเก็บเพียงบริเวณและกลยุทธ์ของมัน layout() ไม่แชร์สถานะระหว่างการเรียก และอินพุตเดียวกันให้ผลลัพธ์เดียวกัน withStrategy() และ withRegion() คืนเอนจินใหม่และไม่แก้ไขตัวรับเลย

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

• ไม่มีเมธอดใดในโมดูลนี้โยนข้อยกเว้น ไม่มีลำดับชั้นข้อยกเว้นให้จับ
• คอนสตรักเตอร์ไม่ตรวจสอบสิ่งใด มิติของบริเวณที่เป็นค่าลบหรือศูนย์ ความสูงอิลิเมนต์ที่เป็นค่าลบ และมาร์จินที่เป็นค่าลบล้วนถูกยอมรับและไหลผ่านการคำนวณโดยไม่เปลี่ยนแปลง
• อิลิเมนต์ที่สูงกว่าบริเวณก็ยังถูกจัดวาง ที่ด้านบนของหน้าจะถูกวางไว้ตรงนั้นและล้นออก ส่วนตำแหน่งอื่นเอนจินจะแบ่งก่อนแล้วอิลิเมนต์ล้นออกบนหน้าใหม่ อิลิเมนต์ถัดไปจะกระตุ้นการแบ่งเสมอ การล้นจึงถูกจำกัดอยู่ในหน้าเดียว
• PageBreak ที่นำหน้าจะวางอิลิเมนต์เนื้อหาแรกบนดัชนีหน้า 1 ทำให้จำนวนหน้าอย่างน้อย 2
• อิลิเมนต์ PageBreak ที่ต่อเนื่องกันแต่ละตัวจะเพิ่มตัวนับหน้า ทำให้เกิดหน้าว่าง ตัวที่ตามท้ายจะทิ้งหน้าว่างหน้าสุดท้ายไว้ใน pageCount
• keep-together คงไว้เฉพาะเมื่ออิลิเมนต์ที่จับคู่กันทั้งคู่พอดีบนหน้าเดียวกัน คู่ที่ความสูงรวมเกินหนึ่งหน้าเต็มก็ยังถูกแบ่ง
• widthPt ที่ไม่เป็นค่าบวกจะถูกแทนด้วยความกว้างของบริเวณ การตรวจการแทนที่คือมากกว่าศูนย์อย่างเคร่งครัด
• remainingHeight() อาจคืนค่าศูนย์หรือค่าติดลบเมื่อเคอร์เซอร์ล้นออกไปแล้ว contains() ถือว่าขอบเขตของบริเวณอยู่ข้างใน
• placementsOnPage() ที่ใช้ดัชนีนอกช่วงจะคืนรายการว่าง
• โมดูลนี้ไม่ทำการดำเนินการเข้ารหัสลับใดๆ และไม่กำหนดพฤติกรรมเฉพาะสำหรับ FIPS

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

Flow Layout นำพฤติกรรมการจัดวางที่ NextPDF กำหนดมาใช้ ไม่ได้มุ่งไปยังมาตรฐานการจัดวางหรือการเรียงพิมพ์ภายนอก ดังนั้นหน้านี้จึงไม่มีตารางการอ้างอิงเชิงบรรทัดฐาน กลยุทธ์การแบ่งหน้าเป็นความหมายเชิงความหมายของ NextPDF ไม่ใช่การนำคุณสมบัติ CSS fragmentation หรือโมเดล keep ของ XSL-FO ใดๆ มาใช้ มิติทั้งหมดแสดงเป็นพอยต์ ตรงกับหน่วยที่ Core writer ใช้

ข้อความเหล่านี้อธิบายเฉพาะความสามารถเท่านั้น NextPDF ไม่ถือใบรับรองความสอดคล้องใดๆ และไม่มีการอ้างหรือบอกเป็นนัยถึงการรับรองใดๆ

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

• วัดเนื้อหาที่ต้นทาง เอนจินใช้ความสูงที่ผู้เรียกให้มา ไม่มีเมตริกฟอนต์และไม่ทำการวัดข้อความ
• แบ่งข้อความยาวหรือเนื้อหาตารางล่วงหน้าเป็นหลายอิลิเมนต์ก่อนจัดวาง ใช้ isBreakable() เพื่อตัดสินว่าตัวแบ่งอาจแบ่งชนิดใดได้
• ใช้เอนจินหนึ่งตัวซ้ำต่อหนึ่งเรขาคณิตหน้า สร้างรูปแบบต่างๆ ได้อย่างประหยัดด้วย withStrategy() และ withRegion()
• จัดกลุ่มเอาต์พุตรายหน้าด้วย placementsOnPage() เมื่อเรนเดอร์ทีละหน้า
• การจัดวางเป็นการเดินรอบเดียว เป็นเชิงเส้นตามจำนวนอิลิเมนต์ และไม่เก็บโครงสร้างต้นไม้เอกสารไว้ ผลลัพธ์เป็นแบบกำหนดได้แน่นอน ซึ่งเหมาะกับการทดสอบแบบ golden-file
• สำหรับการเรนเดอร์ HTML เป็น PDF ให้ใช้ไปป์ไลน์ Core HTML แทน โมดูลนี้ไม่ใช่เอนจิน HTML หรือ CSS

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

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

ดูเพิ่มเติม

• Flow Layout — ภาพรวมความสามารถ
• Document — การอ้างอิงเชิงลึก
• โมดูล Core HTML