---
id: gh-pixijs-accessibility
name: "pixijs-accessibility"
url: https://skills.yangsir.net/skill/gh-pixijs-accessibility
author: pixijs
domain: game-dev
tags: ["accessibility", "a11y", "pixijs", "game-development", "keyboard-navigation"]
install_count: 2300
rating: 4.30 (120 reviews)
github: https://github.com/pixijs/pixijs-skills/tree/main/skills/pixijs-accessibility
---

# pixijs-accessibility

> 此技能用于在 PixiJS v8 应用中添加屏幕阅读器和键盘导航功能。它通过创建不可见的 Shadow DOM 覆盖层，使辅助技术能够发现和激活可访问容器，从而显著提升应用的包容性和用户体验，确保所有用户都能无障碍地与交互式内容进行互动。

**Stats**: 2,300 installs · 4.3/5 (120 reviews)

## Before / After 对比

### 可访问性功能实现时间

**Before**:

在没有这个技能之前，开发者需要手动编写复杂的代码来处理屏幕阅读器和键盘导航，这不仅耗时，还容易出错，导致可访问性功能实现不完整或不一致。

**After**:

此技能通过提供标准化的 AccessibilitySystem 和属性，极大地简化了 PixiJS 应用的可访问性集成，显著缩短了开发周期并确保了功能完整性。

| Metric | Before | After | Change |
|---|---|---|---|
| 可访问性功能实现时间 | 8小时 | 1小时 | -87% |

### 辅助技术用户可访问性

**Before**:

在没有这个技能之前，依赖辅助技术的用户（如屏幕阅读器用户）难以有效操作 PixiJS 应用，导致用户群体受限，应用无法触达更广泛的用户。

**After**:

该 Skill 确保了 PixiJS 应用能够被辅助技术用户无障碍地访问和使用，显著扩大了用户基础，提升了应用的包容性和市场潜力。

| Metric | Before | After | Change |
|---|---|---|---|
| 辅助技术用户可访问性 | 20% | 95% | +375% |

## Readme

Enable screen reader and keyboard navigation via PixiJS's AccessibilitySystem. The system creates an invisible shadow DOM overlay positioned over accessible containers so assistive technology can discover and activate them.

## Quick Start

```ts
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());
```

**Related skills:** `pixijs-events` (pointer/tap handlers), `pixijs-scene-dom-container` (HTML elements on canvas), `pixijs-application` (init options).

**Key points:**

- By default the system activates only after the user presses Tab. Set `enabledByDefault: true` in Application init for immediate activation.
- On mobile, the system creates a hidden touch hook; screen-reader focus activates accessibility for the whole session.
- The AccessibilitySystem requires the main thread; it is not available in a Web Worker.

## Core Patterns

### Container accessible properties

```ts
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;
```

Available properties on any Container:

- `accessible` (boolean) - enables the accessible overlay div
- `accessibleTitle` (string) - sets the `title` attribute on the shadow div
- `accessibleHint` (string) - sets the `aria-label` attribute
- `accessibleText` (string) - sets inner text content of the shadow div
- `accessibleType` (string) - HTML tag for the shadow element, defaults to `'button'`
- `tabIndex` (number) - tab order for keyboard navigation (only applied when `interactive` is true / `eventMode` is `'static'` or `'dynamic'`)
- `accessibleChildren` (boolean, default `true`) - when `false`, prevents child containers from being accessible
- `accessiblePointerEvents` (string) - CSS `pointer-events` value on the shadow div

### Custom tab order

Give each accessible container a `tabIndex` to control the order assistive tech walks through them. Higher numbers come later; equal numbers fall back to scene-graph order.

```ts
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` is only forwarded to the shadow div when the container is `interactive` (`eventMode` is `'static'` or `'dynamic'`). Without that, the system clamps the div's tabIndex back to `0`, and the order you set is ignored.

### Programmatic control

```ts
import { Application } from "pixi.js";

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

// Enable accessibility at runtime
app.renderer.accessibility.setAccessibilityEnabled(true);

// Check current state
console.log(app.renderer.accessibility.isActive);
console.log(app.renderer.accessibility.isMobileAccessibility);

// Full init options:
await app.init({
  accessibilityOptions: {
    enabledByDefault: true, // activate immediately (default: false)
    debug: true, // makes overlay divs visible (default: false)
    activateOnTab: true, // Tab key activates system (default: true)
    deactivateOnMouseMove: false, // stay active when mouse moves (default: true)
  },
});
```

The system can also be configured via static defaults before creating the Application:

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

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

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

### Handling accessible interactions

```ts
import { Sprite } from "pixi.js";

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

// Screen readers trigger click/tap events through the shadow DOM element
button.on("pointertap", () => {
  submitForm();
});
```

When accessibility is active and a user activates a shadow div (via Enter/Space key or screen reader action), the system dispatches `click`, `pointertap`, and `tap` FederatedEvents to the corresponding container. Focus on the shadow div dispatches `mouseover`, and focus-out dispatches `mouseout`. Both `eventMode` and `accessible` should be set for full keyboard + pointer support.

## Common Mistakes

### [MEDIUM] Expecting accessibility to be active without Tab key press

The AccessibilitySystem does not create its DOM overlay until the user presses Tab (or, on mobile, focuses the touch hook). If your application needs accessibility immediately:

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

Or at runtime:

```ts
app.renderer.accessibility.setAccessibilityEnabled(true);
```

Without one of these, automated accessibility testing tools will not find the overlay elements.


### [MEDIUM] Setting accessible without accessibleTitle

Wrong:

```ts
const sprite = new Sprite();
sprite.accessible = true;
// no title or hint set
```

Correct:

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

A container with `accessible = true` but no `accessibleTitle` or `accessibleHint` gets a fallback title of `"container {tabIndex}"`. Screen readers will announce this generic label with no useful context. Always provide at least `accessibleTitle`.


### [MEDIUM] Accessibility deactivates when moving mouse

By default, `deactivateOnMouseMove` is `true`. Any mouse movement after Tab-activation will deactivate the overlay. This is by design (assumes keyboard-only users don't use a mouse), but it makes testing with a mouse frustrating.

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


### [MEDIUM] Not importing accessibility extension in custom builds

When using `skipExtensionImports: true` for a custom build, the accessibility extension is not automatically registered. You must import it explicitly:

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

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

Without this import, `app.renderer.accessibility` will be undefined and no shadow DOM layer will be created.


## API Reference

- [AccessibilitySystem](https://pixijs.download/release/docs/accessibility.AccessibilitySystem.html.md)
- [AccessibilitySystemOptions](https://pixijs.download/release/docs/accessibility.AccessibilitySystemOptions.html.md)
- [AccessibilityOptions](https://pixijs.download/release/docs/accessibility.AccessibilityOptions.html.md)
- [AccessibleOptions](https://pixijs.download/release/docs/accessibility.AccessibleOptions.html.md)
- [PointerEvents](https://pixijs.download/release/docs/accessibility.PointerEvents.html.md)


---
*Source: https://skills.yangsir.net/skill/gh-pixijs-accessibility*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-pixijs-accessibility/markdown*