Erişilebilirlik: etiketleme temelleri ve PDF/UA-2 yapı modeli

Bir bakışta

NextPDF Core, erişilebilir içerik üretmek için temel bileşenler sağlar: mantıksal bir yapı ağacı, standart rol eşlemesi, işaretli içerik etiketlemesi ve ISO 14289-2 (PDF/UA-2) ile ISO 32000-2 §14.7 içindeki yapı ağacı modeliyle uyumlu Best Current Practice (BCP) 47 dil öznitelikleri. Üretilen dosya, yalnızca nihai belge, yazarın içerik tercihleri ve harici bir denetleyici bu sonucu desteklediğinde uygun sayılır. Kitaplık, bu uygunluğu sizin adınıza beyan etmez.

Kurulum

composer require nextpdf/core

Kavramsal genel bakış

Etiketli bir Portable Document Format (PDF) dosyası, kökünde tek bir Document yapı öğesi bulunan mantıksal bir yapı ağacı içerir. Yardımcı teknolojiler, görsel yerleşime bağlı olmayan anlamlı bir okuma sırasını belirlemek için bu ağacı okur (ISO 32000-2 §14.7.2; ISO 14289-2 §8.2.5.2). NextPDF, bunu NextPDF\Accessibility ad alanındaki birlikte çalışan üç türle modeller.

StructureTree hiyerarşiyi yönetir. Her sayfa için işaretli içerik tanımlayıcıları ayırır, üst-alt iç içeliğini izler ve ISO 32000-2 §14.7 uyarınca yapı ağacı kökünü, yapı öğelerini, üst ağacı, rol haritasını ve PDF 2.0 standart yapı ad alanını serileştirir. createRoot(), zorunlu olan tek Document öğesini bir dil özniteliğiyle başlatır. addElement(), türü belirtilmiş alt öğeler ekler. hasRoot() ve rootHasChildren(), ağacın var olup olmadığını ve alt öğe içerip içermediğini bildirir.

StructureElement, tek bir yapı öğesi sözlüğü için değer nesnesidir. Standart yapı türünü (Tablo 368 adları, örneğin H1 ile H6 arası, P, L, LI, Table, Figure, Link), işaretli içerik tanımlayıcı girdilerini ve alternatif metin, yedek metin, başlık ve dil için isteğe bağlı erişilebilirlik özniteliklerini saklar. Tek bir öğe birden çok sayfaya yayılabilir. Her sayfa için bir tanımlayıcı girdisi biriktirir; böylece alt öğeler dizisi, işaretli içeriğe sayfa sınırları boyunca başvurur.

TaggedContentEmitter, Hypertext Markup Language (HTML) işlem hattını yapı ağacına bağlar. Document::enableTaggedPdf() etkin olduğunda, HTML işleyicisi yayıcıyı devreye alır; böylece blok düzeyindeki öğeler eşleştirilmiş işaretli içerik işleçleri ve bunlara karşılık gelen yapı öğesi düğümleri oluşturur. HtmlToStructureMap, HTML etiketlerinden PDF yapı türlerine tablo tabanlı bir eşleme sağlar (ISO 14289-2 §8). Yayıcı, HTML üst bilgi ve alt bilgi bölgeleri gibi dekoratif yinelenen içeriği yapı öğesi olmayan bir öğeye yönlendirir ve okuma sırasının dışında tutar.

Bcp47Validator, dil etiketlerini doğrular (Request for Comments (RFC) 5646). İyi biçimli bir sözdizimi denetimi ve kayıt defteri destekli bir geçerlilik denetimi sağlar. Katı mod (ConformancePolicy::strictUa2()), hatalı biçimli etiketleri yazma sırasında sessizce atmak yerine application programming interface (API) sınırında reddeder. Bu davranış, katalog dil girdisinin belirli bir dile çözümlenmesi gerektiğine ilişkin ISO 14289-2 §8.4.4 gereksinimiyle örtüşür.

API yüzeyi

