จัดวางข้อความด้วยฟอนต์และการจัดแนว

ภาพรวมโดยย่อ

ใช้สูตรนี้เพื่อวางข้อความและควบคุมตระกูลฟอนต์ สไตล์ ขนาด และการจัดแนวของข้อความ ขั้นตอนนี้ใช้เมท็อดสามรายการ ได้แก่ setFont(), cell() และ multiCell() โค้ดนี้อ้างอิงจาก examples/04-text-and-fonts.php

การติดตั้ง

composer require nextpdf/core:^3

ข้อกำหนดเวอร์ชันนี้จะติดตั้งแพ็กเกจ nextpdf/core ตัวอย่างนี้ต้องใช้ PHP 8.4

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

setFont($family, $style, $size) จะเลือกหน้าฟอนต์ที่ใช้งานอยู่สำหรับการเรียกข้อความครั้งถัดไป อาร์กิวเมนต์ $style รวมแฟล็กสามตัวเข้าด้วยกัน ได้แก่ B (ตัวหนา) I (ตัวเอียง) และ U (ขีดเส้นใต้) แฟล็ก U ใช้สำหรับการตกแต่งข้อความ ส่วนแฟล็กอื่นจะเลือกรูปแบบของฟอนต์ ตระกูล Helvetica, Times และ Courier จะถูกแมปเป็นฟอนต์ Type 1 มาตรฐาน 14 ตัวที่ระบุไว้ใน ISO 32000-2 โปรไฟล์ความสอดคล้องอาจลบล้างพฤติกรรมนี้และกำหนดให้ต้องฝังฟอนต์ทดแทนได้

cell() จะเขียนข้อความหนึ่งบรรทัดภายในกล่อง ส่วน multiCell() จะตัดบรรทัดในคอลัมน์ตามความกว้างและความสูงของบรรทัดที่กำหนด พิกัดข้อความเริ่มในพื้นที่ข้อความ และเมทริกซ์ข้อความจะแมปพื้นที่ข้อความไปยังพื้นที่ผู้ใช้ (ISO 32000-2) การทำงานอยู่ในหน่วยผู้ใช้ และเอนจินจะสร้างเมทริกซ์ให้โดยอัตโนมัติ

กำหนดการจัดแนวด้วย enum Alignment ได้แก่ Left, Center, Right, Justify สำหรับ multiCell() การจัดชิดขอบทั้งสองด้านจะกระจายระยะห่างระหว่างคำตลอดทั้งบรรทัด

ส่วน API ที่เปิดให้ใช้

setFont(string $family, string $style = '', float $size = 12.0): static — NextPDF\Core\Concerns\HasTypography
cell(float $width, float $height, string $text = '', bool|string $border = false, bool $newLine = false, Alignment $align = Alignment::Left, bool $fill = false): static — NextPDF\Core\Concerns\HasTextOutput
multiCell(float $width, float $height, string $text, bool|string $border = false, Alignment $align = Alignment::Left): static — trait เดียวกัน
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify)

ตาราง PHPDoc ฉบับสมบูรณ์สร้างจากซอร์สโค้ด

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

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Heading', newLine: true);

$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Word-wrapped justified body text.', align: Alignment::Justify);

$doc->save(__DIR__ . '/out.pdf');

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

