# @ariakit/react-utils 中文文档

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

版本：0\.2\.8
npm 元数据更新时间：2026-10-14T08:58:27.922Z
中文译文更新时间：2026-11-06T18:46:09.024Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：101 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-05-23T13:51:15.140Z
- 最新版本发布：2026-10-14T08:58:27.540Z
- 近 30 天下载量：3442747（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 13 个）

## 中文简介

Ariakit 反应公用事业

## 安装

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

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

## README

# @ ariakit/反应- utils

**重要内容:** 这个软件包是Ariakit的内部依赖性,不遵循语义化的版本,意思是断裂变化可能发生在补丁和小版本中. 你也许想用 [`@ariakit/react`](https://npmjs.org/package/@ariakit/react) 换句话说.

Ariakit React包使用的共享反应工具.

## 目录

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

## 安装

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

## 使用量

从包根导入助手 :

```ts
import { useEvent } from "@ariakit/react-utils";
```

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

## API 参考

-   [钩子](https://npmcn.com/package/%40ariakit/react-utils/#readme-hooks)
    -   [`useSafeLayoutEffect`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usesafelayouteffect)
    -   [`useInitialValue`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useinitialvalue)
    -   [`useLiveRef`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useliveref)
    -   [`useEvent`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useevent)
    -   [`useTransactionState`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usetransactionstate)
    -   [`useMergeRefs`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usemergerefs)
    -   [`useId`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useid)
    -   [`useDeferredValue`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usedeferredvalue)
    -   [`useTagName`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usetagname)
    -   [`useAttribute`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useattribute)
    -   [`useUpdateEffect`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useupdateeffect)
    -   [`useUpdateLayoutEffect`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useupdatelayouteffect)
    -   [`useForceUpdate`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useforceupdate)
    -   [`useBooleanEvent`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usebooleanevent)
    -   [`useWrapElement`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usewrapelement)
    -   [`usePortalRef`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useportalref)
    -   [`useMetadataProps`](https://npmcn.com/package/%40ariakit/react-utils/#readme-usemetadataprops)
    -   [`useIsMouseMoving`](https://npmcn.com/package/%40ariakit/react-utils/#readme-useismousemoving)
-   [一般公用事业](https://npmcn.com/package/%40ariakit/react-utils/#readme-general-utilities)
    -   [`setRef`](https://npmcn.com/package/%40ariakit/react-utils/#readme-setref)
    -   [`isValidElementWithRef`](https://npmcn.com/package/%40ariakit/react-utils/#readme-isvalidelementwithref)
    -   [`getRefProperty`](https://npmcn.com/package/%40ariakit/react-utils/#readme-getrefproperty)
    -   [`mergeProps`](https://npmcn.com/package/%40ariakit/react-utils/#readme-mergeprops)
-   [系统公用事业](https://npmcn.com/package/%40ariakit/react-utils/#readme-system-utilities)
    -   [`forwardRef`](https://npmcn.com/package/%40ariakit/react-utils/#readme-forwardref)
    -   [`memo`](https://npmcn.com/package/%40ariakit/react-utils/#readme-memo)
    -   [`createElement`](https://npmcn.com/package/%40ariakit/react-utils/#readme-createelement)
    -   [`createHook`](https://npmcn.com/package/%40ariakit/react-utils/#readme-createhook)
    -   [`createStoreContext`](https://npmcn.com/package/%40ariakit/react-utils/#readme-createstorecontext)
-   [公用事业类型](https://npmcn.com/package/%40ariakit/react-utils/#readme-type-utilities)
    -   [`RenderProp`](https://npmcn.com/package/%40ariakit/react-utils/#readme-renderprop)
    -   [`WrapElement`](https://npmcn.com/package/%40ariakit/react-utils/#readme-wrapelement)
    -   [`Options`](https://npmcn.com/package/%40ariakit/react-utils/#readme-options)
    -   [`HTMLProps`](https://npmcn.com/package/%40ariakit/react-utils/#readme-htmlprops)
    -   [`Props`](https://npmcn.com/package/%40ariakit/react-utils/#readme-props)
    -   [`Hook`](https://npmcn.com/package/%40ariakit/react-utils/#readme-hook)

### 钩子

反应钩用于 refs,事件,ids,效果,和元素元数据.

#### `useSafeLayoutEffect`

```ts
const useSafeLayoutEffect: typeof React.useLayoutEffect;
```

`React.useLayoutEffect` 倒计时 `React.useEffect` 在服务器侧.

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

#### `useInitialValue`

```ts
function useInitialValue<T>(value: T | (() => T)): T;
```

返回一个即使参数更新也不会改变的值.

示例

```ts
function Component({ prop }) {
  const initialProp = useInitialValue(prop);
}
```

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

#### `useLiveRef`

```ts
function useLiveRef<T>(value: T): RefObject<T>;
```

创建一个 `React.RefObject` 以新值不断更新.

示例

```ts
function Component({ prop }) {
  const propRef = useLiveRef(prop);
}
```

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

#### `useEvent`

```ts
function useEvent<T extends AnyFunction>(callback?: T): T;
```

创建一个稳定的回调函数,可以访问最新的状态,可以在事件处理器和效果回调中使用. 在渲染相中使用时会抛出.

示例

```ts
function Component(props) {
  const onClick = useEvent(props.onClick);
  React.useEffect(() => {}, [onClick]);
}
```

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

#### `useTransactionState`

```ts
function useTransactionState<T>(
  callback?: ((state: SetStateAction<T | null>) => void) | null,
): readonly [T | null, React.Dispatch<SetStateAction<T | null>>];
```

创建反应状态,当状态在清理时更改并滚回上一个状态时,该状态会调用回调函数.

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

#### `useMergeRefs`

```ts
function useMergeRefs(
  ...refs: Array<Ref<any> | undefined>
): ((value: unknown) => (() => void) | undefined) | undefined;
```

将 React Refs 合并为单一的记忆函数 ref 这样您就可以把它传递给一个元素.

示例

```ts
const Component = React.forwardRef((props, ref) => {
  const internalRef = React.useRef();
  return <div {...props} ref={useMergeRefs(internalRef, ref)} />;
});
```

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

#### `useId`

```ts
function useId(defaultId?: string): string | undefined;
```

生成一个独特的ID. 使用React的用法,如果可用的话.

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

#### `useDeferredValue`

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

使用React's used DeferredValue(如果有的话).

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

#### `useTagName`

```ts
function useTagName(
  refOrElement?: RefObject<HTMLElement | null> | HTMLElement | null,
  type?: string | ComponentType,
): string | undefined;
```

通过解析元素 ref来返回标记名称 .

示例

```ts
function Component(props) {
  const ref = React.useRef();
  const tagName = useTagName(ref, "button"); // div
  return <div ref={ref} {...props} />;
}
```

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

#### `useAttribute`

```ts
function useAttribute(
  refOrElement: RefObject<HTMLElement | null> | HTMLElement | null,
  attributeName: string,
  defaultValue?: string,
): string | undefined;
```

返回元素的属性值.

示例

```ts
function Component(props) {
  const ref = React.useRef();
  const role = useAttribute(ref, "role", props.role);
  return <div ref={ref} {...props} />;
}
```

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

#### `useUpdateEffect`

```ts
function useUpdateEffect(effect: EffectCallback, deps?: DependencyList): void;
```

A 类 `React.useEffect` 它不会运行 在第一个渲染.

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

#### `useUpdateLayoutEffect`

```ts
function useUpdateLayoutEffect(
  effect: EffectCallback,
  deps?: DependencyList,
): void;
```

A 类 `React.useLayoutEffect` 它不会运行 在第一个渲染.

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

#### `useForceUpdate`

```ts
function useForceUpdate(): [never[], React.ActionDispatch<[]>];
```

类似 `useState` 财务报告和审定财务报表 `useReducer`,但唯一目的是重置组件.

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

#### `useBooleanEvent`

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

返回类似事件召回 `useEvent`,但它也接受布尔值,该值将变成函数.

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

#### `useWrapElement`

```ts
function useWrapElement<P>(
  props: P & { wrapElement?: WrapElement },
  callback: WrapElement,
  deps: DependencyList = [],
): P & { wrapElement: WrapElement };
```

带额外道具返回 `wrapElement` 道具 (英语).

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

#### `usePortalRef`

```ts
function usePortalRef(
  portalProp = false,
  portalRefProp?:
    | RefCallback<HTMLElement>
    | MutableRefObject<HTMLElement | null>,
): {
  portalRef: ((value: unknown) => (() => void) | undefined) | undefined;
  portalNode: HTMLElement | null;
  domReady: true | HTMLElement | null;
};
```

合并门户参考道具并返回 a `domReady` 用于下面使用Portal的组件.

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

#### `useMetadataProps`

```ts
function useMetadataProps<T, K extends keyof any>(
  props: { onLoadedMetadataCapture?: AnyFunction & { [key in K]?: T } },
  key: K,
  value: T,
): readonly [
  (AnyFunction & { [key in K]?: T | undefined })[K] | undefined,
  { readonly onLoadedMetadataCapture: any },
];
```

一个传递元数据道具的钩子,而不把它们泄露给DOM.

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

#### `useIsMouseMoving`

```ts
function useIsMouseMoving(): () => boolean;
```

返回检查鼠标是否移动的函数 .

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

### 一般公用事业

提供参考、元素和道具的帮助.

#### `setRef`

```ts
function setRef<T>(
  ref: RefCallback<T> | MutableRefObject<T> | null | undefined,
  value: T,
): void | (() => void);
```

设置函数和对象React ref.

提供回调参考清理功能时返回.

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

#### `isValidElementWithRef`

```ts
function isValidElementWithRef<P extends { ref?: Ref<any> }>(
  element: unknown,
): element is ReactElement<P> & { ref?: Ref<any> };
```

检查元素是否为具有可读性的有效反应元素 .

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

#### `getRefProperty`

```ts
function getRefProperty(element: unknown): Ref<any> | undefined;
```

从 React 元素获取 ref 属性 .

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

#### `mergeProps`

```ts
function mergeProps<T extends HTMLAttributes<any>>(base: T, overrides: T): T;
```

将两套道具合并.

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

### 系统公用事业

用于创建和组合 Ariakit React 组件的助手.

#### `forwardRef`

```ts
function forwardRef<T extends React.FC<any>>(render: T): T;
```

一样 `React.forwardRef` 但通过 `ref` 作为道具并返回具有同一种通用类型的组件.

手势控取 `undefined` 被丢弃,所以传出者的行为与省略相同,组件保留它自己计算的值.

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

#### `memo`

```ts
function memo<T extends React.FC<any>>(
  Component: T,
  propsAreEqual?: (
    prevProps: Readonly<React.ComponentPropsWithoutRef<T>>,
    nextProps: Readonly<React.ComponentPropsWithoutRef<T>>,
  ) => boolean,
): T;
```

一样 `React.memo` 但返回具有相同通用类型的组件.

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

#### `createElement`

```ts
function createElement(
  Type: React.ElementType,
  props: Props<React.ElementType, Options>,
): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
```

创建支持 `render` 财务报告和审定财务报表 `wrapElement` 道具来.

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

#### `createHook`

```ts
function createHook<
  T extends React.ElementType,
  P extends AnyObject = EmptyObject,
>(useProps: (props: Props<T, P>) => HTMLProps<T, P>): Hook<T, P>;
```

创建一个接受道具并返回道具的组件钩子,这样它们就可以被传递到反应元素.

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

#### `createStoreContext`

```ts
type StoreProvider<T extends Store> = React.ComponentType<{
  value: T | undefined;
  children?: React.ReactNode;
}>;

function createStoreContext<T extends Store>(
  providers: StoreProvider<T>[] = [],
  scopedProviders: StoreProvider<T>[] = [],
): {
  context: React.Context<T | undefined>;
  scopedContext: React.Context<T | undefined>;
  useContext: () => T | undefined;
  useScopedContext: (onlyScoped?: boolean) => T | undefined;
  useProviderContext: () => T | undefined;
  ContextProvider: (
    props: React.ComponentPropsWithoutRef<React.Provider<T | undefined>>,
  ) => React.JSX.Element;
  ScopedContextProvider: (
    props: React.ComponentPropsWithoutRef<React.Provider<T | undefined>>,
  ) => React.JSX.Element;
};
```

创建有钩和提供者组件的 Ariakit 商店上下文 .

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

### 公用事业类型

Ariakit React 组件的共享类型 .

#### `RenderProp`

```ts
type RenderProp<P = React.HTMLAttributes<any> & { ref?: React.Ref<any> }> = (
  props: P,
) => React.ReactNode;
```

彩色道具类型.

示例

```ts
const children: RenderProp = (props) => <div {...props} />;
```

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

#### `WrapElement`

```ts
type WrapElement = (element: React.ReactElement) => React.ReactElement;
```

这个 `wrapElement` 道具 (英语).

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

#### `Options`

```ts
interface Options {
  wrapElement?: WrapElement;
  /**
   * Allows the component to be rendered as a different HTML element or React
   * component. The value can be a React element or a function that takes in the
   * original component props and gives back a React element with the props
   * merged.
   *
   * Some Ariakit components detect the type of the underlying element when they
   * mount. If the render element's type may change while the component is
   * mounted, pass a
   * [`key`](https://react.dev/learn/preserving-and-resetting-state) prop that
   * changes with the element type so React remounts the component with the new
   * element. Remounting resets uncontrolled state, so keep the relevant state
   // ... 11 more lines
   * for more details.
   */
  render?: RenderProp | React.ReactElement;
}
```

自定义道具,包括 `render` 道具 (英语).

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

#### `HTMLProps`

```ts
type HTMLProps<
  T extends React.ElementType,
  P extends AnyObject = EmptyObject,
> = Omit<React.ComponentPropsWithRef<T>, keyof P> & {
  [index: `data-${string}`]: unknown;
};
```

基于元素类型的HTML道具,不包括自定义道具.

示例

```ts
type ButtonHTMLProps = HTMLProps<"button", { custom?: boolean }>;
```

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

#### `Props`

```ts
type Props<T extends React.ElementType, P extends AnyObject = EmptyObject> = P &
  HTMLProps<T, P>;
```

基于元素类型的道具,包括自定义道具.

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

#### `Hook`

```ts
type Hook<T extends React.ElementType, P extends AnyObject = EmptyObject> = <
  ElementType extends React.ElementType = T,
>(
  props?: Props<ElementType, P>,
) => HTMLProps<ElementType, P>;
```

支持 `render` 道具并返回基于元素类型的HTML道具.

示例

```ts
type UseButton = Hook<"button", { custom?: boolean }>;
```

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

## 常见问题

### @ariakit/react-utils 是什么？

Ariakit 反应公用事业

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

在项目目录运行 npm install @ariakit/react-utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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