تأليف النصوص باستخدام الخطوط والمحاذاة

لمحة سريعة

استخدم هذه الوصفة لإضافة النصوص والتحكم في عائلة الخط ونمطه وحجمه ومحاذاته. تعتمد الوصفة على ثلاث طرائق: 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 القياسية الأربعة عشر المسماة في ⁨ISO 32000-2.⁩ وقد يتجاوز ملف تعريف المطابقة ذلك فيتطلب خطًا بديلًا مضمَّنًا.

cell() يكتب سطرًا واحدًا داخل صندوق. أما multiCell() فيلفّ الكلمات في عمود وفق العرض وارتفاع السطر اللذين تحددهما. يبدأ النص في فضاء النص، وتربط مصفوفة النص فضاء النص بفضاء المستخدم ‏(⁨ISO 32000-2⁩). تعمل الدوال بوحدات المستخدم، ويُصدِر المحرك المصفوفة نيابة عنك.

حدّد المحاذاة عبر التعداد 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 — السمة ذاتها.
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');

عينة كود — للإنتاج

هذا المثال مستقل بذاته، لذا يمكن لإطار الاختبار تشغيله. وهو يعكس 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' راية زخرفة، وليست متغايرًا للخط.
تغطية المحارف في الخطوط القياسية. توفّر الخطوط القياسية الأربعة عشر ذخيرة ⁨WinAnsiEncoding⁩ ‏(⁨Windows-1252⁩) الكاملة. ويشمل ذلك اللاتينية المُشكَّلة لأوروبا الغربية، وعلامة اليورو، وعلامات الترقيم الطباعية الشائعة — شرطتي ⁨en⁩ و⁨em⁩، وعلامتي الاقتباس المنحنيتين، والنقطة المعدّدة، وعلامة الحذف، ورمز العلامة التجارية. أما النصوص الواقعة خارج تلك المجموعة، مثل الصينية أو اليابانية أو الكورية أو العربية أو العبرية أو اليونانية أو السيريلية أو التايلندية، فسجّل وجه ⁨TrueType⁩ وحدّده. راجع تضمين الخطوط وتجزئتها.
ارتفاع السطر مقارنةً بحجم الخط. ارتفاع كل سطر في multiCell() هو حجم الخط مضروبًا في نسبة ارتفاع السطر الافتراضية لملف القياسات. إذا كان الارتفاع صغيرًا جدًا، فقد تتداخل الأسطر.
الضبط في السطر الأخير. لا يمدّ multiCell() المضبوط السطر الأخير من الفقرة. يطابق هذا التنضيد التقليدي.

الأداء

توليد النص خطي بالنسبة إلى عدد المحارف، ⁨O⁩(⁨n⁩). الميزانية هي wall_ms: 1000, peak_mb: 64. وهي أقل من وصفات لغة ترميز النص الفائق ‏(⁨HTML⁩) لأنه لا توجد عملية تتالٍ ولا شجرة تخطيط. لا تُضمَّن الخطوط القياسية، ما يبقي المُخرَج صغيرًا.

ملاحظات أمنية

يُعرَض محتوى النص ولا يُفسَّر. تحقّق من طول السلاسل التي يوفرها المستخدم لإبقاء حجم المُخرَج محدودًا. لا يشغّل هذا المسار أي سكربت ولا يجلب أي مورد بعيد.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
عائلات ⁨Helvetica⁩ و⁨Times⁩ و⁨Courier⁩ من بين خطوط ⁨Type⁩ 1 القياسية الأربعة عشر.	⁨ISO 32000-2⁩	⁨iso32000_2_sec9⁩#⁨x1.x29⁩
تدعم عائلات ⁨standard-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⁩) الكاملة — لاتينية أوروبا الغربية إضافةً إلى علامات الترقيم الطباعية الشائعة. ويتطلب النص بأنظمة كتابة أخرى وجهًا مضمَّنًا.

السياق التجاري

غير منطبق.