Connect 経由でアクセシブルな Figure と Caption を出力する

概要

<img> と <figcaption> を含む HTML の <figure> を Connect のトランスポート経由で送信します。パイプラインは標準構造要素の Figure を出力し、キャプションを Caption 子要素としてネストして、alt 属性で /Alt を設定します。検証ステップでは Pro 版 のアクセシビリティツールを使用します。NextPDF はこのツールを class_exists() で検出し、サーバーとともに nextpdf/premium がインストールされている場合にのみ登録します。ドキュメント作成と HTML 取り込みにはコアツールを使用します。

アクセシビリティツールの合格結果はアクセシビリティチェックの結果であり、独立した適合認証ではありません。

インストール

composer require nextpdf/server

tools/list 呼び出しで Pro 版のアクセシビリティツールが存在することを確認します。詳しくは /connect/tool-catalog/. を参照してください。

概念の概要

代替説明は、図などの非テキストコンテンツに対応するテキストを提供します（ISO 32000-2 §14.8）。構造要素は、その説明を /Alt エントリに保持します（ISO 32000-2 §14.8）。HTML の alt 属性は、出力される Figure の /Alt を設定します。パイプラインは <figcaption> を兄弟段落ではなく、ネストされた Caption 子要素として出力するため、キャプションは図の一部として到達可能な状態に保たれます（PDF/UA-2 §8.2.4）。

API サーフェス

tools/list を使い、実行中のレジストリでツール名を検証します。正式なカタログは /connect/tool-catalog/. です。このレシピでは、コアのドキュメントツールおよび HTML ツールに加えて、Pro 版のアクセシビリティチェックを使用します。ツール数はここでは再掲しません。

コードサンプル — クイックスタート

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

コードサンプル — 本番

figure マークアップを追加します。図をアクセシブルにするには、alt が必須です。

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id from create_pdf>",
      "html": "<figure><img src=\"diagrams/architecture.png\" alt=\"Three-tier deployment: web frontend, REST API, datastore\" /><figcaption>Figure 1 — Deployment topology.</figcaption></figure>"
    }
  }
}

アクセシビリティチェックを実行し、報告された構造ツリーを確認します。そこには /Alt を持つ単一の Figure が表示され、Caption 子要素がちょうど 1 つ含まれます。

エッジケースと注意点

alt のない <img>。 チェックは figure-alternate-text の失敗を報告します。説明的な alt を指定するか、純粋に装飾目的の画像をアーティファクトとしてマークしてください（/cookbook/connect/page-artifacts/ を参照）。
空の <figcaption>。 パイプラインは警告を出します。キャプションテキストを指定するか、要素を削除してください。
いずれの <figure> にも含まれない <figcaption>。 パイプラインはそれを孤立したキャプションとして出力します。<figure> で囲んでください。
ツールが存在しない。 nextpdf/premium がない場合、Pro 版のアクセシビリティツールは登録されず、検証は未知のツールエラーで失敗します。

パフォーマンス

フロントマターの予算はドキュメント上の上限値です。図の処理は通常のレイアウトパスの一部として実行されます。

セキュリティに関する注記

一般的な Connect トランスポートのガイダンス以外に、該当する項目はありません。

適合性

PDF/UA-2 マッピング

主張	条項	reference_id
非テキストコンテンツに対する代替説明	ISO 32000-2 §14.8
`/Alt` に保持される代替説明	ISO 32000-2 §14.8
構造ツリーを通じて到達可能な Caption	PDF/UA-2 §8.2.4

タグ → ISO 32000-2 §14.9 クロスリファレンス

Figure と Caption は標準構造タイプです。<figcaption> を Caption としてネストすることが、アクセシブルな図に求められる契約です。

WCAG 2.2 マッピング

alt テキストと関連付けられたキャプションを持つ図は、コンテンツレベルで WCAG 2.2 SC 1.1.1（非テキストコンテンツ）および SC 1.3.1（情報及び関係性）への対応を支援します。

アクセシビリティツールの合格結果はアクセシビリティチェックの結果であり、適合認証ではありません。その判定は独立したチェッカーが行います。

商用コンテキスト

アクセシビリティチェックツールは Pro 版であり、サーバーとともに nextpdf/premium がインストールされている場合にのみ登録されます。

Connect 固有の事項

トランスポートの利用可否（MCP / REST / gRPC）

create_pdf、add_html、およびアクセシビリティチェックは、共有のツールエグゼキューターを通じて、MCP、REST、gRPC 上で同じように呼び出せます。

HITL リスクティア

ドキュメント作成と HTML 取り込みは注意レベルです。アクセシビリティチェックは読み取り専用です。いずれもデフォルトでは approval_required ではありません。/connect/hitl-risk-tiers/. を参照してください。

確認ゲートの JSON エンベロープ

これらのツールは、オペレーターのオーバーライドによっていずれかが approval_required に引き上げられない限り、ゲートをトリガーしません。エンベロープと単回利用トークンの契約は /connect/hitl-risk-tiers/. にあります。

Connect 経由でアクセシブルな Figure と Caption を出力する

Connect 経由でアクセシブルな Figure と Caption を出力する

概要

インストール

概念の概要

API サーフェス

コードサンプル — クイックスタート

コードサンプル — 本番

エッジケースと注意点

パフォーマンス

セキュリティに関する注記

適合性

PDF/UA-2 マッピング

タグ → ISO 32000-2 §14.9 クロスリファレンス

WCAG 2.2 マッピング

商用コンテキスト

Connect 固有の事項

トランスポートの利用可否（MCP / REST / gRPC）

HITL リスクティア

確認ゲートの JSON エンベロープ

関連項目