Simge	Tür	Özet
`Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static`	yöntem	Yapı ağacını ve HTML köprüsünü etkinleştirir; mark-info ve katalog dil girdilerini ayarlar.
`Document::setLanguage(string $lang): static`	yöntem	Belge düzeyindeki doğal dili ayarlar (BCP-47).
`Document::isTaggedPdfEnabled(): bool`	yöntem	Etkin uygunluk modunun yapısal etiketlemeyi zorunlu kılıp kılmadığını bildirir.
`StructureTree::createRoot(string $lang = 'en'): int`	yöntem	Zorunlu olan tek `Document` kök öğesini oluşturur.
`StructureTree::addElement(int $parentIndex, string $type, int $pageIndex, ...): int`	yöntem	Türü belirtilmiş bir alt yapı öğesi ekler.
`StructureTree::hasRoot(): bool` ve `rootHasChildren(): bool`	yöntem	Ağacın var olup olmadığını ve alt öğe içerip içermediğini bildirir.
`StructureElement`	final sınıf	Tek bir yapı öğesi için değer nesnesi (alternatif metin, yedek metin, başlık, dil, tanımlayıcılar).
`RoleMap::standard(): array<string,string>`	static	Standart yapı türü sözlüğünü döndürür (ISO 32000-2 Tablo 368 ile PDF 2.0 türleri).
`Bcp47Validator::isWellFormed/isValid/validate/normalise`	yöntem	RFC 5646 dil etiketlerini sözdizimi ve kayıt defteri destekli denetimlerle doğrular.
`AccessibilityAutoFixerRegistry`	final sınıf	Sezgisel yapı düzelticileri için isteğe bağlı, PHP Standards Recommendation (PSR)-11 tarzı kayıt defteri.

Kod örneği — Hızlı başlangıç

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();

// The BCP 47 tag drives the catalog language entry and the
// structure-tree root language attribute.
$doc->enableTaggedPdf(lang: 'en');
$doc->setTitle('Tagged accessibility demo');
$doc->addPage();

// Semantic HTML maps to structure elements: h1 to /H1, p to /P,
// ul and li to /L plus /LI. Text runs are wrapped in
// marked-content operators with stable identifiers.
$doc->writeHtml('<h1>Document title</h1><p>Body paragraph.</p>');

$doc->save(__DIR__ . '/output/tagged.pdf');

Kod örneği — Üretim

<?php

declare(strict_types=1);

use NextPDF\Conformance\ConformancePolicy;
use NextPDF\Core\Document;
use NextPDF\Exception\InvalidConfigException;
use Psr\Log\LoggerInterface;

final class AccessibleReportWriter
{
    public function __construct(private readonly LoggerInterface $logger)
    {
    }

    public function render(string $html, string $bcp47Lang, string $outPath): void
    {
        $doc = Document::createStandalone();

        try {
            // strictUa2() rejects malformed BCP 47 tags at the API
            // boundary (ISO 14289-2 §8.4.4) instead of dropping silently.
            $doc->enableTaggedPdf($bcp47Lang, ConformancePolicy::strictUa2());
        } catch (InvalidConfigException $e) {
            $this->logger->error('Rejected language tag for tagged PDF', [
                'lang' => $bcp47Lang,
                'reason' => $e->getMessage(),
            ]);

            throw $e;
        }

        $doc->setTitle('Quarterly accessibility report')
            ->setLanguage($bcp47Lang)
            ->addPage();

        $doc->writeHtml($html);

        // The engine emits a Degraded / ComplianceRisk advisory directing
        // the caller to validate externally; surface it to operators
        // rather than treating tagged output as certified.
        foreach ($doc->getWarnings() as $warning) {
            $this->logger->warning('Tagged-PDF advisory', [
                'code' => $warning->code->value,
                'message' => $warning->message,
            ]);
        }

        $doc->save($outPath);
    }
}

Uç durumlar ve dikkat edilecek noktalar

Çağrı sırası. enableTaggedPdf() çağrısını writeHtml() öncesinde yapın. HTML işlem hattı, uygunluk modunu ayrıştırıcı oluşturulurken denetler ve daha önce işlenmiş içerik için yayıcıyı geriye dönük olarak bağlamaz.
Boş yapı ağacı. enableTaggedPdf() kullanan ancak eklenmiş yapı alt öğesi bulunmayan bir belge, meta verilerinde PDF/UA-2 olduğunu beyan etmez. Yayımlama eşiği rootHasChildren() yöntemidir, hasRoot() değil; çünkü doğrulayıcılar, boş bir yapı ağacıyla PDF/UA-2 olduğunu ileri süren bir dosyayı reddeder (ISO 14289-2 §5; EmptyTaggedPdfDoesNotAdvertisePdfUa2Test ile doğrulanmıştır).
Uygunluk modunun üzerine yazılması. Aynı belgede enablePdfA() ve enableTaggedPdf() çağrılarını yaptığınızda, tek değerli uygunluk ayırıcısında son çağrı geçerli olur. Yan etkiler (yapı ağacı, mark-info) birikimli kalır ve NextPDF, bu üzerine yazmanın gözlemlenebilir olması için bir CONFORMANCE_MODE_CLOBBERED uyarısı yayar.
Otomatik düzelticiler kendiliğinden çalışmaz. Yerleşik düzelticiler (EmptyTagStripper, LegacyLangNormaliser, RootLangFallback) NextPDF\Accessibility\AutoFixer\* altında gelir ancak hiçbir zaman otomatik olarak kaydedilmez. Bunları AccessibilityAutoFixerRegistry üzerine açıkça kaydetmeniz gerekir.

