Renderowanie arabskiego HTML od prawej do lewej

W skrócie

Renderuj do PDF treść HTML pisaną od prawej do lewej (RTL) za pomocą writeHtml(). Ustaw właściwość CSS direction: rtl i zarejestruj czcionkę obsługującą arabski. Silnik przekształca logiczną kolejność tekstu w kolejność wizualną zgodnie z algorytmem dwukierunkowym Unicode (UAX #9) oraz kształtuje litery arabskie w formy kontekstowe. Ten przepis renderuje niewielką arabską fakturę. RTL obejmuje arabski, hebrajski, perski i urdu. Dla hebrajskiego stosowane jest przestawianie kolejności bez kształtowania, co jest poprawne dla tego pisma.

Instalacja

composer require nextpdf/core

Potrzebujesz także czcionki TrueType lub OpenType obsługującej arabski. Jej mapa znaków musi obejmować blok Arabic Presentation Forms-B. Noto Naskh Arabic i Amiri to odpowiednie kroje na otwartych licencjach.

Przegląd koncepcyjny

Do renderowania RTL potrzebne są dwa elementy wejściowe: właściwość CSS direction: rtl oraz zarejestrowana czcionka arabska.

direction: rtl informuje mechanizm układu, że tekst ma być rozmieszczany od prawej do lewej. Silnik używa następnie algorytmu dwukierunkowego Unicode (UAX #9), aby wyznaczyć kolejność wizualną. Treść mieszana jest porządkowana poprawnie: słowa łacińskie, słowa arabskie i cyfry zachowują własny kierunek. Liczba następująca po tekście arabskim zachowuje układ cyfr od lewej do prawej.

Pismo arabskie jest łączone, dlatego każda litera używa innego glifu zależnie od sąsiadujących znaków. Silnik dobiera dla każdej litery formę początkową, środkową, końcową lub izolowaną oraz stosuje ligaturę Lam-Alef. Takie kształtowanie kontekstowe wymaga czcionki, której mapa znaków obejmuje blok Arabic Presentation Forms-B. Czcionka wyłącznie łacińska, w tym kroje standard-14, nie potrafi renderować arabskiego.

W tabeli każda komórka jest porządkowana i kształtowana oddzielnie, a komórki są wyrównywane do krawędzi początkowej: przy direction: rtl jest nią prawa krawędź. Logiczne wartości text-align start i end są rozstrzygane względem kierunku, więc start odwzorowuje się na prawą krawędź dla treści RTL.

Ustawiaj kierunek za pomocą właściwości CSS direction. Atrybut HTML dir nie jest na nią odwzorowywany. Aktualne granice implementacji opisuje sekcja RTL — bieżące ograniczenia.

Powierzchnia API

Symbol	Lokalizacja	Rola
Document::writeHtml(string $html): static	NextPDF\Core\Concerns\HasTextOutput	Renderuje fragment HTML w bieżącej pozycji kursora.
FontRegistry::register(string $fontFile, string $alias = '', int $fontIndex = 0): FontInfo	NextPDF\Typography\FontRegistry	Rejestruje krój arabski pod aliasem.
DocumentFactory::create(): Document	NextPDF\Core\DocumentFactory	Tworzy dokument, który odczytuje wypełniony rejestr.

Przykład korzysta z tych właściwości CSS: direction, font-family, text-align. W CSS font-family odwołuj się do zarejestrowanej czcionki przez jej alias w rejestrze.

Próbka kodu — Szybki start

<?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');

Nagłówek jest renderowany od prawej do lewej, a cyfry 380.00 pozostają od lewej do prawej wewnątrz zdania arabskiego.

Próbka kodu — Produkcja

Ten samodzielny przykład renderuje tabelę arabskiej faktury. Każda komórka ma direction: rtl oraz zarejestrowaną czcionkę arabską, więc silnik porządkuje i kształtuje każdy wiersz, a następnie wyrównuje komórki do prawej krawędzi.

<?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";">