pixijs-accessibility

PixiJSの AccessibilitySystem を通じてスクリーンリーダーとキーボードナビゲーションを有効にします。このシステムは、アクセシブルなコンテナーの上に配置された目に見えない shadow DOM オーバーレイを作成し、支援技術がそれらを見つけて起動できるようにします。

クイックスタート

const button = new Sprite(await Assets.load("button.png"));
button.accessible = true;
button.accessibleTitle = "Play game";
button.accessibleHint = "Starts a new game session";
button.eventMode = "static";
button.tabIndex = 0;
app.stage.addChild(button);

app.renderer.accessibility.setAccessibilityEnabled(true);

button.on("pointertap", () => startGame());

関連スキル: pixijs-events (ポインター/タップハンドラー)、pixijs-scene-dom-container (canvas上のHTML要素)、pixijs-application (初期化オプション)。

重要なポイント:

• デフォルトではユーザーがTabキーを押した後にのみシステムが起動します。Application初期化時に enabledByDefault: true を設定して即座に起動させてください。
• モバイルではシステムは隠れたタッチフックを作成します。スクリーンリーダーのフォーカスはセッション全体のアクセシビリティを有効にします。
• AccessibilitySystemはメインスレッドを必要とします。Web Workerでは利用できません。

コアパターン

コンテナーのアクセシビリティプロパティ

import { Container, Sprite } from "pixi.js";

const container = new Container();
container.accessible = true;
container.accessibleTitle = "Navigation menu";
container.accessibleHint = "Contains links to other pages";
container.eventMode = "static"; // required for custom tabIndex to apply
container.tabIndex = 0;
container.accessibleType = "div"; // defaults to 'button'

const sprite = new Sprite();
sprite.accessible = true;
sprite.accessibleTitle = "Close dialog";
sprite.accessibleText = "X"; // text content of the shadow div
sprite.eventMode = "static";
sprite.tabIndex = 1;

任意のコンテナーで利用可能なプロパティ:

• accessible (boolean) - アクセシブルなオーバーレイ div を有効化
• accessibleTitle (string) - shadow div の title 属性を設定
• accessibleHint (string) - aria-label 属性を設定
• accessibleText (string) - shadow div の内部テキストコンテンツを設定
• accessibleType (string) - shadow 要素のHTMLタグ、デフォルトは 'button'
• tabIndex (number) - キーボードナビゲーション用のタブ順序 (interactive が true または eventMode が 'static' もしくは 'dynamic' の場合にのみ適用)
• accessibleChildren (boolean、デフォルト true) - false の場合、子コンテナーのアクセシビリティを防止
• accessiblePointerEvents (string) - shadow div 上の CSS pointer-events 値

カスタムタブ順序

各アクセシブルコンテナーに tabIndex を指定して、支援技術が走査する順序を制御します。高い数値は後に来ます。同じ数値はシーングラフの順序にフォールバックします。

menuButton.accessible = true;
menuButton.eventMode = "static";
menuButton.tabIndex = 1;

playButton.accessible = true;
playButton.eventMode = "static";
playButton.tabIndex = 2;

settingsButton.accessible = true;
settingsButton.eventMode = "static";
settingsButton.tabIndex = 3;

tabIndex はコンテナーが interactive な場合 (eventMode が 'static' または 'dynamic') にのみ shadow div に転送されます。そうでない場合、システムは div の tabIndex を 0 に制限し、設定した順序は無視されます。

プログラマティック制御

import { Application } from "pixi.js";

const app = new Application();
await app.init({ width: 800, height: 600 });

// 実行時にアクセシビリティを有効化
app.renderer.accessibility.setAccessibilityEnabled(true);

// 現在の状態を確認
console.log(app.renderer.accessibility.isActive);
console.log(app.renderer.accessibility.isMobileAccessibility);

// 完全な初期化オプション:
await app.init({
  accessibilityOptions: {
    enabledByDefault: true, // 即座に起動 (デフォルト: false)
    debug: true, // オーバーレイ div を表示 (デフォルト: false)
    activateOnTab: true, // Tabキーがシステムを起動 (デフォルト: true)
    deactivateOnMouseMove: false, // マウス移動時もアクティブなままにする (デフォルト: true)
  },
});

このシステムは Application 作成前に静的なデフォルトで設定することもできます:

import { AccessibilitySystem, Application } from "pixi.js";

AccessibilitySystem.defaultOptions.enabledByDefault = true;
AccessibilitySystem.defaultOptions.deactivateOnMouseMove = false;

const app = new Application();
await app.init();

アクセシブルなインタラクションの処理

import { Sprite } from "pixi.js";

const button = new Sprite();
button.eventMode = "static";
button.accessible = true;
button.accessibleTitle = "Submit form";
button.tabIndex = 0;

// スクリーンリーダーは shadow DOM 要素経由でクリック/タップイベントをトリガー
button.on("pointertap", () => {
  submitForm();
});

アクセシビリティがアクティブな場合、ユーザーが shadow div を起動すると (Enter/Spaceキーまたはスクリーンリーダーアクション経由)、システムは対応するコンテナーに click、pointertap、tap FederatedEvents をディスパッチします。shadow div のフォーカスは mouseover をディスパッチし、フォーカス解除は mouseout をディスパッチします。完全なキーボード + ポインターサポートのため、eventMode と accessible の両方を設定する必要があります。

よくある間違い

[MEDIUM] Tabキー押下なしでアクセシビリティがアクティブになると想定する

AccessibilitySystem は、ユーザーが Tab キーを押す (またはモバイルではタッチフックにフォーカス) までは DOM オーバーレイを作成しません。アプリケーションがアクセシビリティを即座に必要とする場合:

const app = new Application();
await app.init({
  accessibilityOptions: {
    enabledByDefault: true,
  },
});

または実行時に:

app.renderer.accessibility.setAccessibilityEnabled(true);

どちらもない場合、自動化されたアクセシビリティテストツールはオーバーレイ要素を見つけられません。

[MEDIUM] accessibleTitle なしで accessible を設定

間違い:

const sprite = new Sprite();
sprite.accessible = true;
// title や hint が設定されていない

正しい:

const sprite = new Sprite();
sprite.accessible = true;
sprite.accessibleTitle = "Play button";
sprite.accessibleHint = "Click to start the game";

accessible = true だが accessibleTitle または accessibleHint がないコンテナーは、"container {tabIndex}" というフォールバックタイトルが付きます。スクリーンリーダーはこのジェネリックなラベルを役立つコンテキストなしで読み上げます。常に最低でも accessibleTitle を提供してください。

[MEDIUM] マウス移動時にアクセシビリティが無効化される

デフォルトでは、deactivateOnMouseMove は true です。Tab起動後のマウス移動はオーバーレイを無効化します。これは意図的です (キーボードのみユーザーがマウスを使用しないと想定)が、マウスでのテストを悔しくします。

await app.init({
  accessibilityOptions: {
    deactivateOnMouseMove: false,
  },
});

[MEDIUM] カスタムビルドでアクセシビリティ拡張をインポートしない

skipExtensionImports: true をカスタムビルドで使用する場合、アクセシビリティ拡張は自動的に登録されません。明示的にインポートする必要があります:

import "pixi.js/accessibility";
import { Application } from "pixi.js";

const app = new Application();
await app.init({ skipExtensionImports: true });

このインポートがないと、app.renderer.accessibility は undefined となり、shadow DOM レイヤーは作成されません。

API リファレンス

• AccessibilitySystem
• AccessibilitySystemOptions
• AccessibilityOptions
• AccessibleOptions
• PointerEvents