ARIA işaret rollerini Connect ile etiketli PDF'ye eşleyin

ARIA işaret rollerini Connect ile etiketli PDF’ye eşleyin

Bir bakışta

HTML5 bölümleme öğeleri ve Accessible Rich Internet Applications (ARIA) işaret rolleri kullanan HTML’i Connect üzerinden gönderin. Etiketli içerik işlem hattı bunları PDF 2.0 standart yapı türlerine eşler; böylece yardımcı teknolojiler, görsel konum yerine işaretler üzerinden gezinebilir. Burada kullanılan erişilebilirlik denetimi Pro katmanına özgüdür: araç bir class_exists() yoklamasıyla saptanır ve yalnızca nextpdf/premium sunucuyla birlikte kurulduğunda kaydedilir. Belge oluşturma ve HTML alımı çekirdek araçlarla yapılır.

Erişilebilirlik aracı, bulguları PDF/UA-2’ye (ISO 14289-2) göre raporlar. Başarılı sonuç, aracın kendi değerlendirmesidir. Bu bir erişilebilirlik denetimidir; bağımsız bir uyumluluk belgelendirmesi değildir. Uyumluluğu veraPDF veya başka bir denetleyici belirler.

Kurulum

composer require nextpdf/server

Pro erişilebilirlik aracının çalışan dağıtımda mevcut olduğunu bir tools/list çağrısıyla doğrulayın (bkz. /connect/tool-catalog/). Araç mevcut değilse bu dağıtımda nextpdf/premium kurulu değil demektir; bu nedenle bu tarifin doğrulama adımı çalıştırılamaz.

Kavramsal genel bakış

Gruplama yapısı öğeleri, bir belgenin mantıksal yapısını bölümler ve benzeri kapsayıcılar hâlinde düzenler (ISO 32000-2 §14.8). HTML işlem hattı bu öğeleri şu şekilde eşler:

• <aside> ve role="complementary" → PDF 2.0 Aside standart türü
• <article> / role="article" → Art
• <nav> / role="navigation" → Sect

Standart olmayan bir yapı türü, yalnızca standart bir türe rol eşlemesi yapıldığında kabul edilebilir (PDF/UA-2 §8.2.5). İşlem hattı standart türü doğrudan üretir; bu nedenle elle rol eşlemesi yapmanız gerekmez. Yardımcı teknolojilerin içeriğe erişebilmesi için içeriğin yapı ağacında yansıtılması gerekir (PDF/UA-2 §8.2.4).

API yüzeyi

Araç adlarını çalışan kayıt defterine göre tools/list ile doğrulayın. Resmi katalog /connect/tool-catalog/. Bu tarif, çekirdek belge oluşturma ve HTML alımı araçlarını ve Pro erişilebilirlik denetimini kullanır. Sabit bir araç sayısı burada yinelenmez.

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

Etiketli bir PDF 2.0 belgesi oluşturun, işaret rolleri içeren HTML ekleyin ve MCP tools/call isteklerini sırayla göndererek belgeyi denetleyin:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_pdf",
    "arguments": { "page_size": "A4", "title": "ARIA Landmark Demo", "language": "en" }
  }
}

Herhangi bir HTML eklemeden önce etiketli içerik yayıcısını bağlayın. Yayıcının ilk içerik çağrısından itibaren etkin olması için belgeyi dil ayarıyla oluşturun.

Kod örneği — üretim

İşaret HTML’ini ekleyin ve erişilebilirlik denetimini çalıştırın. Başarısız bir durumu taşıma hatası olarak değil, incelenecek normal bir sonuç olarak ele alın:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<main><h1>Annual Report</h1><aside><h2>Aside</h2><p>Note.</p></aside><div role=\"complementary\"><h2>Related</h2><p>Links.</p></div><nav role=\"navigation\"><p>Skip nav</p></nav></main>"
    }
  }
}

Denetim yanıtı, gözlemlediği yapı ağacını ve PDF/UA-2 bulgularının özetini raporlar. Hem <aside> hem de <div role="complementary"> aynı Aside standart türüne indirgenir.

Uç durumlar ve dikkat edilecek noktalar

