繪製由右至左的阿拉伯文 HTML

重點速覽

使用 writeHtml() 將由右至左（RTL）的 HTML 繪製成 PDF。設定 CSS direction: rtl 屬性，並註冊支援阿拉伯文的字型。引擎會依 Unicode 雙向演算法（UAX #9）將文字重排為視覺順序，並把阿拉伯文字母塑形成對應的上下文形式。本範例會繪製一張小型阿拉伯文發票。RTL 適用於阿拉伯文、希伯來文、波斯文與烏都文。希伯來文會重排，但不會塑形；對該文字系統而言，這是正確行為。

安裝

composer require nextpdf/core

你還需要一個支援阿拉伯文的 TrueType 或 OpenType 字型。該字型的字元對應表（character map）必須涵蓋 Arabic Presentation Forms-B 區塊。Noto Naskh Arabic 與 Amiri 都是適合的開放授權字體。

概念總覽

RTL 繪製需要兩項輸入：CSS direction: rtl 屬性，以及已註冊的阿拉伯文字型。

direction: rtl 會告訴版面配置由右至左排列文字。接著，引擎會使用 Unicode 雙向演算法（UAX #9）決定視覺順序。混合內容會正確排序：拉丁文字、阿拉伯文字與數字各自保留自己的方向。緊接在阿拉伯文之後的數字，會保持由左至右。

阿拉伯文是一種草書（cursive）文字系統，因此每個字母會依相鄰字母採用不同字形。引擎會為每個字母選擇起首形（initial）、中間形（medial）、結尾形（final）或孤立形（isolated），並套用 Lam-Alef 連字。這種上下文塑形需要字元對應表涵蓋 Arabic Presentation Forms-B 區塊的字型。僅含拉丁文字的字型（包含 standard-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	建立會讀取你已填入登錄表（registry）的文件。

範例會使用這些 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 在這個阿拉伯文句子中仍會保持由左至右。

程式碼範例 — 正式環境

這個自足（self-contained）的範例會繪製一張阿拉伯文發票表格。每個儲存格都帶有 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";">