المحتوى: نموذج المحتوى النصي والمهيكل

لمحة سريعة

تبني وحدة ⁨Content⁩ عوامل إظهار النص، وعوامل حالة النص، وظلال النص، و⁨JavaScript⁩ على مستوى المستند، وقواميس خصائص المحتوى المعلَّم. وتقع بين التخطيط ودفق المحتوى.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية

توفر وحدة ⁨Content⁩ البدائيات التي تحوّل النص المحلول إلى عوامل تنسيق ⁨PDF⁩. يُعد TextRenderer المكوّن المركزي؛ فهو يبني عامل إظهار النص لسلسلة نصية وعوامل حالة النص التي تسبقه. بموجب §9 من ⁨ISO 32000-2⁩ الصادر عن المنظمة الدولية للتوحيد القياسي (⁨ISO⁩)، يرسم العامل Tj محارف السلسلة بالخط الحالي والمعاملات الرسومية المرتبطة بالنص. يختار TextRenderer إما عامل إظهار مفردًا أو مصفوفة TJ ذات مواضع محددة، وذلك بحسب TypographyMode النشط. كما يطبّق تعديلات التقنين (⁨kerning⁩) عندما يستخدم الوضع مصفوفات TJ.

تُنمذَج حالة النص كمجموعة متكاملة. تأخذ setTextRenderingMode() تعدادًا من نوع TextRenderingMode. وتتطابق حالاته الثماني، واحدةً بواحدة، مع أوضاع عرض النص في ⁨ISO 32000-2⁩: التعبئة، والحدّ، والتعبئة ثم الحدّ، وغير المرئي، وأنواع القصّ الأربعة (الجدول 104). كما يتحكّم العارض في عرض الحدّ، والتباعد بين المحارف، والتباعد بين الكلمات، والتمدد الأفقي، وارتفاع النص، والاتجاه من اليمين إلى اليسار، وHyphenator الاختياري. يصدر استدعاء buildTextStateOperators() الحالة المتراكمة في كتلة عوامل واحدة.

TextShadow كائن قيمة يضم اللون، وإزاحتي ⁨X⁩ و⁨Y⁩ بوحدات المستخدم، والعتامة. يستخدمه العارض لإصدار تمريرة رسم ثانية عند الإزاحة. الإزاحات الافتراضية هي 0.5/−0.5 خفيفة بعتامة 0.5، وتشبه ظلًا ناعمًا في صفحات الأنماط المتتالية (⁨CSS⁩).

يدير JavaScriptManager البرمجة النصية على مستوى المستند. تسجّل includeJs() برنامجًا نصيًا للمستند. وتُسجّل addJsObject() كائن برنامج نصي مُسمّى. أما writeJavaScript() / writeOpenAction() فيسلسلان البرامج النصية ضمن الفهرس وضمن ⁨OpenAction.⁩ يتحقق المدير من صحة كل متن برنامج نصي ويرمّزه كسلسلة ⁨PDF⁩ قبل الإصدار.

يمثّل PropertiesRegistry مخزن خصائص المحتوى المعلَّم. تُعيد register() فهرس وسم ثابتًا لقاموس خصائص. وتربط registerOcg() / registerOcgs() مجموعات المحتوى الاختياري (⁨OCGs⁩) برقم الكائن. تسلسل writeProperties() السجلّ ضمن قاموس موارد الصفحة. وتقرأ وحدة ⁨ContentStream⁩ هذه البيانات عندما تفتح تسلسلًا معلَّمًا مزوّدًا بقائمة خصائص.

تتضمن هذه الوحدة مفكّكي ترميز للصور لأنهما يتعاملان مع تنسيقات أصيلة في ⁨PDF⁩ تدعم التمرير المباشر. يحلل JBig2Loader وJpxLoader بنى مقاطع ⁨JBIG2⁩ و⁨JPEG 2000⁩ ويعيدان ImageData دون تنقيط البكسلات. تمرّ البايتات المرمَّزة إلى العارض دون تغيير. عندما يحمل مصدر ⁨JBIG2⁩ مقطعًا عامًا منفصلًا، يضمّنه JBig2Loader عبر مرجع دفق /JBIG2Globals على كائن ⁨XObject⁩ للصورة؛ وتستمر صيغة ⁨in-stream/in-line⁩ في الترحيل ذهابًا وإيابًا كما في السابق. هذا توصيل بنيوي فقط: تمرّ بايتات المقطع العام دون تنقيط، ولا تُفكّك ترميزها.