• Etiketli yayım, içerikten önce etkin değil. Belge dil / etiketli kip ile oluşturulmadıysa ilk HTML eklemesi etiketsiz içerik üretir ve denetim etiketli içerik hatası raporlar. Belgeyi dil ayarıyla yeniden oluşturun.
• Bölümleme öğesinde çakışan rol (<aside role="navigation">) bir uyarı üretir. Çakışan rolü kaldırın veya bir <div> kullanın.
• Araç mevcut değil. nextpdf/premium olmadan Pro erişilebilirlik aracı kaydedilmez ve doğrulama adımı, bilinmeyen araç hatasıyla başarısız olur.

Performans

Ön bilgi bütçesi bir belgelendirme üst sınırıdır. İşaret eşlemesi normal yerleşim geçişinin bir parçasıdır. Tipik belgeler için ayrı, ölçülebilir bir aşama eklemez.

Güvenlik notları

Connect’in genel taşıma kuralının ötesinde ek bir yönerge geçerli değildir: belge içeriğini veya HTML gövdesini dışarıya yayımlanan bir günlük düzeyinde kayda geçirmeyin.

Uyumluluk

PDF/UA-2 eşlemesi

HTML	PDF 2.0 standart türü
<aside>, role="complementary"	Aside
<article>, role="article"	Art
<nav>, role="navigation"	Sect

Etiket → ISO 32000-2 §14.9 çapraz başvuru

İddia	Madde	reference_id
Gruplama öğeleri, mantıksal yapıyı bölümler hâlinde düzenler	ISO 32000-2 §14.8
Standart olmayan türler, standart bir türe rol eşlemesi gerektirir	PDF/UA-2 §8.2.5
İçeriğe yapı ağacı üzerinden erişilebilmelidir	PDF/UA-2 §8.2.4

WCAG 2.2 eşlemesi

İşaret tabanlı gezinme, içerik düzeyinde WCAG 2.2 SC 1.3.1 (Info and Relationships) ve SC 2.4.1 (Bypass Blocks) başarı ölçütlerini destekler. Yapıyı PDF biçimi taşır. WCAG düzeyindeki içerik oluşturma kararlarından içerik yazarı sorumlu olmaya devam eder.

Başarılı bir erişilebilirlik aracı sonucu, erişilebilirlik denetimidir; uyumluluk belgelendirmesi değildir. PDF/UA-2 uyumluluğunu bağımsız bir denetleyici (örneğin veraPDF) belirler.

Ticari bağlam

Erişilebilirlik denetimi aracı Pro katmanına özgüdür ve yalnızca nextpdf/premium sunucuyla birlikte kurulduğunda kaydedilir.

Connect ayrıntıları

Taşıma kullanılabilirliği (MCP / REST / gRPC)

Şunları create_pdf, add_html ve erişilebilirlik denetimini, paylaşılan araç yürütücüsü aracılığıyla MCP tools/call, REST araç uç noktası ve gRPC hizmeti üzerinden aynı şekilde çağırın.

HITL risk katmanı

Belge oluşturma ve HTML alımı dikkat düzeyindedir (otomatik yürütülür, denetim günlüğüne kaydedilir). Erişilebilirlik denetimi salt okunurdur. Bu araçların hiçbiri varsayılan olarak approval_required değildir. Bkz. /connect/hitl-risk-tiers/.

Onay geçidi JSON zarfı

Operatör yapılandırmasındaki bir geçersiz kılma bu araçlardan birini approval_required düzeyine yükseltmediği sürece bu araçlar geçidi tetiklemez. Geçit uygulandığında, sınama zarfı ve tek kullanımlık jeton sözleşmesi şu belgeye uyar: /connect/hitl-risk-tiers/.

Ayrıca bkz.

• /cookbook/connect/figure-caption/ — iç içe Figure / Caption yapısı.
• /cookbook/connect/aria-noteref-pattern/ — dipnot başvurusu ve gövde rolleri.
• /connect/tool-catalog/ — katman başına araç kümesi hesaplaması.
• /connect/hitl-risk-tiers/ — risk modeli ve geçit.