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

دعم تشكيل الأنظمة الكتابية المعقّدة

لمحة سريعة

معاينة اختيارية. تشكيل الأنظمة الكتابية المعقّدة مُعطَّل افتراضيًا. عندما يكون مُعطَّلًا، يُصيِّر المحرّك عبر مسار نقطة الرمز إلى cmap الموجود — متطابق بايتًا ببايت مع بناء بدون الميزة. فعِّله فقط عندما يكون لديك libharfbuzz وخط قادر على التشكيل، وتحقّق من النتيجة.

يُضيف مُصيِّر ⁨HTML⁩ مُشكِّل أنظمة كتابية معقّدة اختياريًا للتبتية والمنغولية. عندما يكون المُشكِّل مُفعَّلًا، يُشكَّل أي مقطع تبتي أو منغولي مُكتشَف ضمن النطاق عبر libharfbuzz ويُصدَر كرموز محارف Identity-H. ويُغطّي المُشكِّل التبتية الأفقية في وجوه TrueType وCFF/OTTO، بما في ذلك الالتفاف، والمنغولية العمودية المضبوطة من الأعلى إلى الأسفل (TTB).

التثبيت

composer require nextpdf/core:^3

يُشحَن المُشكِّل في حزمة core. الخيار الاختياري CssFeatureFlags::$complexTextShaping هو @since 6.1.0. وتُعدّ libharfbuzz متطلَّبًا في وقت التشغيل عند تفعيل العَلَم — يستدعي المُشكِّل libharfbuzz عبر امتداد FFI في ⁨PHP⁩. وعند إيقاف العَلَم، لا تعتمد المكتبة على libharfbuzz.

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

تُعيد الأنظمة الكتابية المعقّدة ترتيب المحارف، وتستبدلها، وتُعيد وضعها بحسب السياق. وأي تخطيط ساذج من نقطة الرمز إلى المحرف يُصيِّرها خاطئةً بصورة ظاهرة. يُسلِّم المُشكِّل مقطعًا ضمن النطاق إلى libharfbuzz، التي تُطبِّق جداول تشكيل OpenType الخاصة بالخط، ويُصدر المحرّك تتابع المحارف الناتج كخط مُركَّب من النوع Type 0 بترميز Identity-H (⁨ISO 32000-2⁩ §⁨9.7.4⁩ — السلسلة المعروضة هي معرّفات CIDs من بايتين).

النطاق مقصود. يتعرّف المُشكِّل على مقاطع التبتية والمنغولية ويُشكِّلها؛ ولا يدّعي تغطية عامة للأنظمة الكتابية المعقّدة. وتُشكَّل التبتية الأفقية في وجوه TrueType وCFF/OTTO، مع التفاف السطور. وتُشكَّل المنغولية عموديًا، من الأعلى إلى الأسفل.

حدّ الإغلاق الآمن — صارم ومُحدَّد النوع

لا يُصدر المُشكِّل أبدًا محارف غير مُشكَّلة ومكسورة بصريًا كارتداد. وأي مقطع لا يمكن تشكيله بأمانة يطرح استثناءً مُحدَّد النوع بدلًا من ذلك:

ComplexScriptShapingException — تعذّر تشكيل المقطع بأمانة: الخط يفتقر إلى المحارف اللازمة (ينتج عنه .notdef)، أو طُلِب من وجه CFF التشكيل في المسار العمودي، أو يحتوي المقطع على رابط، أو يحتاج عمود منغولي إلى التفاف (حالة خارج النطاق).
HarfBuzzUnavailableException — العَلَم مُفعَّل لكن libharfbuzz غير قابلة للوصول عبر FFI في وقت التشغيل.

عند إيقاف العَلَم off، يُصيَّر أي مقطع ضمن النطاق عبر مسار نقطة الرمز إلى cmap الموجود. وهذا قيد مُوثَّق، لا ادّعاء تشكيل: مسار الإيقاف لا يُطبِّق تشكيل OpenType، لذا لا تُضمَن الأشكال السياقية. لا تصف مُخرجات مسار الإيقاف بأنها “مُشكَّلة”.

حدّ الصدق — تكافؤ موضوعي، لا اعتماد جمالي

تُتحقَّق أمانة التشكيل موضوعيًا مقابل HarfBuzz: تطابق معرّفات المحارف المُصدَرة، وتعيين العناقيد، ومواضع المحارف مُخرجات HarfBuzz المرجعية (تكافؤ المحرف والعنقود والموضع). أما مراجعة جمالية من متحدّث أصلي — تُقيِّم ما إذا كانت النتيجة تُقرأ طبيعيًا لقارئ طليق — فهي متابعة مُتتبَّعة بعد الشحن. ولا يقدّم ⁨NextPDF⁩ أي ادّعاء بجودة لغوية في هذه الواجهة أو في هذه الوثائق. التكافؤ الموضوعي مُؤكَّد؛ والجودة الجمالية لا.

سطح الـ ⁨API⁩

