渲染从右到左的阿拉伯语 HTML

重点速览

使用 writeHtml() 将从右到左（RTL）的 HTML 渲染为 PDF。设置 CSS direction: rtl 属性，并注册一款支持阿拉伯语的字体。引擎会使用 Unicode 双向算法（UAX #9）将文本重排序为视觉顺序，并把阿拉伯字母塑形为依上下文变化的字形。本示例会渲染一张小型阿拉伯语发票。RTL 适用于阿拉伯语、希伯来语、波斯语和乌尔都语。希伯来语会被重排序，但不会被塑形；这对该文字系统而言是正确的。

安装

composer require nextpdf/core

你还需要一款支持阿拉伯语的 TrueType 或 OpenType 字体。该字体的字符映射表必须覆盖 Arabic Presentation Forms-B 区块。Noto Naskh Arabic 和 Amiri 都是合适的开源授权字体。

概念总览

RTL 渲染需要两个输入：CSS direction: rtl 属性，以及一款已注册的阿拉伯语字体。

direction: rtl 会让布局从右向左放置文本。随后，引擎会用 Unicode 双向算法（UAX #9）解析视觉顺序。混合内容会正确排序：拉丁单词、阿拉伯单词和数字都会保留各自的方向。跟在阿拉伯语文本之后的数字，其各位数字仍保持从左到右。

阿拉伯语是连写文字，因此每个字母都会根据相邻字符使用不同的字形。引擎会为每个字母选择词首、词中、词尾或独立形式，并应用 Lam-Alef 连字。这种上下文塑形需要一款字符映射表覆盖 Arabic Presentation Forms-B 区块的字体。仅含拉丁文的字体（包括标准 14 款字体）无法绘制阿拉伯语。

在表格中，每个单元格都会独立进行重排序和塑形，并且单元格会对齐到起始边：在 direction: rtl 下就是右边缘。逻辑性的 text-align 取值 start 和 end 会按方向解析，因此对 RTL 内容而言，start 映射到右边缘。

请用 CSS direction 属性设置方向。HTML 的 dir 属性不会映射到该属性。当前实现的边界请参见 RTL — 当前限制。

API 一览

符号	位置	作用
Document::writeHtml(string $html): static	NextPDF\Core\Concerns\HasTextOutput	在当前光标位置渲染 HTML 片段。
FontRegistry::register(string $fontFile, string $alias = '', int $fontIndex = 0): FontInfo	NextPDF\Typography\FontRegistry	以别名注册阿拉伯语字体。
DocumentFactory::create(): Document	NextPDF\Core\DocumentFactory	创建一个会读取你已填充注册表的文档。

本示例使用以下 CSS 属性：direction、font-family、text-align。在 CSS font-family 中，通过注册表别名引用已注册的字体。

代码示例 — 快速上手

<?php

declare(strict_types=1);

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

use NextPDF\Core\DocumentFactory;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Typography\FontRegistry;

$fontRegistry = new FontRegistry();
$fontRegistry->register(__DIR__ . '/NotoNaskhArabic-Regular.ttf', alias: 'ArabicFont');

$documentFactory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $documentFactory->create();
$doc->addPage();

$doc->writeHtml(
    '<div style="direction: rtl; font-family: \'ArabicFont\';">'
    . '<h1>فاتورة</h1>'
    . '<p>المبلغ الإجمالي 380.00</p>'
    . '</div>'
);

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

标题会从右到左渲染，而数字 380.00 在这句阿拉伯语句子中仍保持从左到右。

代码示例 — 生产环境

这个自包含示例会渲染一张阿拉伯语发票表格。每个单元格都设置了 direction: rtl 并使用已注册的阿拉伯语字体，因此引擎会对每一行进行重排序和塑形，然后把单元格对齐到右边缘。

<?php

declare(strict_types=1);

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

use NextPDF\Core\DocumentFactory;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Typography\FontRegistry;

// Supply an Arabic-capable face whose cmap covers Arabic Presentation Forms-B.
// Embed only fonts you are licensed to embed.
$fontPath = __DIR__ . '/NotoNaskhArabic-Regular.ttf';
if (!is_file($fontPath)) {
    fwrite(STDERR, "Arabic font not found at {$fontPath}\n");
    exit(1);
}

$fontRegistry = new FontRegistry();
$fontRegistry->register($fontPath, alias: 'ArabicFont');

$documentFactory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $documentFactory->create();
$doc->setTitle('Arabic invoice');
$doc->addPage();

$html = <<<'HTML'
<div style="direction: rtl; font-family: 'ArabicFont'; font-size: 12pt;">
  <h1>فاتورة</h1>
  <table style="width: 100%; border-collapse: collapse;">
    <tr>
      <th style="border: 1px solid #333; padding: 6px;">الوصف</th>
      <th style="border: 1px solid #333; padding: 6px;">المبلغ</th>
    </tr>
    <tr>
      <td style="border: 1px solid #333; padding: 6px;">خدمات استشارية</td>
      <td style="border: 1px solid #333; padding: 6px;">380.00</td>
    </tr>
    <tr>
      <td style="border: 1px solid #333; padding: 6px;">الإجمالي</td>
      <td style="border: 1px solid #333; padding: 6px;">380.00</td>
    </tr>
  </table>
</div>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_OUT');
$doc->save($out !== false ? $out : __DIR__ . '/render-rtl-arabic-html.pdf');

echo "Wrote the Arabic invoice PDF\n";

  الوصف المبلغ   خدمات استشارية 380.00   الإجمالي 380.00  

HTML;$doc->writeHtml($html);$out = getenv('NEXTPDF_OUT');$doc->save($out !== false ? $out : __DIR__ . '/render-rtl-arabic-html.pdf');echo "Wrote the Arabic invoice PDF\n";">