ตัวอย่างนี้มีครบในตัว จึงให้ test harness รันได้โดยตรง ตัวอย่างนี้อ้างอิงเนื้อหาของ examples/04-text-and-fonts.php และแสดงรูปแบบสไตล์ต่างๆ ฟอนต์หลายขนาด ข้อความแบบตัดบรรทัดที่จัดชิดขอบทั้งสองด้าน และการจัดแนวทั้งสามแบบ

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Text and Fonts');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Text and Font Styles', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Normal text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, 'Bold text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'I', 12);
$doc->cell(0, 8, 'Italic text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'BI', 12);
$doc->cell(0, 8, 'Bold-Italic text in Helvetica 12pt.', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Font Sizes', newLine: true);
foreach ([8, 10, 12, 14, 18] as $size) {
    $doc->setFont('helvetica', '', (float) $size);
    $doc->cell(0, $size * 0.8, "This is {$size}pt text.", newLine: true);
}
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Multi-Line Text (Word Wrap)', newLine: true);
$doc->setFont('helvetica', '', 11);
$paragraph = 'NextPDF is a modern PDF 2.0 library for PHP. It provides a '
    . 'fluent API for document creation. This paragraph demonstrates '
    . 'automatic word wrapping and justified alignment with multiCell().';
$doc->multiCell(0, 7, $paragraph, align: Alignment::Justify);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Text Alignment', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->cell(0, 8, 'Left-aligned text', newLine: true, align: Alignment::Left);
$doc->cell(0, 8, 'Center-aligned text', newLine: true, align: Alignment::Center);
$doc->cell(0, 8, 'Right-aligned text', newLine: true, align: Alignment::Right);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/compose-text-and-fonts.pdf');

echo "Wrote compose-text-and-fonts.pdf\n";

STDOUT ที่คาดไว้:

Wrote compose-text-and-fonts.pdf

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

ความกว้าง 0 หมายถึงความกว้างที่เหลืออยู่ เมื่อส่งค่า 0 ให้ทั้ง cell(0, ...) และ multiCell(0, ...) ทั้งสองเมท็อดจะใช้พื้นที่ไปจนถึงระยะขอบด้านขวา สำหรับกล่องที่มีความกว้างคงที่ ให้ระบุค่าความกว้างให้ชัดเจน
ลำดับของสตริงสไตล์ 'BI' และ 'IB' จะเลือกรูปแบบตัวหนาเอียงเดียวกัน เพราะตัวแยกวิเคราะห์ไม่คำนึงถึงลำดับของแฟล็ก แฟล็ก 'U' เป็นแฟล็กสำหรับการตกแต่ง ไม่ใช่รูปแบบของฟอนต์
ความครอบคลุมของกลีฟในฟอนต์มาตรฐาน ฟอนต์มาตรฐาน 14 ตัวเรนเดอร์ชุดอักขระของ WinAnsiEncoding (Windows-1252) ได้ครบถ้วน ซึ่งครอบคลุมละตินที่มีเครื่องหมายกำกับเสียงของยุโรปตะวันตก เครื่องหมายยูโร และเครื่องหมายวรรคตอนเชิงการพิมพ์ทั่วไป ได้แก่ เครื่องหมายขีด en และ em อัญประกาศโค้ง จุดนำ จุดไข่ปลา และเครื่องหมายการค้า สำหรับสคริปต์ที่อยู่นอกชุดนั้น เช่น จีน ญี่ปุ่น เกาหลี อาหรับ ฮีบรู กรีก ซีริลลิก หรือไทย ให้ลงทะเบียนและเลือกหน้าฟอนต์ TrueType ดู ฝังและสร้างซับเซ็ตของฟอนต์
ความสูงของบรรทัดเทียบกับขนาดฟอนต์ ความสูงต่อบรรทัดของ multiCell() คือขนาดฟอนต์คูณด้วยอัตราส่วนความสูงบรรทัดเริ่มต้นของโปรไฟล์เมตริก หากความสูงน้อยเกินไป บรรทัดอาจซ้อนทับกันได้
การจัดชิดขอบในบรรทัดสุดท้าย multiCell() ที่จัดชิดขอบทั้งสองด้านจะไม่ยืดบรรทัดสุดท้ายของย่อหน้า ซึ่งสอดคล้องกับการเรียงพิมพ์ตามแบบแผน

ประสิทธิภาพ

การสร้างข้อความมีความซับซ้อนเชิงเส้นตามจำนวนกลีฟ คือ O(n) งบประมาณคือ wall_ms: 1000, peak_mb: 64 ค่านี้ต่ำกว่าสูตรของ HyperText Markup Language (HTML) เพราะไม่มีการสืบทอดสไตล์แบบ cascade หรือโครงสร้างต้นไม้ของเค้าโครง ฟอนต์มาตรฐานจะไม่ถูกฝัง จึงช่วยให้เอาต์พุตมีขนาดเล็ก

หมายเหตุด้านความปลอดภัย

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

ความสอดคล้อง

ข้อความระบุ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
ตระกูล Helvetica, Times และ Courier เป็นส่วนหนึ่งของฟอนต์ Type 1 มาตรฐาน 14 ตัว	ISO 32000-2	iso32000_2_sec9#x1.x29
ตระกูลมาตรฐาน 14 ตัวรองรับชุดอักขระละตินทั้งหมด (WinAnsiEncoding, Windows code page 1252)	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
พิกัดข้อความอยู่ในพื้นที่ข้อความ และถูกแมปไปยังพื้นที่ผู้ใช้ด้วยเมทริกซ์ข้อความ	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

สูตรนี้แสดงวิธีที่ NextPDF จัดวางข้อความด้วยฟอนต์มาตรฐาน ความครอบคลุมของกลีฟคือชุดอักขระของ WinAnsiEncoding (Windows-1252) ทั้งหมด ได้แก่ ละตินยุโรปตะวันตกและเครื่องหมายวรรคตอนเชิงการพิมพ์ทั่วไป ข้อความในสคริปต์อื่นจำเป็นต้องใช้หน้าฟอนต์ที่ฝังไว้

บริบทเชิงพาณิชย์

ไม่มี