واجهة ⁨API⁩

الصنف	الطرائق الرئيسية	الدور
`TextRenderer`	`buildTextShowOperator()`, `buildTextStateOperators()`, `setTextRenderingMode()`, `setTextStrokeWidth()`, `setTextShadow()`, `setFontSpacing()`, `setWordSpacing()`, `setFontStretching()`, `setTextRise()`, `setRTL()`, `setHyphenation()`	باني عوامل إظهار النص وحالة النص
`TextRenderingMode` (تعداد)	`Fill`, `Stroke`, `FillStroke`, `Invisible`, `FillClip`, `StrokeClip`, `FillStrokeClip`, `Clip`	أوضاع عرض النص في ⁨ISO 32000-2⁩
`TextShadow`	`__construct(Color, offsetX, offsetY, opacity)`	كائن قيمة لتمريرة الرسم بالإزاحة
`JavaScriptManager`	`includeJs()`, `addJsObject()`, `hasJavaScript()`, `writeJavaScript()`, `writeOpenAction()`	توصيل فهرس ⁨JavaScript⁩ على مستوى المستند
`PropertiesRegistry`	`register()`, `getTagIndex()`, `registerOcg()`, `registerOcgs()`, `getAll()`, `writeProperties()`	مخزن خصائص المحتوى المعلَّم + ⁨OCG⁩
`JBig2Loader`	`load()`, `loadFromString()`, `parseSegments()`	مفكّك ترميز ⁨JBIG2⁩ بالتمرير المباشر
`JpxLoader`	`load()`, `loadFromString()`, `parseBoxes()`	مفكّك ترميز ⁨JPEG 2000⁩ بالتمرير المباشر

شغّل composer docs:generate-api-php -- --module=Content للحصول على جدول ⁨PHPDoc⁩ الكامل.

عينة شيفرة — بداية سريعة

المصدر: examples/28-text-rendering.php.

<?php

declare(strict_types=1);

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

use NextPDF\Content\TextRenderer;
use NextPDF\Content\TextRenderingMode;

$renderer = new TextRenderer();
$renderer
    ->setTextRenderingMode(TextRenderingMode::FillStroke)
    ->setTextStrokeWidth(0.3)
    ->setWordSpacing(0.5);

$stateOps = $renderer->buildTextStateOperators();

عينة شيفرة — إنتاج

تضيف هذه العينة ظلًا ناعمًا وأداة فصل بشرطة، ثم تبني عامل الإظهار باستخدام دالة هروب يوفّرها المستدعي، وهي الحدّ المرجعي القانوني PdfStringEscaper من سجل قرار البنية ⁨ADR-015.⁩

<?php

declare(strict_types=1);

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

use NextPDF\Content\TextRenderer;
use NextPDF\Content\TextShadow;
use NextPDF\Graphics\Color;
use NextPDF\Support\PdfStringEscaper;

$renderer = new TextRenderer();
$renderer
    ->setTextShadow(new TextShadow(Color::rgb(0, 0, 0), 0.4, -0.4, 0.45))
    ->setRTL(false);

$showOp = $renderer->buildTextShowOperator(
    text: 'Quarterly report',
    fontKey: 'F1',
    metrics: $fontMetrics,
    escapeSegment: static fn (string $s): string => PdfStringEscaper::escapeLiteral($s),
);

$pageContent = $renderer->buildTextStateOperators() . $showOp;

الحالات الحدّية والمزالق

