# @aria-ui/utils 中文文档

规范地址：https://npmcn.com/package/%40aria-ui/utils/

版本：0\.1\.8
npm 元数据更新时间：2026-10-21T10:35:47.681Z
中文译文更新时间：2026-11-06T18:41:43.317Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aria-ui/utils
原文对照：https://npmcn.com/package/%40aria-ui/utils/?lang=original
源码仓库：https://github.com/ocavue/aria-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：156 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-03-29T10:16:12.900Z
- 最新版本发布：2026-10-21T10:35:47.321Z
- 近 30 天下载量：118700（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

Aria-ui 的功能

## 安装

```sh
npm install @aria-ui/utils
```

也可以使用：`pnpm add @aria-ui/utils`、`yarn add @aria-ui/utils`、`bun add @aria-ui/utils`

## README

# @aria-ui/用户

用于在顶部建立可访问的 Web 组件的可重复使用的钩子和辅助工具 [`@aria-ui/core`](https://www.npmjs.com/package/@aria-ui/core)。 。 。 .

这个软件包提供了组件 [`@aria-ui/elements`](https://www.npmjs.com/package/@aria-ui/elements) 使用内部——ARIA属性反射,采集导航,指针/键盘交互,存在和过渡跟踪等等. 您可以使用它来编写遵循相同模式的自定义元素 .

## 安装

```bash
npm install @aria-ui/core @aria-ui/utils
# or
pnpm add @aria-ui/core @aria-ui/utils
```

## API 概览

### ARIA 反射钩

每个钩子订阅一个取出器,并将结果写入主机元素上相应的ARIA属性. 它们是微小的效果, 但使用它们保持你的设置功能 声明和一致.

| 钩子 | 反映于 |
| --- | --- |
| `useAriaDisabled(host, get)` | `aria-disabled` |
| `useAriaExpanded(host, get)` | `aria-expanded` |
| `useAriaSelected(host, get)` | `aria-selected` |
| `useAriaControls(host, get)` | `aria-controls` |
| `useAriaDescribedBy(host, get)` | `aria-describedby` |
| `useAriaMultiselectable(host, get)` | `aria-multiselectable` |
| `useAriaOrientation(host, get)` | `aria-orientation` |
| `useAriaActivedescendant(host, get)` | `aria-activedescendant` |
| `useAriaHasPopup(host, get)` | `aria-haspopup` |

加低级助手 `getAriaHasPopup(element)` 财务报告和审定财务报表 `setAriaHasPopup(element, value)`。 。 。 .

```ts
import { useAriaDisabled, useAriaExpanded } from '@aria-ui/utils'

function setupTrigger(host, props) {
  useAriaDisabled(host, () => props.disabled.get())
  useAriaExpanded(host, () => props.open.get())
}
```

### 收款

收藏助手允许您构建复合部件——列表框,菜单,组合框——其中母元素协调了一组项目元素.

| 导出 | 说明 |
| --- | --- |
| `Collection` | 按键的一组命令项 `value`按DOM位置排序. |
| `getCollectionItemValue(element)` | 读取 `value` 收集项目. |
| `createCollectionStore()` | 创建仓库 `getCollection()`, (中文(简体) ), `getHighlightedValue()`, (中文(简体) ), `setHighlightedValue()`, (中文(简体) ), `first()`等 (中文(简体) ). 被设计成嵌入到您自己的仓库中. |
| `setupCollectionItem(host, props, getStore, getVisible?)` | 在其母收藏库中注册项目元素 。 登记、身份证分配和 `data-active` 属性. |
| `handleCollectionNavigation(event, collection, getHighlighted, setHighlighted, orientation, loop?)` | 进程a `keydown` arowUp/Down/Left/Right/Home/End 并更新突出显示值的事件。 回返 `true` 如果事件被处理. |

### 指针和键盘交互

| 钩子 | 说明 |
| --- | --- |
| `useEventListener(host, type, listener, options?)` | 添加一个 DOM 事件倾听器, 当主机断开时会自动删除 . |
| `useGlobalEventListener(host, type, listener)` | 添加一个 `window` 事件倾听器绑定在主机连接的生命周期上,在主机之间被复制. |
| `usePress(host, onPress)` | 为鼠标、触摸和键盘(Enter/Space)激活而起火的统一压力处理器. |
| `useHover(host, { openDelay, closeDelay, onOpen, onClose })` | 以可配置的开放/接近的延迟进行 Hover 跟踪 。 被流行乐和工具提示所使用. |
| `usePresence(host, present)` | 跟踪主机是否出现在 DOM 中, 带有用于卸载后激活行为的钩子. |
| `useTransitionStatus(host, present)` | 轨迹 CSS 过渡状态`'entering'`, (中文(简体) ), `'entered'`, (中文(简体) ), `'exiting'`, (中文(简体) ), `'exited'`)用于动画叠加. |
| `useDisabledMountTransitionStyle(host)` | 在初始挂载时禁用 CSS 转换, 以避免在第一个涂料上闪出 . |
| `createDelayedToggle({ openDelay, closeDelay })` | 独立延迟打开/关闭状态机器. |

### 身份和属性

| 钩子 | 说明 |
| --- | --- |
| `useElementId(host)` | 指定一个稳定,独特的 `id` 如果主机元素还没有一个的话。 返回代码 。 用于 `aria-activedescendant` 财务报告和审定财务报表 `aria-controls`。 。 。 . |
| `useAttribute(host, name, get)` | 反映任意 HTML 属性的值. |
| `useDataState(host, get)` | 反映状态字符串到 `data-state`。 。 。 . |

### 特性检测

| 导出 | 说明 |
| --- | --- |
| `FeatureDetection` | 公共特征检测助手. |
| `FeatureDetectionInternals` | 内部特征检测助手. |

### 再出口

为了方便,这个包裹也再出口 `getNearestOverflowAncestor` 从 `@zag-js/dom-query`。 。 。 .

## 示例:一个最小列表框项目

```ts
import {
  defineCustomElement,
  defineProps,
  onMount,
  type HostElement,
  type State,
} from '@aria-ui/core'
import { setupCollectionItem, useAriaSelected, useEventListener } from '@aria-ui/utils'

import { MyListboxContext } from './my-listbox-context'

interface ItemProps {
  value: string
}

const itemProps = defineProps<ItemProps>({
  value: { default: '', attribute: 'value', type: 'string' },
})

function setupItem(host: HostElement, props: State<ItemProps>) {
  onMount(host, () => {
    host.role = 'option'
  })

  const getStore = MyListboxContext.consume(host)

  setupCollectionItem(host, props, getStore)

  useAriaSelected(host, () => {
    return getStore()?.selectedValues.get().includes(props.value.get()) ?? false
  })

  useEventListener(host, 'click', () => {
    getStore()?.toggle(props.value.get())
  })
}

export class MyItemElement extends defineCustomElement(setupItem, itemProps) {}
```

## 许可证

麻省理工学院

## 常见问题

### @aria-ui/utils 是什么？

Aria-ui 的功能

### 如何安装 @aria-ui/utils？

在项目目录运行 npm install @aria-ui/utils，或使用 pnpm add / yarn add / bun add。

### @aria-ui/utils 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aria-ui/utils 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aria-ui/utils 可以商用吗？

@aria-ui/utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aria-ui/utils 的下载量有多少？

根据 npm 官方下载统计，@aria-ui/utils 在 2026/10/07 – 2026/11/05 这 30 天内被下载 118,700 次，日均约 3,957 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aria-ui/utils 还在维护吗？

最新版本 0\.1\.8 发布于 2026/10/21（17 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/03/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。