الرمز	الموقع	الدور
`CssFeatureFlags::$complexTextShaping`	`src/Html/CssFeatureFlags.php`	عَلَم اختياري لمُشكِّل التبتية/المنغولية (الافتراضي `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	يُرفِق مجموعة الأعلام بتهيئة المستند.
`ComplexScriptShapingException`	`src/Font/Shaper/ComplexScriptShapingException.php`	يُطرَح عندما يتعذّر تشكيل مقطع ضمن النطاق بأمانة.
`HarfBuzzUnavailableException`	`src/Font/Shaper/HarfBuzzUnavailableException.php`	يُطرَح عندما يكون العَلَم مُفعَّلًا لكن libharfbuzz غير متوفّرة.

نموذج برمجي — بداية سريعة

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(complexTextShaping: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>',
);
$doc->save(__DIR__ . '/tibetan.pdf');

نموذج برمجي — إنتاجي

سجِّل خطًّا قادرًا على التشكيل، وأدخِل المستند في المُشكِّل، وعالِج وضعَي الفشل المُحدَّدَي النوع صراحةً. تصيير أمين أو استثناء واضح — لا مقطع محارف مكسور بصمت أبدًا.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\DocumentFactory;
use NextPDF\Exception\ComplexScriptShapingException;
use NextPDF\Exception\HarfBuzzUnavailableException;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Html\Css\CssFeatureFlags;
use NextPDF\Typography\FontRegistry;

$fontRegistry = new FontRegistry();
$fontRegistry->register('/path/to/NotoSerifTibetan-Regular.ttf', alias: 'NotoSerifTibetan');

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(complexTextShaping: true),
);

$factory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $factory->create($config);
$doc->setLanguage('bo');
$doc->addPage();

try {
    $doc->writeHtml('<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>');
} catch (HarfBuzzUnavailableException $e) {
    // The flag is on but libharfbuzz is not reachable. Install it, or turn the
    // flag off to fall back to the unshaped cmap path.
    throw $e;
} catch (ComplexScriptShapingException $e) {
    // The run cannot be shaped faithfully (missing glyphs, link in run,
    // out-of-scope case). Fix the font or the content; do not ship broken glyphs.
    throw $e;
}

$doc->save($out);

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

libharfbuzz مطلوبة عند التفعيل. مع تفعيل العَلَم وغياب libharfbuzz، يطرح المحرّك HarfBuzzUnavailableException. ولا يتدهور بصمت.
الإيقاف ليس “تشكيلًا”. عند إيقاف العَلَم، يُصيَّر أي مقطع ضمن النطاق عبر مسار cmap دون تشكيل OpenType. وهذا قيد مُوثَّق؛ لا تصفه بأنه مُخرجات مُشكَّلة.
النطاق هو التبتية والمنغولية. الأنظمة الكتابية المعقّدة الأخرى خارج النطاق في هذه الشريحة.
أي رابط في المقطع يُغلَق بأمان. أي مقطع يحتوي على تعليق رابط يطرح ComplexScriptShapingException، لأن مستطيل الرابط لا يمكنه تتبّع إعادة الترتيب المُشكَّلة.
لا ادّعاء بجودة لغوية. التكافؤ مع HarfBuzz مُؤكَّد؛ والجودة الجمالية من متحدّث أصلي متابعة مُتتبَّعة وغير مُدَّعاة.

الأداء

يُضيف التشكيل استدعاء libharfbuzz واحدًا لكل مقطع ضمن النطاق، بالإضافة إلى مرور إصدار المحارف، خطّيًا في عدد المحارف. والميزانية (wall_ms: 2000، peak_mb: 128) تتبع ملف CJK/الأنظمة الكتابية المعقّدة، لأن خطوط التشكيل كبيرة ومعالجة الخط تهيمن على التكلفة.

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

يُدخِل تفعيل المُشكِّل استدعاء FFI إلى libharfbuzz، وهي مكتبة أصلية. وتبقى ملفات الخطوط مُدخلات ثنائية غير موثوقة تُعالجها طبقة الطباعة بالتحقّق الموجود لديها قبل أن تصل إلى المُشكِّل. ويستهلك المُشكِّل وجوهًا مُسجَّلة مسبقًا ومُتحقَّقًا منها مسبقًا. عامِل مصدر الخطوط المُقدَّمة من المستخدم النهائي بوصفه غير موثوق، ووفِّر libharfbuzz من مصدر موثوق.

المطابقة

العبارة	المواصفة	البند
تُصدَر المقاطع المُشكَّلة كمعرّفات CIDs من بايتين بترميز Identity-H في خط مُركَّب من النوع Type 0.	ISO 32000-2	§9.7.4
يُطبِّق المُشكِّل استبدال المحارف ووضعها في OpenType الخاص بالخط.	OpenType Specification	GSUB / GPOS
يتبع تشكيل العناقيد خصائص النظام الكتابي للتبتية والمنغولية.	Unicode Standard Annex	Tibetan and Mongolian

هذا تطبيق معاينة محصور بالتبتية والمنغولية، مُتحقَّق منه لأجل التكافؤ الموضوعي مع HarfBuzz. ولا يقدّم أي ادّعاء بجودة لغوية ولا يُؤكِّد أي مطابقة ⁨PDF⁩ شاملة من طرفٍ إلى طرف للملف المُنتَج. ولا يُعاد إنتاج أي نص معياري.