buildTextShowOperator() يُعيد سلسلة فارغة للإدخال الفارغ. لا تُصدِر Tj فارغًا؛ تحقّق عند المنبع إذا كان تخطيطك قد ينتج تشغيلات فارغة.
دالة الهروب إلزامية وهي المسؤولة عن أمان السلاسل النصية. مرّر PdfStringEscaper::escapeLiteral() القانوني من ⁨ADR-015.⁩ فأداة الهروب الجزئية تُنتج سلسلة نصية حرفية غير صحيحة نحويًا.
في نقطة أصل أعلى اليسار، يكون TextShadow::offsetY سالبًا باتجاه الأسفل. قيمة ⁨Y⁩ الموجبة تدفع الظل إلى الأعلى، وهو أمر نادرًا ما يكون مقصودًا.
يتحقق JavaScriptManager من صحة إدخال البرنامج النصي. تُرفض المتون النصية غير الصحيحة عند التسجيل، ولا تُسقَط بصمت وقت الكتابة.
لا ينقّط JBig2Loader وJpxLoader أبدًا. فهما يتحققان من الصحة ويمرّران البايتات المرمَّزة. يظهر المقطع التالف كخطأ تحليل، لا كصورة فارغة.
PropertiesRegistry::register() خامل (⁨idempotent⁩) لكل قاموس؛ تُعيد قواميس الخصائص المتطابقة استخدام فهرس وسم واحد.

الأداء

بناء العوامل من الرتبة ⁨O⁩(⁨n⁩) بدلالة طول السلسلة، مع تمريرة تقنين إضافية من الرتبة ⁨O⁩(⁨n⁩) عندما يستخدم وضع الطباعة مصفوفات TJ. لا توجد هنا تكلفة تخطيط أو تشكيل؛ فهذا العمل يبقى في وحدتي ⁨Typography⁩ و⁨Layout.⁩ تسلسل ⁨JavaScript⁩ والخصائص من الرتبة ⁨O⁩(⁨entries⁩). تستخدم محمّلات الصور بالتمرير المباشر تحليلًا من الرتبة ⁨O⁩(⁨bytes⁩) بتكلفة فك ترميز صفرية. وهذه ميزتها الرئيسية في أحمال عمل المستندات الممسوحة ضوئيًا. تبلغ قيمة performance_budget لحمل العمل المرجعي 1500 ⁨ms⁩ زمنًا فعليًا و64 ⁨MB⁩ ذروةً.

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

يقبل JavaScriptManager متون برامج نصية قد تأتي من قوالب غير موثوقة. وهو يتحقق من الصحة ويرمّز كل متن كسلسلة ⁨PDF⁩، لكن ⁨JavaScript⁩ المستند يظل سطح محتوى نشطًا. عطّله للمخرجات غير الموثوقة، أو جرّده عبر مسار التعقيم الموصوف في /modules/core/security/. يحلل JBig2Loader وJpxLoader بنى مقاطع غير موثوقة: قيّد حجم الإدخال وزمن التحليل، وشغّل الاستخراج في عامل مقيَّد عندما يكون المصدر مزوَّدًا من المستخدم. حدّ هروب النص هو دالة الاستدعاء التي يوفّرها المستدعي. مرّر دائمًا أداة الهروب القانونية حتى لا تتمكن بايتات التحكم من الخروج من السلسلة الحرفية.

المطابقة

تصدر الوحدة عوامل إظهار النص وحالة النص بما يتسق مع نموذج النص في §9 من ⁨ISO 32000-2.⁩ يشمل ذلك دلالات العامل Tj وأوضاع العرض في الجدول 104 المنعكسة في تعداد TextRenderingMode. هذه حقائق تنفيذية: ينتج src/Content/TextRenderer.php وتعداد TextRenderingMode أشكال العوامل، وتختبرها tests/Unit/Content/TextRenderer* وJavaScriptManagerIsoTest وPropertiesRegistryTest. وهي لا تؤكّد المطابقة الكاملة لـ ⁨PDF 2.0⁩ من طرف إلى طرف. يتبع عقد هروب السلاسل النصية ⁨ADR-015⁩ و§7.3.4.2 من ⁨ISO 32000-2.⁩ تحفظ مسارات التمرير المباشر لـ ⁨JBIG2⁩ و⁨JPEG 2000⁩ الدفوق المرمَّزة دون تغيير. يُضمَّن مقطع ⁨JBIG2⁩ عام منفصل كمرجع دفق /JBIG2Globals على كائن ⁨XObject⁩ للصورة؛ وهذا مُتحقَّق منه كتوصيل بنيوي، لا كادّعاء أمانة فك ترميز. تُتحقَّق المطابقة على مستوى المستند عبر مجموعتي الأوراكل والاختبارات الذهبية في /modules/core/conformance/.