@eva/plugin-a11y 2.0.1-beta.27 → 2.0.1-beta.29

package/dist/plugin-a11y.cjs.js

@@ -37,6 +37,11 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+/**
+ * 生成唯一的标识符
+ * @param len 长度
+ * @param radix 基
+ */
 function uuid(len) {
     let chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'.split('');
     let uuid = [];
@@ -45,6 +50,11 @@ function uuid(len) {
         uuid[i] = chars[0 | (Math.random() * radix)];
     return uuid.join('');
 }
+/**
+ * 设置 dom 样式
+ * @param div 需要设置样式的dom元素
+ * @param style 样式属性
+ */
 const setStyle = (element, style) => {
     const { width, height, position, left = 0, top = 0, zIndex, pointerEvents, background } = style;
     element.style.width = `${width}px`;
@@ -68,7 +78,70 @@ const setTransform = (element, transform, ratioX, ratioY) => {
     element.style.webkitTransformOrigin = 'left top';
 };
 
+/**
+ * 无障碍组件（A11y/Accessibility）
+ *
+ * A11y 组件为游戏对象提供无障碍支持，使屏幕阅读器能够识别和朗读游戏内容。
+ * 它在游戏画布上方创建透明的 DOM 元素，携带 ARIA 属性，让视障用户也能使用游戏。
+ *
+ * 主要功能：
+ * - 提供屏幕阅读器可识别的文本标签
+ * - 支持 ARIA 角色和属性
+ * - 自动同步游戏对象的位置和尺寸
+ * - 支持交互事件的无障碍访问
+ *
+ * @example
+ * ```typescript
+ * // 为游戏对象提供朗读能力
+ * const button = new GameObject('button');
+ * button.addComponent(new A11y({
+ *   hint: '开始游戏按钮',
+ *   role: 'button'
+ * }));
+ *
+ * // 带交互事件的无障碍元素
+ * button.addComponent(new A11y({
+ *   hint: '点击开始游戏',
+ *   event: eventComponent
+ * }));
+ * ```
+ */
 class A11y extends eva_js.Component {
+    /**
+     * 构造无障碍组件
+     *
+     * @param param - 无障碍组件配置参数
+     * @param param.hint - 屏幕阅读器朗读文本
+     * @param param.interactive - 是否可交互，默认 false
+     * @param param.role - ARIA 角色属性
+     * @param param.event - 关联的事件组件（已弃用）
+     * @param param.delay - DOM 延迟加载时间（毫秒）
+     * @param param.props - ARIA value 属性（已弃用）
+     * @param param.state - ARIA state 属性（已弃用）
+     * @param param.attr - 自定义属性（已弃用）
+     *
+     * @example
+     * ```typescript
+     * // 简单文本朗读
+     * new A11y({ hint: '这是一个图片' })
+     *
+     * // 可交互按钮
+     * new A11y({
+     *   hint: '开始游戏',
+     *   role: 'button',
+     *   interactive: true
+     * })
+     *
+     * // 带 ARIA 属性
+     * new A11y({
+     *   hint: '进度条',
+     *   role: 'progressbar',
+     *   'aria-valuemin': '0',
+     *   'aria-valuemax': '100',
+     *   'aria-valuenow': '50'
+     * })
+     * ```
+     */
     constructor(param) {
         super();
         Object.assign(this, param);
@@ -83,6 +156,7 @@ class A11y extends eva_js.Component {
         this.a11yId = `_${uuid(6)}`;
     }
 }
+/** 组件名称 */
 A11y.componentName = 'A11y';
 __decorate([
     inspectorDecorator.type('boolean')
@@ -109,16 +183,25 @@ exports.A11yActivate = void 0;
     A11yActivate[A11yActivate["DISABLE"] = 1] = "DISABLE";
     A11yActivate[A11yActivate["CHECK"] = 2] = "CHECK";
 })(exports.A11yActivate || (exports.A11yActivate = {}));
+/**
+ * 无障碍 DOM 的指针事件
+ */
 var PointerEvents;
 (function (PointerEvents) {
     PointerEvents["NONE"] = "none";
     PointerEvents["AUTO"] = "auto";
 })(PointerEvents || (PointerEvents = {}));
+/**
+ * 无障碍 DOM 层的样式
+ */
 var MaskBackground;
 (function (MaskBackground) {
     MaskBackground["DEBUG"] = "rgba(255,0,0,0.5)";
     MaskBackground["NONE"] = "transparent";
 })(MaskBackground || (MaskBackground = {}));
+/**
+ * 无障碍 DOM 的类型
+ */
 var ElementType;
 (function (ElementType) {
     ElementType["BUTTON"] = "button";
@@ -137,11 +220,69 @@ const getEventFunc = function (event, gameObject, e) {
         });
     });
 };
+/**
+ * 无障碍系统（A11y System）
+ *
+ * A11ySystem 管理游戏中所有无障碍组件，在游戏画布上方创建无障碍覆盖层。
+ * 它会自动将游戏对象的位置、尺寸同步到对应的 DOM 元素上，
+ * 并处理与屏幕阅读器的交互。
+ *
+ * 主要功能：
+ * - 创建和管理无障碍 DOM 覆盖层
+ * - 同步游戏对象的变换到 DOM 元素
+ * - 处理无障碍元素的事件绑定
+ * - 支持调试模式（可视化无障碍区域）
+ * - 自动检测或手动配置无障碍功能开关
+ *
+ * @example
+ * ```typescript
+ * // 自动检测系统读屏功能
+ * game.addSystem(new A11ySystem());
+ *
+ * // 开启调试模式
+ * game.addSystem(new A11ySystem({ debug: true }));
+ *
+ * // 强制启用无障碍功能
+ * game.addSystem(new A11ySystem({
+ *   activate: A11yActivate.ENABLE,
+ *   zIndex: 10000
+ * }));
+ * ```
+ */
 let A11ySystem = class A11ySystem extends eva_js.System {
+    /**
+     * 构造无障碍系统
+     *
+     * @param opt - 系统配置选项
+     * @param opt.debug - 是否开启调试模式，默认 false
+     * @param opt.activate - 无障碍功能开关模式，默认 CHECK（自动检测）
+     * @param opt.delay - DOM 元素延迟创建时间（毫秒），默认 100
+     * @param opt.zIndex - 覆盖层的 z-index，默认 10000
+     * @param opt.checkA11yOpen - 自定义检测无障碍功能是否开启的函数
+     *
+     * @example
+     * ```typescript
+     * // 开启调试，无障碍区域会显示红色透明背景
+     * new A11ySystem({ debug: true })
+     *
+     * // 禁用无障碍功能
+     * new A11ySystem({ activate: A11yActivate.DISABLE })
+     *
+     * // 自定义检测逻辑
+     * new A11ySystem({
+     *   checkA11yOpen: async () => {
+     *     return await isScreenReaderActive();
+     *   }
+     * })
+     * ```
+     */
     constructor(opt) {
         super(opt);
+        /** 无障碍 DOM 元素缓存 */
         this.cache = new Map();
+        /** 事件处理函数缓存 */
         this.eventCache = new Map();
+        /** 无障碍覆盖层的 z-index 值 */
         this.zIndex = ZINDEX;
     }
     get ratioX() {
@@ -199,8 +340,10 @@ let A11ySystem = class A11ySystem extends eva_js.System {
             }
             if (!this.activate)
                 return;
+            // 渲染出父容器
             const div = document.createElement('div');
             this.div = div;
+            // 如果存在父容器，则渲染这个 div，子元素则会相对这个 div 进行定位，否则直接相对于 body 进行定位
             if (this.game.canvas.parentNode) {
                 this.game.canvas.parentNode.insertBefore(this.div, this.game.canvas);
             }
@@ -225,12 +368,14 @@ let A11ySystem = class A11ySystem extends eva_js.System {
         return { renderWidth, renderHeight };
     }
     getCanvasBoundingClientRect() {
+        // 渲染画布相对于视口的实际宽高以及位置，实际的像素
         const { width, height, left, top } = this.game.canvas.getBoundingClientRect();
         return { width, height, left, top };
     }
     initDiv() {
         const { pageXOffset, pageYOffset } = window;
         const { width, height, left, top } = this.getCanvasBoundingClientRect();
+        // 父容器位置
         const style = {
             width,
             height,
@@ -242,6 +387,7 @@ let A11ySystem = class A11ySystem extends eva_js.System {
             background: MaskBackground.NONE,
         };
         setStyle(this.div, style);
+        // 给父容器设置捕获事件，用于监听事件坐标
         this.div.addEventListener('click', e => {
             const currentTarget = e.currentTarget;
             const { left, top } = currentTarget.getBoundingClientRect();
@@ -250,6 +396,9 @@ let A11ySystem = class A11ySystem extends eva_js.System {
             this.eventPosition = { x, y };
         }, true);
     }
+    /**
+     * 监听插件更新
+     */
     update() {
         return __awaiter(this, void 0, void 0, function* () {
             const changes = this.componentObserver.clear();
@@ -290,6 +439,10 @@ let A11ySystem = class A11ySystem extends eva_js.System {
         element && this.div.removeChild(element);
         this.cache.delete(a11yId);
     }
+    /**
+     * 监听组件被添加至游戏对象
+     * @param changed 改变的组件
+     */
     add(changed) {
         if (!this.activate)
             return;
@@ -318,6 +471,7 @@ let A11ySystem = class A11ySystem extends eva_js.System {
             }
         }, delay || this.delay);
     }
+    // 监听 scene 改变
     transformChange(changed) {
         const component = changed.component;
         const { gameObject } = changed;
@@ -326,16 +480,26 @@ let A11ySystem = class A11ySystem extends eva_js.System {
             return;
         const { a11yId } = a11yComponent;
         if (!component.inScene) {
+            // 监听 scene 删除游戏对象
             const dom = this.div.querySelector(`#${a11yId}`);
             dom && this.div.removeChild(dom);
+            // this.cache.delete(a11yId)
         }
         else {
+            // 监听 scene add
+            // this.div.appendChild(this.cache)
             if (this.cache.has(a11yId)) {
                 const addDom = this.cache.get(a11yId);
                 addDom && this.div.appendChild(addDom);
             }
         }
     }
+    /**
+     * 为无障碍组件设置监听事件
+     * @param element DOM 元素
+     * @param event 事件组件对象
+     * @param gameObject 游戏对象
+     */
     setEvent(element, event, gameObject, id) {
         if (!event) {
             return;
@@ -367,12 +531,19 @@ let A11ySystem = class A11ySystem extends eva_js.System {
         const element = this.cache.get(a11yId);
         element && element.removeEventListener('click', func);
     }
+    /**
+     * 设置无障碍属性标签
+     * @param element DOM 元素
+     * @param hint 无障碍朗读文字
+     * @param interactive 是否可交互
+     */
     setA11yAttr(element, component) {
         const { hint, props = {}, state = {}, role, a11yId: id } = component;
         const realRole = role || 'text';
         element.setAttribute('role', realRole);
         element.setAttribute('aria-label', hint);
         element.id = id;
+        // 这里兼容
         const ariaProps = Object.keys(props);
         for (const key of ariaProps) {
             element.setAttribute(key, props[key]);
@@ -387,8 +558,19 @@ let A11ySystem = class A11ySystem extends eva_js.System {
             }
         }
     }
+    /**
+     * 将无障碍元素设置到对应的位置
+     * @param element DOM 元素
+     * @param transform 位置属性
+     */
     setPosition(element, transform) {
+        // 相对画布定位
+        // const { x: anchorX, y: anchorY } = transform.anchor
+        // 游戏对象的宽高
         const { width, height } = transform.size;
+        // position
+        // const { x: positionX, y: positionY } = transform.position
+        // 设置无障碍 DOM 的样式，龙骨动画默认 2px
         const style = {
             width: width === 0 ? 1 : width * this.ratioX,
             height: height === 0 ? 1 : height * this.ratioY,
@@ -398,6 +580,7 @@ let A11ySystem = class A11ySystem extends eva_js.System {
             background: this.debug ? MaskBackground.DEBUG : MaskBackground.NONE,
         };
         setStyle(element, style);
+        // 调整 DOM 的位置
         setTransform(element, transform, this.ratioX, this.ratioY);
     }
     onDestroy() {
@@ -407,6 +590,7 @@ let A11ySystem = class A11ySystem extends eva_js.System {
         this.div = null;
     }
 };
+/** 系统名称 */
 A11ySystem.systemName = 'A11ySystem';
 A11ySystem = __decorate([
     eva_js.decorators.componentObserver({

package/dist/plugin-a11y.d.ts

@@ -5,17 +5,106 @@ import type { GameObject } from '@eva/eva.js';
 import { System } from '@eva/eva.js';
 import { Transform } from '@eva/eva.js';
 
+/**
+ * 无障碍组件（A11y/Accessibility）
+ *
+ * A11y 组件为游戏对象提供无障碍支持，使屏幕阅读器能够识别和朗读游戏内容。
+ * 它在游戏画布上方创建透明的 DOM 元素，携带 ARIA 属性，让视障用户也能使用游戏。
+ *
+ * 主要功能：
+ * - 提供屏幕阅读器可识别的文本标签
+ * - 支持 ARIA 角色和属性
+ * - 自动同步游戏对象的位置和尺寸
+ * - 支持交互事件的无障碍访问
+ *
+ * @example
+ * ```typescript
+ * // 为游戏对象提供朗读能力
+ * const button = new GameObject('button');
+ * button.addComponent(new A11y({
+ *   hint: '开始游戏按钮',
+ *   role: 'button'
+ * }));
+ *
+ * // 带交互事件的无障碍元素
+ * button.addComponent(new A11y({
+ *   hint: '点击开始游戏',
+ *   event: eventComponent
+ * }));
+ * ```
+ */
 export declare class A11y extends Component<A11yParams> {
+    /** 组件名称 */
     static componentName: string;
+    /** 是否可交互 */
     interactive: boolean;
+    /** 屏幕阅读器朗读的文本内容 */
     hint: string;
+    /**
+     * 事件组件对象
+     * @deprecated 已弃用，将根据 Event 组件自动添加
+     */
     event: Component;
+    /** DOM 元素延迟加载时间（毫秒） */
     delay: number;
+    /** ARIA role 属性，定义元素的角色（如 button、link 等） */
     role: string;
+    /**
+     * ARIA value 属性集合
+     * @deprecated 已弃用，请将属性直接写在 component 上
+     * @example
+     * aria-valuemin = "0"
+     */
     props: object;
+    /**
+     * ARIA state 属性集合
+     * @deprecated 已弃用，请将属性直接写在 component 上
+     * @example
+     * aria-hidden = "true"
+     */
     state: object;
+    /**
+     * 自定义 DOM 属性
+     * @deprecated 已弃用，请将属性直接写在 component 上
+     */
     attr: object;
+    /** 辅助 DOM 元素的唯一 ID，自动生成 */
     a11yId: string;
+    /**
+     * 构造无障碍组件
+     *
+     * @param param - 无障碍组件配置参数
+     * @param param.hint - 屏幕阅读器朗读文本
+     * @param param.interactive - 是否可交互，默认 false
+     * @param param.role - ARIA 角色属性
+     * @param param.event - 关联的事件组件（已弃用）
+     * @param param.delay - DOM 延迟加载时间（毫秒）
+     * @param param.props - ARIA value 属性（已弃用）
+     * @param param.state - ARIA state 属性（已弃用）
+     * @param param.attr - 自定义属性（已弃用）
+     *
+     * @example
+     * ```typescript
+     * // 简单文本朗读
+     * new A11y({ hint: '这是一个图片' })
+     *
+     * // 可交互按钮
+     * new A11y({
+     *   hint: '开始游戏',
+     *   role: 'button',
+     *   interactive: true
+     * })
+     *
+     * // 带 ARIA 属性
+     * new A11y({
+     *   hint: '进度条',
+     *   role: 'progressbar',
+     *   'aria-valuemin': '0',
+     *   'aria-valuemax': '100',
+     *   'aria-valuenow': '50'
+     * })
+     * ```
+     */
     constructor(param: A11yParams);
 }
 
@@ -37,18 +126,84 @@ declare interface A11yParams {
     [propName: string]: string | object | number;
 }
 
+/**
+ * 无障碍系统（A11y System）
+ *
+ * A11ySystem 管理游戏中所有无障碍组件，在游戏画布上方创建无障碍覆盖层。
+ * 它会自动将游戏对象的位置、尺寸同步到对应的 DOM 元素上，
+ * 并处理与屏幕阅读器的交互。
+ *
+ * 主要功能：
+ * - 创建和管理无障碍 DOM 覆盖层
+ * - 同步游戏对象的变换到 DOM 元素
+ * - 处理无障碍元素的事件绑定
+ * - 支持调试模式（可视化无障碍区域）
+ * - 自动检测或手动配置无障碍功能开关
+ *
+ * @example
+ * ```typescript
+ * // 自动检测系统读屏功能
+ * game.addSystem(new A11ySystem());
+ *
+ * // 开启调试模式
+ * game.addSystem(new A11ySystem({ debug: true }));
+ *
+ * // 强制启用无障碍功能
+ * game.addSystem(new A11ySystem({
+ *   activate: A11yActivate.ENABLE,
+ *   zIndex: 10000
+ * }));
+ * ```
+ */
 export declare class A11ySystem extends System {
+    /** 系统名称 */
     static systemName: string;
+    /** 无障碍覆盖层容器 */
     div: HTMLDivElement;
+    /** 是否开启调试模式（显示无障碍区域背景色） */
     debug: boolean;
+    /** 画布横向缩放比例 */
     _ratioX: number;
+    /** 画布纵向缩放比例 */
     _ratioY: number;
+    /** 当前事件触发的坐标位置 */
     eventPosition: EventPosition;
+    /** 是否启用无障碍功能 */
     activate: boolean;
+    /** DOM 元素延迟放置时间（毫秒） */
     delay: number;
+    /** 无障碍 DOM 元素缓存 */
     cache: Map<string, HTMLElement>;
+    /** 事件处理函数缓存 */
     eventCache: Map<string, (e: MouseEvent) => void>;
+    /** 无障碍覆盖层的 z-index 值 */
     zIndex: number;
+    /**
+     * 构造无障碍系统
+     *
+     * @param opt - 系统配置选项
+     * @param opt.debug - 是否开启调试模式，默认 false
+     * @param opt.activate - 无障碍功能开关模式，默认 CHECK（自动检测）
+     * @param opt.delay - DOM 元素延迟创建时间（毫秒），默认 100
+     * @param opt.zIndex - 覆盖层的 z-index，默认 10000
+     * @param opt.checkA11yOpen - 自定义检测无障碍功能是否开启的函数
+     *
+     * @example
+     * ```typescript
+     * // 开启调试，无障碍区域会显示红色透明背景
+     * new A11ySystem({ debug: true })
+     *
+     * // 禁用无障碍功能
+     * new A11ySystem({ activate: A11yActivate.DISABLE })
+     *
+     * // 自定义检测逻辑
+     * new A11ySystem({
+     *   checkA11yOpen: async () => {
+     *     return await isScreenReaderActive();
+     *   }
+     * })
+     * ```
+     */
     constructor(opt?: SystemParam);
     get ratioX(): number;
     get ratioY(): number;
@@ -65,19 +220,46 @@ export declare class A11ySystem extends System {
         top: number;
     };
     initDiv(): void;
+    /**
+     * 监听插件更新
+     */
     update(): Promise<void>;
     change(changed: ComponentChanged): void;
     remove(changed: ComponentChanged): void;
+    /**
+     * 监听组件被添加至游戏对象
+     * @param changed 改变的组件
+     */
     add(changed: ComponentChanged): void;
     transformChange(changed: ComponentChanged): void;
+    /**
+     * 为无障碍组件设置监听事件
+     * @param element DOM 元素
+     * @param event 事件组件对象
+     * @param gameObject 游戏对象
+     */
     setEvent(element: HTMLElement, event: EE, gameObject: GameObject, id: any): void;
     addEvent(gameObject: GameObject): void;
     removeEvent(changed: ComponentChanged): void;
+    /**
+     * 设置无障碍属性标签
+     * @param element DOM 元素
+     * @param hint 无障碍朗读文字
+     * @param interactive 是否可交互
+     */
     setA11yAttr(element: HTMLElement, component: A11y): void;
+    /**
+     * 将无障碍元素设置到对应的位置
+     * @param element DOM 元素
+     * @param transform 位置属性
+     */
     setPosition(element: HTMLElement, transform: Transform): void;
     onDestroy(): void;
 }
 
+/**
+ * 点击事件位置
+ */
 declare interface EventPosition {
     x: number;
     y: number;

package/dist/plugin-a11y.esm.js

@@ -33,6 +33,11 @@ function __awaiter(thisArg, _arguments, P, generator) {
     });
 }
 
+/**
+ * 生成唯一的标识符
+ * @param len 长度
+ * @param radix 基
+ */
 function uuid(len) {
     let chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'.split('');
     let uuid = [];
@@ -41,6 +46,11 @@ function uuid(len) {
         uuid[i] = chars[0 | (Math.random() * radix)];
     return uuid.join('');
 }
+/**
+ * 设置 dom 样式
+ * @param div 需要设置样式的dom元素
+ * @param style 样式属性
+ */
 const setStyle = (element, style) => {
     const { width, height, position, left = 0, top = 0, zIndex, pointerEvents, background } = style;
     element.style.width = `${width}px`;
@@ -64,7 +74,70 @@ const setTransform = (element, transform, ratioX, ratioY) => {
     element.style.webkitTransformOrigin = 'left top';
 };
 
+/**
+ * 无障碍组件（A11y/Accessibility）
+ *
+ * A11y 组件为游戏对象提供无障碍支持，使屏幕阅读器能够识别和朗读游戏内容。
+ * 它在游戏画布上方创建透明的 DOM 元素，携带 ARIA 属性，让视障用户也能使用游戏。
+ *
+ * 主要功能：
+ * - 提供屏幕阅读器可识别的文本标签
+ * - 支持 ARIA 角色和属性
+ * - 自动同步游戏对象的位置和尺寸
+ * - 支持交互事件的无障碍访问
+ *
+ * @example
+ * ```typescript
+ * // 为游戏对象提供朗读能力
+ * const button = new GameObject('button');
+ * button.addComponent(new A11y({
+ *   hint: '开始游戏按钮',
+ *   role: 'button'
+ * }));
+ *
+ * // 带交互事件的无障碍元素
+ * button.addComponent(new A11y({
+ *   hint: '点击开始游戏',
+ *   event: eventComponent
+ * }));
+ * ```
+ */
 class A11y extends Component {
+    /**
+     * 构造无障碍组件
+     *
+     * @param param - 无障碍组件配置参数
+     * @param param.hint - 屏幕阅读器朗读文本
+     * @param param.interactive - 是否可交互，默认 false
+     * @param param.role - ARIA 角色属性
+     * @param param.event - 关联的事件组件（已弃用）
+     * @param param.delay - DOM 延迟加载时间（毫秒）
+     * @param param.props - ARIA value 属性（已弃用）
+     * @param param.state - ARIA state 属性（已弃用）
+     * @param param.attr - 自定义属性（已弃用）
+     *
+     * @example
+     * ```typescript
+     * // 简单文本朗读
+     * new A11y({ hint: '这是一个图片' })
+     *
+     * // 可交互按钮
+     * new A11y({
+     *   hint: '开始游戏',
+     *   role: 'button',
+     *   interactive: true
+     * })
+     *
+     * // 带 ARIA 属性
+     * new A11y({
+     *   hint: '进度条',
+     *   role: 'progressbar',
+     *   'aria-valuemin': '0',
+     *   'aria-valuemax': '100',
+     *   'aria-valuenow': '50'
+     * })
+     * ```
+     */
     constructor(param) {
         super();
         Object.assign(this, param);
@@ -79,6 +152,7 @@ class A11y extends Component {
         this.a11yId = `_${uuid(6)}`;
     }
 }
+/** 组件名称 */
 A11y.componentName = 'A11y';
 __decorate([
     type('boolean')
@@ -105,16 +179,25 @@ var A11yActivate;
     A11yActivate[A11yActivate["DISABLE"] = 1] = "DISABLE";
     A11yActivate[A11yActivate["CHECK"] = 2] = "CHECK";
 })(A11yActivate || (A11yActivate = {}));
+/**
+ * 无障碍 DOM 的指针事件
+ */
 var PointerEvents;
 (function (PointerEvents) {
     PointerEvents["NONE"] = "none";
     PointerEvents["AUTO"] = "auto";
 })(PointerEvents || (PointerEvents = {}));
+/**
+ * 无障碍 DOM 层的样式
+ */
 var MaskBackground;
 (function (MaskBackground) {
     MaskBackground["DEBUG"] = "rgba(255,0,0,0.5)";
     MaskBackground["NONE"] = "transparent";
 })(MaskBackground || (MaskBackground = {}));
+/**
+ * 无障碍 DOM 的类型
+ */
 var ElementType;
 (function (ElementType) {
     ElementType["BUTTON"] = "button";
@@ -133,11 +216,69 @@ const getEventFunc = function (event, gameObject, e) {
         });
     });
 };
+/**
+ * 无障碍系统（A11y System）
+ *
+ * A11ySystem 管理游戏中所有无障碍组件，在游戏画布上方创建无障碍覆盖层。
+ * 它会自动将游戏对象的位置、尺寸同步到对应的 DOM 元素上，
+ * 并处理与屏幕阅读器的交互。
+ *
+ * 主要功能：
+ * - 创建和管理无障碍 DOM 覆盖层
+ * - 同步游戏对象的变换到 DOM 元素
+ * - 处理无障碍元素的事件绑定
+ * - 支持调试模式（可视化无障碍区域）
+ * - 自动检测或手动配置无障碍功能开关
+ *
+ * @example
+ * ```typescript
+ * // 自动检测系统读屏功能
+ * game.addSystem(new A11ySystem());
+ *
+ * // 开启调试模式
+ * game.addSystem(new A11ySystem({ debug: true }));
+ *
+ * // 强制启用无障碍功能
+ * game.addSystem(new A11ySystem({
+ *   activate: A11yActivate.ENABLE,
+ *   zIndex: 10000
+ * }));
+ * ```
+ */
 let A11ySystem = class A11ySystem extends System {
+    /**
+     * 构造无障碍系统
+     *
+     * @param opt - 系统配置选项
+     * @param opt.debug - 是否开启调试模式，默认 false
+     * @param opt.activate - 无障碍功能开关模式，默认 CHECK（自动检测）
+     * @param opt.delay - DOM 元素延迟创建时间（毫秒），默认 100
+     * @param opt.zIndex - 覆盖层的 z-index，默认 10000
+     * @param opt.checkA11yOpen - 自定义检测无障碍功能是否开启的函数
+     *
+     * @example
+     * ```typescript
+     * // 开启调试，无障碍区域会显示红色透明背景
+     * new A11ySystem({ debug: true })
+     *
+     * // 禁用无障碍功能
+     * new A11ySystem({ activate: A11yActivate.DISABLE })
+     *
+     * // 自定义检测逻辑
+     * new A11ySystem({
+     *   checkA11yOpen: async () => {
+     *     return await isScreenReaderActive();
+     *   }
+     * })
+     * ```
+     */
     constructor(opt) {
         super(opt);
+        /** 无障碍 DOM 元素缓存 */
         this.cache = new Map();
+        /** 事件处理函数缓存 */
         this.eventCache = new Map();
+        /** 无障碍覆盖层的 z-index 值 */
         this.zIndex = ZINDEX;
     }
     get ratioX() {
@@ -195,8 +336,10 @@ let A11ySystem = class A11ySystem extends System {
             }
             if (!this.activate)
                 return;
+            // 渲染出父容器
             const div = document.createElement('div');
             this.div = div;
+            // 如果存在父容器，则渲染这个 div，子元素则会相对这个 div 进行定位，否则直接相对于 body 进行定位
             if (this.game.canvas.parentNode) {
                 this.game.canvas.parentNode.insertBefore(this.div, this.game.canvas);
             }
@@ -221,12 +364,14 @@ let A11ySystem = class A11ySystem extends System {
         return { renderWidth, renderHeight };
     }
     getCanvasBoundingClientRect() {
+        // 渲染画布相对于视口的实际宽高以及位置，实际的像素
         const { width, height, left, top } = this.game.canvas.getBoundingClientRect();
         return { width, height, left, top };
     }
     initDiv() {
         const { pageXOffset, pageYOffset } = window;
         const { width, height, left, top } = this.getCanvasBoundingClientRect();
+        // 父容器位置
         const style = {
             width,
             height,
@@ -238,6 +383,7 @@ let A11ySystem = class A11ySystem extends System {
             background: MaskBackground.NONE,
         };
         setStyle(this.div, style);
+        // 给父容器设置捕获事件，用于监听事件坐标
         this.div.addEventListener('click', e => {
             const currentTarget = e.currentTarget;
             const { left, top } = currentTarget.getBoundingClientRect();
@@ -246,6 +392,9 @@ let A11ySystem = class A11ySystem extends System {
             this.eventPosition = { x, y };
         }, true);
     }
+    /**
+     * 监听插件更新
+     */
     update() {
         return __awaiter(this, void 0, void 0, function* () {
             const changes = this.componentObserver.clear();
@@ -286,6 +435,10 @@ let A11ySystem = class A11ySystem extends System {
         element && this.div.removeChild(element);
         this.cache.delete(a11yId);
     }
+    /**
+     * 监听组件被添加至游戏对象
+     * @param changed 改变的组件
+     */
     add(changed) {
         if (!this.activate)
             return;
@@ -314,6 +467,7 @@ let A11ySystem = class A11ySystem extends System {
             }
         }, delay || this.delay);
     }
+    // 监听 scene 改变
     transformChange(changed) {
         const component = changed.component;
         const { gameObject } = changed;
@@ -322,16 +476,26 @@ let A11ySystem = class A11ySystem extends System {
             return;
         const { a11yId } = a11yComponent;
         if (!component.inScene) {
+            // 监听 scene 删除游戏对象
             const dom = this.div.querySelector(`#${a11yId}`);
             dom && this.div.removeChild(dom);
+            // this.cache.delete(a11yId)
         }
         else {
+            // 监听 scene add
+            // this.div.appendChild(this.cache)
             if (this.cache.has(a11yId)) {
                 const addDom = this.cache.get(a11yId);
                 addDom && this.div.appendChild(addDom);
             }
         }
     }
+    /**
+     * 为无障碍组件设置监听事件
+     * @param element DOM 元素
+     * @param event 事件组件对象
+     * @param gameObject 游戏对象
+     */
     setEvent(element, event, gameObject, id) {
         if (!event) {
             return;
@@ -363,12 +527,19 @@ let A11ySystem = class A11ySystem extends System {
         const element = this.cache.get(a11yId);
         element && element.removeEventListener('click', func);
     }
+    /**
+     * 设置无障碍属性标签
+     * @param element DOM 元素
+     * @param hint 无障碍朗读文字
+     * @param interactive 是否可交互
+     */
     setA11yAttr(element, component) {
         const { hint, props = {}, state = {}, role, a11yId: id } = component;
         const realRole = role || 'text';
         element.setAttribute('role', realRole);
         element.setAttribute('aria-label', hint);
         element.id = id;
+        // 这里兼容
         const ariaProps = Object.keys(props);
         for (const key of ariaProps) {
             element.setAttribute(key, props[key]);
@@ -383,8 +554,19 @@ let A11ySystem = class A11ySystem extends System {
             }
         }
     }
+    /**
+     * 将无障碍元素设置到对应的位置
+     * @param element DOM 元素
+     * @param transform 位置属性
+     */
     setPosition(element, transform) {
+        // 相对画布定位
+        // const { x: anchorX, y: anchorY } = transform.anchor
+        // 游戏对象的宽高
         const { width, height } = transform.size;
+        // position
+        // const { x: positionX, y: positionY } = transform.position
+        // 设置无障碍 DOM 的样式，龙骨动画默认 2px
         const style = {
             width: width === 0 ? 1 : width * this.ratioX,
             height: height === 0 ? 1 : height * this.ratioY,
@@ -394,6 +576,7 @@ let A11ySystem = class A11ySystem extends System {
             background: this.debug ? MaskBackground.DEBUG : MaskBackground.NONE,
         };
         setStyle(element, style);
+        // 调整 DOM 的位置
         setTransform(element, transform, this.ratioX, this.ratioY);
     }
     onDestroy() {
@@ -403,6 +586,7 @@ let A11ySystem = class A11ySystem extends System {
         this.div = null;
     }
 };
+/** 系统名称 */
 A11ySystem.systemName = 'A11ySystem';
 A11ySystem = __decorate([
     decorators.componentObserver({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-a11y",
-  "version": "2.0.1-beta.27",
+  "version": "2.0.1-beta.29",
   "description": "@eva/plugin-a11y",
   "main": "index.js",
   "module": "dist/plugin-a11y.esm.js",
@@ -18,9 +18,9 @@
   "license": "MIT",
   "homepage": "https://eva.js.org",
   "dependencies": {
-    "@eva/eva.js": "2.0.1-beta.27",
+    "@eva/eva.js": "2.0.1-beta.29",
     "@eva/inspector-decorator": "^0.0.5",
-    "@eva/plugin-renderer": "2.0.1-beta.27",
+    "@eva/plugin-renderer": "2.0.1-beta.29",
     "eventemitter3": "^3.1.2"
   }
 }