Bilinen sınırlamalar

NextPDF, PDF/UA-2 yapı ağacı modeliyle tutarlı yapı yayar ancak türetemediği anlamsal bilgiyi oluşturmaz. Aşağıdakiler için işaretleme veya öznitelik sağlamanız gerekir; NextPDF bunları sizin için oluşturmaz:

görseller ve diğer metin dışı içerik için alternatif metin;
HTML işaretlemenin ifade ettiğinin ötesinde tablo başlığı kapsamı ve başlıktan hücreye ilişkilendirmeler;
görünen bağlantı metni kendi kendini açıklamadığında bağlantı amacı metni;
görsel olarak liste biçiminde düzenlenmiş ancak liste işaretlemesi bulunmayan içerik için liste anlamı;
kaynak sırası amaçlanan okuma sırasından farklı olduğunda düzeltilmiş okuma sırası;
belirsiz içerik için dekoratif ile anlamlı arasındaki ayrıma dayalı sınıflandırma.

NextPDF, uçtan uca PDF/UA-2 doğrulaması yapmaz. Çalışma zamanında, çağıranı üretime almadan önce çıktıyı harici bir denetleyiciyle doğrulamaya yönlendiren bir Degraded / ComplianceRisk bilgilendirmesi (PDFUA2_FOUNDATIONAL) yayar. Bir PDF/UA denetleyicisiyle doğrulayın (örneğin, veraPDF). NextPDF, uygunluğu sizin adınıza beyan etmez. Nihai belge uygunluğu, API çağrısına değil, içerik oluşturma tercihlerine ve bir doğrulayıcıya bağlıdır.

Performans

Yapı ağacı oluşturma, yapı öğesi sayısına göre doğrusaldır. Tanımlayıcı ayırma, işaretli içerik dizisi başına amorti edilmiş sabit zamandır. Serileştirme, öğe kümesi üzerinde tek bir doğrusal geçiştir. HTML tabanlı etiketlemede baskın maliyet, etiket yayma değil, HTML işlem hattının kendisidir. performance_budget içinde tanımlanan tarif başına üst sınır (1500 ms duvar saati süresi, 64 MB tepe kullanım), tipik bir çok sayfalı anlamsal belge için geçerlidir. Büyük belgeler, sayfa sayısıyla değil öğe sayısıyla doğrusal olarak ölçeklenir.

Güvenlik notları

Dil etiketleri ve erişilebilirlik öznitelikleri, PDF ad ve dize nesnelerine aktarılır. NextPDF, bunları PdfStringEscaper aracılığıyla kaçışlı hale getirir; böylece hatalı biçimli veya kötü amaçlı dil, alternatif metin, yedek metin ve başlık değerleri kendi PDF nesne bağlamlarından çıkamaz. Katı mod ayrıca kayıtlı olmayan BCP-47 etiketlerini API sınırında reddeder ve giriş yüzeyini yazıcıya ulaşmadan önce daraltır. Erişilebilirlik öznitelikleri, yazar tarafından sağlanan serbest metin taşıyabilir. Bunları güvenilmeyen çıktı olarak ele alın ve diğer belge içeriğini gözden geçirdiğiniz gibi gözden geçirin. Profil denetleyicisi davranışı için Uygunluk modülüne bakın.

Uygunluk

Bu sayfa, kitaplık davranışını madde tanımlayıcılarıyla eşler. Çıktınızın uygun olduğunu beyan etmez. Alıntılanan maddeler başka sözcüklerle ifade edilmiştir, asla doğrudan alıntılanmamıştır. Madde düzeyindeki tablo ve açıkça belirtilen kapsam dışı durumlar için PDF/UA-2 belirtim eşlemesine bakın. Alıntı parçası karmaları docs/public/modules/core/_normative-evidence-a11y.md içinde kaydedilir.