# @ariakit/utils 中文文档

规范地址：https://npmcn.com/package/%40ariakit/utils/

版本：0\.2\.2
npm 元数据更新时间：2026-10-14T08:57:45.369Z
中文译文更新时间：2026-11-06T18:47:05.977Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ariakit/utils
原文对照：https://npmcn.com/package/%40ariakit/utils/?lang=original
项目主页：https://ariakit.com/
源码仓库：https://github.com/ariakit/ariakit

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

- 包体积（解压后）：258 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-05-23T13:46:07.339Z
- 最新版本发布：2026-10-14T08:57:44.976Z
- 近 30 天下载量：3442170（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 10 个）

## 中文简介

阿里阿基特公用事业

## 安装

```sh
npm install @ariakit/utils
```

也可以使用：`pnpm add @ariakit/utils`、`yarn add @ariakit/utils`、`bun add @ariakit/utils`

## README

# @ ariakit/ utils (英语)

**重要内容:** 这个软件包是Ariakit的内部依赖性,不遵循语义化的版本,意思是断裂变化可能发生在补丁和小版本中.

Ariakit软件包使用的共享框架不可知公用事业.

## 目录

-   [安装](https://npmcn.com/package/%40ariakit/utils/#readme-installation)
-   [使用量](https://npmcn.com/package/%40ariakit/utils/#readme-usage)
-   [API 参考](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

## 安装

```sh
npm i @ariakit/utils
```

## 使用量

从包根导入助手 :

```ts
import { invariant } from "@ariakit/utils";
```

这一一揽子方案只采用无害环境管理,并暴露出单一的公众切入点.

## API 参考

-   [阵列公用事业](https://npmcn.com/package/%40ariakit/utils/#readme-array-utilities)
    -   [`toArray`](https://npmcn.com/package/%40ariakit/utils/#readme-toarray)
    -   [`addItemToArray`](https://npmcn.com/package/%40ariakit/utils/#readme-additemtoarray)
    -   [`flatten2DArray`](https://npmcn.com/package/%40ariakit/utils/#readme-flatten2darray)
    -   [`reverseArray`](https://npmcn.com/package/%40ariakit/utils/#readme-reversearray)
-   [DOM 公用事业](https://npmcn.com/package/%40ariakit/utils/#readme-dom-utilities)
    -   [`canUseDOM`](https://npmcn.com/package/%40ariakit/utils/#readme-canusedom)
    -   [`getDocument`](https://npmcn.com/package/%40ariakit/utils/#readme-getdocument)
    -   [`getWindow`](https://npmcn.com/package/%40ariakit/utils/#readme-getwindow)
    -   [`GetActiveElementOptions`](https://npmcn.com/package/%40ariakit/utils/#readme-getactiveelementoptions)
    -   [`getActiveElement`](https://npmcn.com/package/%40ariakit/utils/#readme-getactiveelement)
    -   [`contains`](https://npmcn.com/package/%40ariakit/utils/#readme-contains)
    -   [`isElement`](https://npmcn.com/package/%40ariakit/utils/#readme-iselement)
    -   [`isNode`](https://npmcn.com/package/%40ariakit/utils/#readme-isnode)
    -   [`isFrame`](https://npmcn.com/package/%40ariakit/utils/#readme-isframe)
    -   [`isButton`](https://npmcn.com/package/%40ariakit/utils/#readme-isbutton)
    -   [`isVisible`](https://npmcn.com/package/%40ariakit/utils/#readme-isvisible)
    -   [`isTextField`](https://npmcn.com/package/%40ariakit/utils/#readme-istextfield)
    -   [`isTextbox`](https://npmcn.com/package/%40ariakit/utils/#readme-istextbox)
    -   [`getTextboxValue`](https://npmcn.com/package/%40ariakit/utils/#readme-gettextboxvalue)
    -   [`getTextboxSelection`](https://npmcn.com/package/%40ariakit/utils/#readme-gettextboxselection)
    -   [`getPopupRole`](https://npmcn.com/package/%40ariakit/utils/#readme-getpopuprole)
    -   [`getItemRoleByPopupRole`](https://npmcn.com/package/%40ariakit/utils/#readme-getitemrolebypopuprole)
    -   [`getPopupItemRole`](https://npmcn.com/package/%40ariakit/utils/#readme-getpopupitemrole)
    -   [`scrollIntoViewIfNeeded`](https://npmcn.com/package/%40ariakit/utils/#readme-scrollintoviewifneeded)
    -   [`GetScrollingElementOptions`](https://npmcn.com/package/%40ariakit/utils/#readme-getscrollingelementoptions)
    -   [`getScrollingElement`](https://npmcn.com/package/%40ariakit/utils/#readme-getscrollingelement)
    -   [`isPartiallyHidden`](https://npmcn.com/package/%40ariakit/utils/#readme-ispartiallyhidden)
    -   [`setSelectionRange`](https://npmcn.com/package/%40ariakit/utils/#readme-setselectionrange)
    -   [`sortBasedOnDOMPosition`](https://npmcn.com/package/%40ariakit/utils/#readme-sortbasedondomposition)
-   [二. 活动公用事业](https://npmcn.com/package/%40ariakit/utils/#readme-event-utilities)
    -   [`isPortalEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-isportalevent)
    -   [`isSelfTarget`](https://npmcn.com/package/%40ariakit/utils/#readme-isselftarget)
    -   [`isOpeningInNewTab`](https://npmcn.com/package/%40ariakit/utils/#readme-isopeninginnewtab)
    -   [`isDownloading`](https://npmcn.com/package/%40ariakit/utils/#readme-isdownloading)
    -   [`fireEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-fireevent)
    -   [`fireBlurEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-fireblurevent)
    -   [`fireFocusEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-firefocusevent)
    -   [`fireKeyboardEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-firekeyboardevent)
    -   [`fireClickEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-fireclickevent)
    -   [`isFocusEventOutside`](https://npmcn.com/package/%40ariakit/utils/#readme-isfocuseventoutside)
    -   [`getInputType`](https://npmcn.com/package/%40ariakit/utils/#readme-getinputtype)
    -   [`isInputEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-isinputevent)
    -   [`queueBeforeEvent`](https://npmcn.com/package/%40ariakit/utils/#readme-queuebeforeevent)
    -   [`addGlobalEventListener`](https://npmcn.com/package/%40ariakit/utils/#readme-addglobaleventlistener)
-   [二. 重点公用事业](https://npmcn.com/package/%40ariakit/utils/#readme-focus-utilities)
    -   [`isFocusable`](https://npmcn.com/package/%40ariakit/utils/#readme-isfocusable)
    -   [`isTabbable`](https://npmcn.com/package/%40ariakit/utils/#readme-istabbable)
    -   [`getAllFocusableIn`](https://npmcn.com/package/%40ariakit/utils/#readme-getallfocusablein)
    -   [`getAllFocusable`](https://npmcn.com/package/%40ariakit/utils/#readme-getallfocusable)
    -   [`getFirstFocusableIn`](https://npmcn.com/package/%40ariakit/utils/#readme-getfirstfocusablein)
    -   [`getFirstFocusable`](https://npmcn.com/package/%40ariakit/utils/#readme-getfirstfocusable)
    -   [`getAllTabbableIn`](https://npmcn.com/package/%40ariakit/utils/#readme-getalltabbablein)
    -   [`getAllTabbable`](https://npmcn.com/package/%40ariakit/utils/#readme-getalltabbable)
    -   [`getFirstTabbableIn`](https://npmcn.com/package/%40ariakit/utils/#readme-getfirsttabbablein)
    -   [`getFirstTabbable`](https://npmcn.com/package/%40ariakit/utils/#readme-getfirsttabbable)
    -   [`getLastTabbableIn`](https://npmcn.com/package/%40ariakit/utils/#readme-getlasttabbablein)
    -   [`getLastTabbable`](https://npmcn.com/package/%40ariakit/utils/#readme-getlasttabbable)
    -   [`getNextTabbableIn`](https://npmcn.com/package/%40ariakit/utils/#readme-getnexttabbablein)
    -   [`getNextTabbable`](https://npmcn.com/package/%40ariakit/utils/#readme-getnexttabbable)
    -   [`getPreviousTabbableIn`](https://npmcn.com/package/%40ariakit/utils/#readme-getprevioustabbablein)
    -   [`getPreviousTabbable`](https://npmcn.com/package/%40ariakit/utils/#readme-getprevioustabbable)
    -   [`getClosestFocusable`](https://npmcn.com/package/%40ariakit/utils/#readme-getclosestfocusable)
    -   [`hasFocus`](https://npmcn.com/package/%40ariakit/utils/#readme-hasfocus)
    -   [`hasFocusWithin`](https://npmcn.com/package/%40ariakit/utils/#readme-hasfocuswithin)
    -   [`focusIfNeeded`](https://npmcn.com/package/%40ariakit/utils/#readme-focusifneeded)
    -   [`disableFocus`](https://npmcn.com/package/%40ariakit/utils/#readme-disablefocus)
    -   [`disableFocusIn`](https://npmcn.com/package/%40ariakit/utils/#readme-disablefocusin)
    -   [`restoreFocusIn`](https://npmcn.com/package/%40ariakit/utils/#readme-restorefocusin)
    -   [`focusIntoView`](https://npmcn.com/package/%40ariakit/utils/#readme-focusintoview)
-   [一般公用事业](https://npmcn.com/package/%40ariakit/utils/#readme-general-utilities)
    -   [`noop`](https://npmcn.com/package/%40ariakit/utils/#readme-noop)
    -   [`shallowEqual`](https://npmcn.com/package/%40ariakit/utils/#readme-shallowequal)
    -   [`applyState`](https://npmcn.com/package/%40ariakit/utils/#readme-applystate)
    -   [`isObject`](https://npmcn.com/package/%40ariakit/utils/#readme-isobject)
    -   [`isEmpty`](https://npmcn.com/package/%40ariakit/utils/#readme-isempty)
    -   [`isInteger`](https://npmcn.com/package/%40ariakit/utils/#readme-isinteger)
    -   [`hasOwnProperty`](https://npmcn.com/package/%40ariakit/utils/#readme-hasownproperty)
    -   [`chain`](https://npmcn.com/package/%40ariakit/utils/#readme-chain)
    -   [`cx`](https://npmcn.com/package/%40ariakit/utils/#readme-cx)
    -   [`normalizeString`](https://npmcn.com/package/%40ariakit/utils/#readme-normalizestring)
    -   [`omit`](https://npmcn.com/package/%40ariakit/utils/#readme-omit)
    -   [`pick`](https://npmcn.com/package/%40ariakit/utils/#readme-pick)
    -   [`identity`](https://npmcn.com/package/%40ariakit/utils/#readme-identity)
    -   [`beforePaint`](https://npmcn.com/package/%40ariakit/utils/#readme-beforepaint)
    -   [`afterPaint`](https://npmcn.com/package/%40ariakit/utils/#readme-afterpaint)
    -   [`warnOnce`](https://npmcn.com/package/%40ariakit/utils/#readme-warnonce)
    -   [`invariant`](https://npmcn.com/package/%40ariakit/utils/#readme-invariant)
    -   [`getKeys`](https://npmcn.com/package/%40ariakit/utils/#readme-getkeys)
    -   [`isFalsyBooleanCallback`](https://npmcn.com/package/%40ariakit/utils/#readme-isfalsybooleancallback)
    -   [`disabledFromProps`](https://npmcn.com/package/%40ariakit/utils/#readme-disabledfromprops)
    -   [`disabledFromElement`](https://npmcn.com/package/%40ariakit/utils/#readme-disabledfromelement)
    -   [`removeUndefinedValues`](https://npmcn.com/package/%40ariakit/utils/#readme-removeundefinedvalues)
    -   [`defaultValue`](https://npmcn.com/package/%40ariakit/utils/#readme-defaultvalue)
-   [平台公用事业](https://npmcn.com/package/%40ariakit/utils/#readme-platform-utilities)
    -   [`isTouchDevice`](https://npmcn.com/package/%40ariakit/utils/#readme-istouchdevice)
    -   [`isApple`](https://npmcn.com/package/%40ariakit/utils/#readme-isapple)
    -   [`isSafari`](https://npmcn.com/package/%40ariakit/utils/#readme-issafari)
    -   [`isFirefox`](https://npmcn.com/package/%40ariakit/utils/#readme-isfirefox)
    -   [`isMac`](https://npmcn.com/package/%40ariakit/utils/#readme-ismac)
-   [公用事业类型](https://npmcn.com/package/%40ariakit/utils/#readme-type-utilities)
    -   [`AnyObject`](https://npmcn.com/package/%40ariakit/utils/#readme-anyobject)
    -   [`EmptyObject`](https://npmcn.com/package/%40ariakit/utils/#readme-emptyobject)
    -   [`AnyFunction`](https://npmcn.com/package/%40ariakit/utils/#readme-anyfunction)
    -   [`BivariantCallback`](https://npmcn.com/package/%40ariakit/utils/#readme-bivariantcallback)
    -   [`SetStateAction`](https://npmcn.com/package/%40ariakit/utils/#readme-setstateaction)
    -   [`SetState`](https://npmcn.com/package/%40ariakit/utils/#readme-setstate)
    -   [`BooleanOrCallback`](https://npmcn.com/package/%40ariakit/utils/#readme-booleanorcallback)
    -   [`StringWithValue`](https://npmcn.com/package/%40ariakit/utils/#readme-stringwithvalue)
    -   [`ToPrimitive`](https://npmcn.com/package/%40ariakit/utils/#readme-toprimitive)
    -   [`PickByValue`](https://npmcn.com/package/%40ariakit/utils/#readme-pickbyvalue)
    -   [`PickRequired`](https://npmcn.com/package/%40ariakit/utils/#readme-pickrequired)
    -   [`AriaHasPopup`](https://npmcn.com/package/%40ariakit/utils/#readme-ariahaspopup)
    -   [`AriaRole`](https://npmcn.com/package/%40ariakit/utils/#readme-ariarole)
-   [撤消公用事业](https://npmcn.com/package/%40ariakit/utils/#readme-undo-utilities)
    -   [`UndoManager`](https://npmcn.com/package/%40ariakit/utils/#readme-undomanager)
    -   [`createUndoManager`](https://npmcn.com/package/%40ariakit/utils/#readme-createundomanager)

### 阵列公用事业

Ariakit 软件包使用的串行帮助器 .

#### `toArray`

```ts
function toArray<T>(arg: T): T extends readonly any[] ? T : T[];
```

变换 `arg` 如果还没有进入数组.

示例

```ts
toArray("a"); // ["a"]
toArray(["a"]); // ["a"]
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `addItemToArray`

```ts
function addItemToArray<T extends any[]>(
  array: T,
  item: T[number],
  index = -1,
): T;
```

当然,在一个阵列中添加一个项.

返回:通过数组索引中包含项目的新数组.

示例

```ts
addItemToArray(["a", "b", "d"], "c", 2); // ["a", "b", "c", "d"]
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `flatten2DArray`

```ts
function flatten2DArray<T>(array: T[][]): T[];
```

将2D阵列平整为一维阵列.

返回:一个一维阵列.

示例

```ts
flatten2DArray([["a"], ["b"], ["c"]]); // ["a", "b", "c"]
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `reverseArray`

```ts
function reverseArray<T>(array: T[]): T[];
```

自动反转数组 .

返回:倒数组.

示例

```ts
reverseArray(["a", "b", "c"]); // ["c", "b", "a"]
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

### DOM 公用事业

DOM帮助浏览器,iframe,文本输入,弹出和滚动行为.

#### `canUseDOM`

```ts
const canUseDOM: boolean;
```

这是 `true` 如果它在浏览器环境中运行或 `false` 如果不是的话.

示例

```ts
const title = canUseDOM ? document.title : "";
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getDocument`

```ts
function getDocument(node?: Window | Document | Node | null): Document;
```

返回文档 `node` 属于,或当它没有时属于当前.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getWindow`

```ts
function getWindow(
  node?: Window | Document | Node | null,
): Window & typeof globalThis;
```

返回窗口 `node` 属于,或当它没有时属于当前.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `GetActiveElementOptions`

```ts
interface GetActiveElementOptions {
  /**
   * Whether to resolve focus that lives inside a frame into that frame's own
   * document. Pass `false` to decide ownership in `node`'s document, where
   * focus inside a frame is represented by the frame element.
   * @default true
   */
  frame?: boolean;
  /**
   * Whether to resolve the element referenced by the focused element's
   * `aria-activedescendant` attribute.
   * @default false
   */
  activeDescendant?: boolean;
}
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getActiveElement`

```ts
function getActiveElement(
  node?: Node | null,
  { frame = true, activeDescendant = false }: GetActiveElementOptions = {},
): HTMLElement | null;
```

返回焦点元素 `node`'文件,溶入焦点框架自己的文件,除非 `frame` 实值 `false`。 。 。 .

示例

```ts
// Focus inside a frame, as the frame element rather than the inner element.
getActiveElement(document.getElementById("dialog"), { frame: false });
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `contains`

```ts
function contains(parent: Node, child: Node): boolean;
```

类似 `Element.prototype.contains`不过要快一点 `element` 与 `child`。 。 。 .

示例

```ts
contains(document.getElementById("parent"), document.getElementById("child"));
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isElement`

```ts
function isElement(target: EventTarget | null | undefined): target is Element;
```

检查指定事件目标是否为元素 .

`event.target` 财务报告和审定财务报表 `event.relatedTarget` 为: `EventTarget`s,这些不一定是元素——例如: `window` 或一个 `XMLHttpRequest` 当一个事件被按程序发送时。 通话 `Element`\- 仅限方法,例如 `hasAttribute` 在投出之前 注意这个 然后再把它们当作元素 当你只需要一个 `Node` ——例如打电话 `contains` ——使用 `isNode` 换句话说.

测试 `nodeType` 而不是说 `instanceof Element` 使来自同源儿童框架的元素 `addGlobalEventListener` 也听了),没有被错误地拒绝,因为属于不同的领域.

示例

```ts
if (isElement(event.target)) {
  event.target.hasAttribute("data-active");
}
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isNode`

```ts
function isNode(target: EventTarget | null | undefined): target is Node;
```

检查指定事件目标是否为节点 .

喜欢 `isElement`,但只要求目标是一个 `Node` 而不是一个因素——在召唤之前有用 `contains`,它接受任何节点。 它仍然拒绝非节点 `EventTarget`s(例如: `window` 或一个 `XMLHttpRequest`) 将产生 `contains` 掷出.

示例

```ts
if (isNode(event.target)) {
  contains(element, event.target);
}
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isFrame`

```ts
function isFrame(element: Element): element is HTMLIFrameElement;
```

检查是否 `element` 是一个框架元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isButton`

```ts
function isButton(element: { tagName: string; type?: string }): boolean;
```

检查是否 `element` 是本地 HTML 按钮元素.

示例

```ts
isButton(document.querySelector("button")); // true
isButton(document.querySelector("input[type='button']")); // true
isButton(document.querySelector("div")); // false
isButton(document.querySelector("input[type='text']")); // false
isButton(document.querySelector("div[role='button']")); // false
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isVisible`

```ts
function isVisible(element: Element): boolean;
```

检查元素是否可见 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isTextField`

```ts
function isTextField(
  element: Element,
): element is HTMLInputElement | HTMLTextAreaElement;
```

检查给定元素是否是一个文本字段,其中文本字段由输入内选择的能力所定义.

示例

```ts
isTextField(document.querySelector("div")); // false
isTextField(document.querySelector("input")); // true
isTextField(document.querySelector("input[type='button']")); // false
isTextField(document.querySelector("textarea")); // true
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isTextbox`

```ts
function isTextbox(element: HTMLElement): boolean;
```

检查给定元素是文本字段还是内容可编辑元素 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getTextboxValue`

```ts
function getTextboxValue(element: HTMLElement): string;
```

返回文本字段或内容可编辑元素作为字符串的值.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getTextboxSelection`

```ts
function getTextboxSelection(element: HTMLElement): {
  start: number;
  end: number;
};
```

返回元素中选择的起始和结尾相抵.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getPopupRole`

```ts
function getPopupRole(
  element?: Element | null,
  fallback?: AriaHasPopup,
): AriaHasPopup;
```

返回元素角色属性中的弹出角色, 如果它有的话 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getItemRoleByPopupRole`

```ts
function getItemRoleByPopupRole(popupRole?: string | null): string | undefined;
```

返回基于弹出角色的项目角色 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getPopupItemRole`

```ts
function getPopupItemRole(
  element?: Element | null,
  fallback?: AriaRole,
): string | undefined;
```

返回基于弹出式角色的项目角色属性 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `scrollIntoViewIfNeeded`

```ts
function scrollIntoViewIfNeeded(
  element: Element,
  arg?: boolean | ScrollIntoViewOptions,
): void;
```

电话 `element.scrollIntoView()` 如果该元素被隐藏或部分隐藏在取景口.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `GetScrollingElementOptions`

```ts
interface GetScrollingElementOptions {
  /**
   * The axis to check. By default, either axis can establish a scroll
   * container.
   */
  axis?: "x" | "y";
  /**
   * Returns this ancestor without testing its overflow or walking beyond it.
   */
  stopAt?: Element;
}
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getScrollingElement`

```ts
function getScrollingElement(
  element?: Element | null,
  options: GetScrollingElementOptions = {},
): HTMLElement | Element | null;
```

返回给定元素的滚动容器元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isPartiallyHidden`

```ts
function isPartiallyHidden(element: Element): boolean;
```

确定元素是隐藏还是部分隐藏在视图端口.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `setSelectionRange`

```ts
function setSelectionRange(
  element: HTMLInputElement | HTMLTextAreaElement,
  ...args: Parameters<typeof HTMLInputElement.prototype.setSelectionRange>
): void;
```

SelectRange只工作于几类输入. 通话 `setSelectionRange` 在不支持的输入类型上,可能会对某些浏览器出错。 为避免出现这种情况,我们先检查其类型是否支持选择区域. 在找到工作之前,它不会成为非支持类型.

见: [https://developer.mozila.org/en-US/docs/Web/API/HTML 通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通訊通相相相相相相相相相相通相通相相通相通相通相通相通相通相通相相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange)

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `sortBasedOnDOMPosition`

```ts
function sortBasedOnDOMPosition<T>(
  items: T[],
  getElement: (item: T) => Element | null | undefined,
): T[];
```

根据其 DOM 位置排序项目 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

### 二. 活动公用事业

用于发送和解释浏览器事件的事件助手.

#### `isPortalEvent`

```ts
function isPortalEvent(event: Pick<Event, "currentTarget" | "target">): boolean;
```

回返 `true` 若为 `event` 已经在一个反应门户元素内发射.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isSelfTarget`

```ts
function isSelfTarget(event: Pick<Event, "target" | "currentTarget">): boolean;
```

回返 `true` 若为 `event.target` 财务报告和审定财务报表 `event.currentTarget` 都一样.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isOpeningInNewTab`

```ts
function isOpeningInNewTab(
  event: Pick<MouseEvent, "currentTarget" | "metaKey" | "ctrlKey">,
): boolean;
```

检查用户事件是否在新标签中触发页面导航 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isDownloading`

```ts
function isDownloading(
  event: Pick<MouseEvent, "altKey" | "currentTarget">,
): boolean;
```

检查用户事件是否触发下载 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `fireEvent`

```ts
function fireEvent(
  element: Element,
  type: string,
  eventInit?: EventInit,
): boolean;
```

创建和发送一个事件.

示例

```ts
fireEvent(document.getElementById("id"), "blur", {
  bubbles: true,
  cancelable: true,
});
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `fireBlurEvent`

```ts
function fireBlurEvent(element: Element, eventInit?: FocusEventInit): boolean;
```

创建并发送模糊事件 .

示例

```ts
fireBlurEvent(document.getElementById("id"));
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `fireFocusEvent`

```ts
function fireFocusEvent(element: Element, eventInit?: FocusEventInit): boolean;
```

创建和发送焦点活动.

示例

```ts
fireFocusEvent(document.getElementById("id"));
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `fireKeyboardEvent`

```ts
function fireKeyboardEvent(
  element: Element,
  type: string,
  eventInit?: KeyboardEventInit,
): boolean;
```

创建并发送键盘事件.

示例

```ts
fireKeyboardEvent(document.getElementById("id"), "keydown", {
  key: "ArrowDown",
  shiftKey: true,
});
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `fireClickEvent`

```ts
function fireClickEvent(
  element: Element,
  eventInit?: PointerEventInit | null,
): boolean;
```

创建并发送点击事件.

这个事件是 `PointerEvent` 由拥有元素的窗口所建, 浏览器发送的方式, 返回到一个 `MouseEvent` 在窗口没有 `PointerEvent`。 。 `view` 那扇窗是真实的 `Window`,或 `null` 否则,它就由它组成。 它报告点击后没有指针,除非呼叫者通过一个指针,并报告其他每个指针属性的默认值,即点击总是这样.

示例

```ts
fireClickEvent(document.getElementById("id"));
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isFocusEventOutside`

```ts
function isFocusEventOutside(
  event: Pick<FocusEvent, "currentTarget" | "relatedTarget">,
  container?: Element | null,
): boolean;
```

检查焦点/ blur 事件是否从容器元素的外出/ 从外出 .

示例

```ts
const element = document.getElementById("id");
element.addEventListener("blur", (event) => {
  if (isFocusEventOutside(event)) {
    // ...
  }
});
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getInputType`

```ts
function getInputType(
  event: Event | { nativeEvent: Event },
): string | undefined;
```

返回 `inputType` (a) 活动财产,如果有的话.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isInputEvent`

```ts
function isInputEvent(event: Event): event is InputEvent;
```

检查事件是否为输入事件 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `queueBeforeEvent`

```ts
function queueBeforeEvent(
  element: Element,
  type: string,
  callback: () => void,
  timeout?: number,
): () => void;
```

在下一个动画框上运行回调,但在某个事件之前运行.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `addGlobalEventListener`

```ts
function addGlobalEventListener<K extends keyof DocumentEventMap>(
  type: K,
  listener: (event: DocumentEventMap[K]) => any,
  options?: boolean | AddEventListenerOptions,
  scope?: Window,
): () => void;
function addGlobalEventListener(
  type: string,
  listener: EventListenerOrEventListenerObject,
  options?: boolean | AddEventListenerOptions,
  scope?: Window,
): () => void;
```

添加一个全局活动收听器,包括儿童帧.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

### 二. 重点公用事业

可聚焦和可制表元素的焦点管理助手.

#### `isFocusable`

```ts
function isFocusable(element: Element): boolean;
```

检查是否 `element` 可聚焦与否.

示例

```ts
isFocusable(document.querySelector("input")); // true
isFocusable(document.querySelector("input[tabindex='-1']")); // true
isFocusable(document.querySelector("input[hidden]")); // false
isFocusable(document.querySelector("input:disabled")); // false
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isTabbable`

```ts
function isTabbable(
  element: Element | HTMLElement | HTMLInputElement,
): element is HTMLElement;
```

检查是否 `element` 是否可制表.

示例

```ts
isTabbable(document.querySelector("input")); // true
isTabbable(document.querySelector("input[tabindex='-1']")); // false
isTabbable(document.querySelector("input[hidden]")); // false
isTabbable(document.querySelector("input:disabled")); // false
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getAllFocusableIn`

```ts
function getAllFocusableIn(
  container: HTMLElement,
  includeContainer?: boolean,
): HTMLElement[];
```

返回所有可聚焦元素 `container`。 。 。 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getAllFocusable`

```ts
function getAllFocusable(includeBody?: boolean): HTMLElement[];
```

返回文档中的所有可聚焦元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getFirstFocusableIn`

```ts
function getFirstFocusableIn(
  container: HTMLElement,
  includeContainer?: boolean,
): HTMLElement | null;
```

返回第一个可聚焦元素 `container`。 。 。 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getFirstFocusable`

```ts
function getFirstFocusable(includeBody?: boolean): HTMLElement | null;
```

返回文档中的第一个可聚焦元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getAllTabbableIn`

```ts
function getAllTabbableIn(
  container: HTMLElement,
  includeContainer?: boolean,
  fallbackToFocusable?: boolean,
): HTMLElement[];
```

返回所有可制表元素 `container`包括集装箱本身.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getAllTabbable`

```ts
function getAllTabbable(fallbackToFocusable?: boolean): HTMLElement[];
```

返回文档中的所有可制表元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getFirstTabbableIn`

```ts
function getFirstTabbableIn(
  container: HTMLElement,
  includeContainer?: boolean,
  fallbackToFocusable?: boolean,
): HTMLElement | null;
```

返回第一个可制表元素 `container`包括容器本身,如果它是可标签的.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getFirstTabbable`

```ts
function getFirstTabbable(fallbackToFocusable?: boolean): HTMLElement | null;
```

返回文档中的第一个可制表元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getLastTabbableIn`

```ts
function getLastTabbableIn(
  container: HTMLElement,
  includeContainer?: boolean,
  fallbackToFocusable?: boolean,
): HTMLElement | null;
```

返回最后一个可制表元素 `container`包括容器本身,如果它是可标签的.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getLastTabbable`

```ts
function getLastTabbable(fallbackToFocusable?: boolean): HTMLElement | null;
```

返回文档中最后一个可制表元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getNextTabbableIn`

```ts
function getNextTabbableIn(
  container: HTMLElement,
  includeContainer?: boolean,
  fallbackToFirst?: boolean,
  fallbackToFocusable?: boolean,
): HTMLElement | null;
```

返回下一个可制表元素 `container`。 。 。 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getNextTabbable`

```ts
function getNextTabbable(
  fallbackToFirst?: boolean,
  fallbackToFocusable?: boolean,
): HTMLElement | null;
```

返回文档中的下一个可制表元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getPreviousTabbableIn`

```ts
function getPreviousTabbableIn(
  container: HTMLElement,
  includeContainer?: boolean,
  fallbackToLast?: boolean,
  fallbackToFocusable?: boolean,
): HTMLElement | null;
```

返回上一个可制表元素 `container`。 。 。 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getPreviousTabbable`

```ts
function getPreviousTabbable(
  fallbackToLast?: boolean,
  fallbackToFocusable?: boolean,
): HTMLElement | null;
```

返回文档中先前的可制表元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getClosestFocusable`

```ts
function getClosestFocusable(element?: HTMLElement | null): HTMLElement | null;
```

返回最接近的可聚焦元素 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `hasFocus`

```ts
function hasFocus(element: Element): boolean;
```

检查是否 `element` 有焦点。 参考的要点 `aria-activedescendant` 还将考虑.

示例

```ts
hasFocus(document.getElementById("id"));
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `hasFocusWithin`

```ts
function hasFocusWithin(element: Node | Element): boolean;
```

检查是否 `element` 专注在内部。 参考的要点 `aria-activedescendant` 还将考虑.

示例

```ts
hasFocusWithin(document.getElementById("id"));
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `focusIfNeeded`

```ts
function focusIfNeeded(element: HTMLElement): void;
```

只有当元素还没有被聚焦时,才关注元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `disableFocus`

```ts
function disableFocus(element: HTMLElement): void;
```

禁用焦点 `element`。 。 。 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `disableFocusIn`

```ts
function disableFocusIn(
  container: HTMLElement,
  includeContainer?: boolean,
): void;
```

使容器内的元素不具有可标签性.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `restoreFocusIn`

```ts
function restoreFocusIn(container: HTMLElement): void;
```

恢复容器内受禁用FocusIn影响的可标签元素.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `focusIntoView`

```ts
function focusIntoView(
  element: HTMLElement,
  options?: ScrollIntoViewOptions,
): void;
```

注重元素并滚动到视图中.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

### 一般公用事业

通用辅助器用于状态,对象,字符串,调度,以及断言.

#### `noop`

```ts
function noop(..._: any[]): any;
```

空函数 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `shallowEqual`

```ts
function shallowEqual(a?: AnyObject, b?: AnyObject): boolean;
```

比较两个对象.

示例

```ts
shallowEqual({ a: "a" }, {}); // false
shallowEqual({ a: "a" }, { b: "b" }); // false
shallowEqual({ a: "a" }, { a: "a" }); // true
shallowEqual({ a: "a" }, { a: "a", b: "b" }); // false
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `applyState`

```ts
function applyState<T>(
  argument: SetStateAction<T>,
  currentValue: T | (() => T),
): T;
```

接收 a `setState` 参数和调用 `currentValue` 如果这是一个函数。 否则, 将参数作为新值返回 .

示例

```ts
applyState((value) => value + 1, 1); // 2
applyState(2, 1); // 2
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isObject`

```ts
function isObject(arg: any): arg is Record<any, unknown>;
```

检查是否 `arg` 是否为对象.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isEmpty`

```ts
function isEmpty(arg: any): boolean;
```

检查是否 `arg` 是否为空.

示例

```ts
isEmpty([]); // true
isEmpty(["a"]); // false
isEmpty({}); // true
isEmpty({ a: "a" }); // false
isEmpty(); // true
isEmpty(null); // true
isEmpty(undefined); // true
isEmpty(""); // true
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isInteger`

```ts
function isInteger(arg: any): boolean;
```

检查是否 `arg` 是否为整数.

示例

```ts
isInteger(1); // true
isInteger(1.5); // false
isInteger("1"); // true
isInteger("1.5"); // false
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `hasOwnProperty`

```ts
function hasOwnProperty<T extends AnyObject>(
  object: T,
  prop: keyof any,
): prop is keyof T;
```

检查是否 `prop` 属于 `obj` 或无.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `chain`

```ts
function chain<T>(
  ...fns: T[]
): (...args: T extends AnyFunction ? Parameters<T> : never) => void;
```

接收函数作为参数并返回调用全部的新函数.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `cx`

```ts
function cx(
  ...args: Array<string | null | false | 0 | undefined>
): string | undefined;
```

返回带有以下真值的字符串: `args` 以空间分隔 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `normalizeString`

```ts
function normalizeString(str: string): string;
```

从字符串中去除二甲酸盐.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `omit`

```ts
function omit<T extends AnyObject, K extends keyof T>(
  object: T,
  keys: ReadonlyArray<K> | K[],
): Omit<T, K>;
```

关闭对象的特定密钥.

示例

```ts
omit({ a: "a", b: "b" }, ["a"]); // { b: "b" }
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `pick`

```ts
function pick<T extends AnyObject, K extends keyof T>(
  object: T,
  paths: ReadonlyArray<K> | K[],
): Pick<T, K>;
```

从对象中选择特定的密钥.

示例

```ts
pick({ a: "a", b: "b" }, ["a"]); // { a: "a" }
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `identity`

```ts
function identity<T>(value: T): T;
```

返回相同的参数.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `beforePaint`

```ts
function beforePaint(cb: () => void = noop): () => void;
```

在下一个油漆之前就跑.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `afterPaint`

```ts
function afterPaint(cb: () => void = noop): () => void;
```

下作相后行行相.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `warnOnce`

```ts
function warnOnce(message: string, key?: object): void;
```

每个消息和密钥只记录一次警告.

示例

```ts
if (process.env.NODE_ENV !== "production") {
  warnOnce("Warning");
}
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `invariant`

```ts
function invariant(
  condition: any,
  message?: string | boolean,
): asserts condition;
```

确认一个条件是真实的,否则会丢出一个错误.

示例

```ts
invariant(
  condition,
  process.env.NODE_ENV !== "production" && "Invariant failed",
);
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `getKeys`

```ts
function getKeys<T extends object>(obj: T): (keyof T)[];
```

类似 `Object.keys` 但返回一个类型安全的密钥数组.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isFalsyBooleanCallback`

```ts
function isFalsyBooleanCallback<T extends unknown[]>(
  booleanOrCallback?: boolean | ((...args: T) => boolean),
  ...args: T
): boolean;
```

检查布尔事件道具(例如隐藏 OnInteract Outside)是否被故意设定为虚假, 或带有布尔值, 或带有返回错误的回调 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `disabledFromProps`

```ts
function disabledFromProps(props: {
  disabled?: boolean;
  "aria-disabled"?: boolean | "true" | "false";
}): boolean;
```

检查某物是否基于道具被禁用.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `disabledFromElement`

```ts
function disabledFromElement(element: Element): boolean;
```

检查某物是否基于其 DOM 属性被禁用 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `removeUndefinedValues`

```ts
function removeUndefinedValues<T extends AnyObject>(obj: T): T;
```

从对象中删除未定义的值。 只有自己的地产被复制,所以继承的可支配地产永远不会成为结果的地产. A 类 `__proto__` 键被丢弃,因为它将取代结果的原型,而不是在结果中添加一个属性.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `defaultValue`

```ts
type DefaultValue<T extends readonly any[], Other = never> = T extends [
  infer Head,
  ...infer Rest,
]
  ? Rest extends []
    ? T[number] | Other
    : undefined extends Head
      ? DefaultValue<Rest, Exclude<Other | Head, undefined>>
      : Exclude<T[number], undefined>
  : never;

function defaultValue<T extends readonly any[]>(...values: T): DefaultValue<T>;
```

返回第一个不是的值 `undefined`。 。 。 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

### 平台公用事业

浏览器和平台检测帮助器.

#### `isTouchDevice`

```ts
function isTouchDevice(): boolean;
```

检测设备是否有触摸能力.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isApple`

```ts
function isApple(): boolean;
```

探测苹果设备.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isSafari`

```ts
function isSafari(): boolean;
```

探测到Safari浏览器.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isFirefox`

```ts
function isFirefox(): boolean;
```

检测 Firefox 浏览器 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `isMac`

```ts
function isMac(): boolean;
```

检测Mac电脑.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

### 公用事业类型

阿里阿基特套件使用的共享型公用事业.

#### `AnyObject`

```ts
type AnyObject = Record<string, any>;
```

任何物体.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `EmptyObject`

```ts
type EmptyObject = Record<keyof any, never>;
```

空对象.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `AnyFunction`

```ts
type AnyFunction = (...args: any) => any;
```

任何职能.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `BivariantCallback`

```ts
type BivariantCallback<T extends AnyFunction> = {
  bivarianceHack(...args: Parameters<T>): ReturnType<T>;
}["bivarianceHack"];
```

解决差异问题.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `SetStateAction`

```ts
type SetStateAction<T> = T | BivariantCallback<(prevState: T) => T>;
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `SetState`

```ts
type SetState<T> = BivariantCallback<(value: SetStateAction<T>) => void>;
```

类型 `setState` 函数在 `[state, setState] = useState()`。 。 。 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `BooleanOrCallback`

```ts
type BooleanOrCallback<T> = boolean | BivariantCallback<(arg: T) => boolean>;
```

布尔值或返回布尔值的回调值.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `StringWithValue`

```ts
type StringWithValue<T extends string> = T | (string & Record<never, never>);
```

为特定字符串提供自动补全的字符串 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `ToPrimitive`

```ts
type ToPrimitive<T> = T extends string
  ? string
  : T extends number
    ? number
    : T extends boolean
      ? boolean
      : T extends AnyFunction
        ? (...args: Parameters<T>) => ReturnType<T>
        : T;
```

将一个类型转换为原始类型.

示例

```ts
// string
ToPrimitive<"a">;
// number
ToPrimitive<1>;
```

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `PickByValue`

```ts
type PickByValue<T, Value> = {
  [
    K in keyof T as [Value] extends [T[K]]
      ? T[K] extends Value | undefined
        ? K
        : never
      : never
  ]: T[K];
};
```

只从具有特定值的类型中选择属性.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `PickRequired`

```ts
type PickRequired<T, P extends keyof T> = T &
  {
    [K in keyof T]: Pick<Required<T>, K>;
  }[P];
```

仅从类型中选择所需的属性.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `AriaHasPopup`

```ts
type AriaHasPopup =
  | boolean
  | "false"
  | "true"
  | "menu"
  | "listbox"
  | "tree"
  | "grid"
  | "dialog"
  | undefined;
```

表示一个元素可以触发的互动弹出元素的可用性和类型,如菜单或对话框等.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `AriaRole`

```ts
type AriaRole =
  | "alert"
  | "alertdialog"
  | "application"
  | "article"
  | "banner"
  | "button"
  | "cell"
  | "checkbox"
  | "columnheader"
  | "combobox"
  | "complementary"
  | "contentinfo"
  | "definition"
  // ... 53 more lines
  | "tree"
  | "treegrid"
  | "treeitem"
  | (string & {});
```

WAI-ARIA 1.1 所有角色属性值来自 [https://www.w3.org/TR/wai-aria-1.1/#作用 定义](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

### 撤消公用事业

撤消和重做管理工具 .

#### `UndoManager`

```ts
type Callback = void | (() => Callback | Promise<Callback>);

const UndoManager: { canUndo: () => boolean; canRedo: () => boolean; undo: () => Promise<void>; redo: () => Promise<void>; execute: (callback: Callback, group?: string) => Promise<void>; };
```

共享取消管理器实例 .

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

#### `createUndoManager`

```ts
type Callback = void | (() => Callback | Promise<Callback>);

interface CreateUndoManagerOptions {
  limit?: number;
}

function createUndoManager({ limit = 100 }: CreateUndoManagerOptions = {}): {
  canUndo: () => boolean;
  canRedo: () => boolean;
  undo: () => Promise<void>;
  redo: () => Promise<void>;
  execute: (callback: Callback, group?: string) => Promise<void>;
};
```

创建带有撤销和重做堆栈的撤销管理器.

[回到顶部](https://npmcn.com/package/%40ariakit/utils/#readme-api-reference)

## 常见问题

### @ariakit/utils 是什么？

阿里阿基特公用事业

### 如何安装 @ariakit/utils？

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

### @ariakit/utils 支持 TypeScript 吗？

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

### @ariakit/utils 支持 ESM 还是 CommonJS？

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

### @ariakit/utils 可以商用吗？

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

### @ariakit/utils 的下载量有多少？

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

### @ariakit/utils 还在维护吗？

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