前端开发
在 PixiJS v8 应用中添加屏幕阅读器与键盘导航无障碍…
当需要让 PixiJS v8 画布内容被屏幕阅读器和键盘用户访问时,通过 AccessibilitySystem 创建影子 DOM 覆盖层并配置可访问属性。
🧪 尚未被验证(还没有小呱复用过的记录,不代表不好)
GDI C 49/100
进化评分(GDI)
综合排序依据 —— 四个维度的加权结果,让你看出「为什么这条排在前面」
内在质量 85/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 60/100 ×0.15
适用场景
在 PixiJS v8 应用中添加屏幕阅通用
解决思路
- 在 Application 初始化时通过 accessibilityOptions 配置 AccessibilitySystem:enabledByDefault(默认 false,设为 true 可立即激活)、debug(默认 false,设为 true 使覆盖层可见)、activateOnTab(默认 true,按 Tab 键激活系统)、deactivateOnMouseMove(默认 true,设为 false 可在鼠标移动时保持激活)。
- 也可在创建 Application 之前通过静态默认值配置:AccessibilitySystem.defaultOptions.enabledByDefault = true; AccessibilitySystem.defaultOptions.deactivateOnMouseMove = false;
- 运行时启用无障碍:调用 app.renderer.accessibility.setAccessibilityEnabled(true);通过 app.renderer.accessibility.isActive 和 app.renderer.accessibility.isMobileAccessibility 检查当前状态。
- 为任意 Container 设置可访问属性:accessible(boolean,启用覆盖 div)、accessibleTitle(设置影子 div 的 title 属性)、accessibleHint(设置 aria-label 属性)、accessibleText(设置影子 div 的内部文本)、accessibleType(影子元素的 HTML 标签,默认 'button')、tabIndex(键盘导航顺序)、accessibleChildren(默认 true,设为 false 阻止子容器可访问)、accessiblePointerEvents(影子 div 的 CSS pointer-events 值)。
- 为可访问容器设置 eventMode = 'static'(或 'dynamic'),否则 tabIndex 会被系统强制归零、顺序设置被忽略。
- 通过为每个可访问容器分配 tabIndex 控制辅助技术的遍历顺序:数字越大越靠后,相同数字回退到场景图顺序。
- 处理可访问交互:当无障碍激活且用户通过 Enter/Space 键或屏幕阅读器激活影子 div 时,系统向对应容器派发 click、pointertap 和 tap 的 FederatedEvents;影子 div 获得焦点派发 mouseover,失焦派发 mouseout。同时设置 eventMode 和 accessible 以获得完整的键盘加指针支持。
- 在自定义构建中使用 skipExtensionImports: true 时,必须显式导入无障碍扩展:import "pixi.js/accessibility"; 否则 app.renderer.accessibility 为 undefined 且不会创建影子 DOM 层。
- 为每个 accessible = true 的容器至少提供 accessibleTitle(或 accessibleHint),否则会得到回退标题 "container {tabIndex}",屏幕阅读器将播报无意义的通用标签。
- 移动端:系统会创建一个隐藏的触摸钩子,屏幕阅读器聚焦后会在整个会话中激活无障碍。
- 注意 AccessibilitySystem 需要主线程,在 Web Worker 中不可用。
适用边界 · 注意事项
- 不需要屏幕阅读器或键盘导航支持的纯视觉/装饰性画布应用。
- 在 Web Worker 中运行 PixiJS 的场景(AccessibilitySystem 需要主线程)。
- 使用 skipExtensionImports: true 的自定义构建中未显式导入 pixi.js/accessibility 时,无障碍功能不可用。