# @ariakit/react-store 中文文档

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

版本：0\.1\.13
npm 元数据更新时间：2026-10-14T08:58:34.647Z
中文译文更新时间：2026-11-06T18:47:24.473Z
软件包许可：MIT

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

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

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

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

## 中文简介

Ariakit 反应商店公用事业

## 安装

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

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

## README

# @ ariakit/ react- store (英语)

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

Ariakit商店原始物的回放装订.

## 目录

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

## 安装

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

## 使用量

从包根导入商店钩子 :

```ts
import { useStoreState } from "@ariakit/react-store";
```

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

## API 参考

-   [`UseState`](https://npmcn.com/package/%40ariakit/react-store/#readme-usestate)
-   [`useStoreState`](https://npmcn.com/package/%40ariakit/react-store/#readme-usestorestate)
-   [`useStoreStateObject`](https://npmcn.com/package/%40ariakit/react-store/#readme-usestorestateobject)
-   [`useStoreProps`](https://npmcn.com/package/%40ariakit/react-store/#readme-usestoreprops)
-   [`useStore`](https://npmcn.com/package/%40ariakit/react-store/#readme-usestore)
-   [`Store`](https://npmcn.com/package/%40ariakit/react-store/#readme-store)

### `UseState`

```ts
interface UseState<S> {
  /**
   * Re-renders the component when state changes and returns the current state.
   * @deprecated Use
   *   [`useStoreState`](https://ariakit.com/reference/use-store-state) instead.
   * @example
   * const state = store.useState();
   */
  (): S;
  /**
   * Re-renders the component when the state changes and returns the current
   * state given the passed key. Changes on other keys will not trigger a
   * re-render.
   * @param key The state key.
   // ... 15 more lines
   * const foo = store.useState((state) => state.foo);
   */
  <V>(selector: (state: S) => V): V;
}
```

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

### `useStoreState`

```ts
type StateStore<T = CoreStore<any>> = T | null | undefined;

type StateKey<T = CoreStore<any>> = keyof StoreState<T>;

type SelectorStateKey<T> = T extends CoreStore ? StateKey<T> : never;

type SelectorState<T, K extends PropertyKey> = T extends CoreStore
  ? Pick<StoreState<T>, Extract<K, StateKey<T>>>
  : never;

function useStoreState<T extends CoreStore>(store: T): StoreState<T>;
function useStoreState<T extends CoreStore>(
  store: StateStore<T>,
): StoreState<T> | undefined;
function useStoreState<T extends CoreStore, K extends StateKey<T>>(
  store: T,
  key: K,
): StoreState<T>[K];
function useStoreState<T extends CoreStore, K extends StateKey<T>>(
  store: StateStore<T>,
  key: K,
): StoreState<T>[K] | undefined;
function useStoreState<T extends CoreStore, V>(
  store: T,
  selector: (state: StoreState<T>) => V,
): V;
function useStoreState<T extends CoreStore, V>(
  store: StateStore<T>,
  selector: (state?: StoreState<T>) => V,
): V;
function useStoreState<T extends CoreStore, K extends SelectorStateKey<T>, V>(
  store: T,
  keys: readonly K[],
  selector: (state: SelectorState<T, K>) => V,
): V;
function useStoreState<T extends CoreStore, K extends SelectorStateKey<T>, V>(
  store: StateStore<T>,
  keys: readonly K[],
  selector: (state?: SelectorState<T, K>) => V,
): V;
```

接收 Ariakit 存储对象(可以是) `null` 或者说 `undefined`)并返回当前状态。 如果提供密钥作为第二个参数,则返回该密钥的值。 如果提供了选取函数,则会将状态传给它,并使用它的回取值. 选择者呼叫可以通过他们读取的状态密钥,作为跳过不相关的存储更新的第二个参数. 此列表必须包含选择者读取的每个存储密钥, 或返回的快照可能保持不变 。 空列表意味着存储更新永远不会通知选择者 .

使用此钩的组件会在返回的值变化时重新返回 .

示例

访问整个组合框状态 :

```js
const combobox = Ariakit.useComboboxStore();
const state = Ariakit.useStoreState(combobox);
```

示例

从组合框状态访问特定值 :

```js
const combobox = Ariakit.useComboboxStore();
const value = Ariakit.useStoreState(combobox, "value");
```

示例

使用选择器函数访问值 :

```js
const combobox = Ariakit.useComboboxStore();
const value = Ariakit.useStoreState(combobox, (state) => state.value);
```

示例

只订阅选择器读取的状态密钥 :

```js
const tab = Ariakit.useTabStore();
const selected = Ariakit.useStoreState(
  tab,
  ["selectedId"],
  (state) => state.selectedId === "details",
);
```

示例

访问商店的状态 : `null` 或者说 `undefined` (计: 例如,使用上下文:

```js
const combobox = Ariakit.useComboboxContext();
const value = Ariakit.useStoreState(combobox, "value");
```

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

### `useStoreStateObject`

```ts
type StateStore<T = CoreStore<any>> = T | null | undefined;

type StateKey<T = CoreStore<any>> = keyof StoreState<T>;

type SelectorStateKey<T> = T extends CoreStore ? StateKey<T> : never;

type SelectorState<T, K extends PropertyKey> = T extends CoreStore
  ? Pick<StoreState<T>, Extract<K, StateKey<T>>>
  : never;

type StoreStateObject<T extends StateStore, S> = Record<
  string,
  StateKey<T> | ((state: S) => any)
>;

type StoreStateObjectResult<
  T extends StateStore,
  S extends StoreState<T> | undefined,
  O extends Record<string, StateKey<T> | AnyFunction>,
> = {
  [K in keyof O]: O[K] extends keyof StoreState<T>
    ? O[K] extends keyof S
      ? S[O[K]]
      : StoreState<T>[O[K]] | undefined
    : O[K] extends AnyFunction
      ? ReturnType<O[K]>
      : never;
};

function useStoreStateObject<
  T extends CoreStore,
  O extends StoreStateObject<T, StoreState<T>>,
>(store: T, object: O): StoreStateObjectResult<T, StoreState<T>, O>;
function useStoreStateObject<
  T extends StateStore,
  O extends StoreStateObject<T, StoreState<T> | undefined>,
>(store: T, object: O): StoreStateObjectResult<T, StoreState<T> | undefined, O>;
function useStoreStateObject<
  T extends CoreStore,
  K extends SelectorStateKey<T>,
  O extends StoreStateObject<T, SelectorState<T, K>>,
>(
  store: T,
  keys: readonly K[],
  object: O,
): StoreStateObjectResult<T, StoreState<T>, O>;
function useStoreStateObject<
  T extends CoreStore,
  K extends SelectorStateKey<T>,
  O extends StoreStateObject<T, SelectorState<T, K> | undefined>,
>(
  store: StateStore<T>,
  keys: readonly K[],
  object: O,
): StoreStateObjectResult<T, StoreState<T> | undefined, O>;
```

接收 Ariakit 存储对象(可以是) `null` 或者说 `undefined`)并返回当前状态。 与 `useStoreState`,此钩子接收到一个对象,该对象的密钥将映射到存储密钥或选择器函数。 在对象中存储密钥总是被订阅. 当选择器依赖密钥作为第二个参数被传递时,它们必须包含每个选择器读取的每个存储密钥,或者返回的快照可能保持停滞. 空列表意味着只有对象中的直接存储密钥会通知选择者.

示例

读取带有选定依赖关系的直接和衍生值 :

```js
const values = useStoreStateObject(store, ["value"], {
  value: "value",
  valueLength: (state) => state.value.length,
});
```

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

### `useStoreProps`

```ts
function useStoreProps<
  S extends State,
  P extends Partial<S>,
  K extends keyof S,
  SK extends keyof PickByValue<P, SetState<P[K]>>,
>(store: CoreStore<S>, props: P, key: K, setKey?: SK): void;
```

将商店与道具同步,包括母店道具.

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

### `useStore`

```ts
function useStore<T extends CoreStore, P>(
  createStore: (props: P) => T,
  props: P,
): readonly [T & { useState: UseState<StoreState<T>> }, () => void];
```

从核心存储对象创建反应存储并返回一个与存储并更新存储的tuple和函数.

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

### `Store`

```ts
type Store<T extends CoreStore = CoreStore> = T & {
  /**
   * Re-renders the component when the state changes and returns the current
   * state.
   * @deprecated Use
   *   [`useStoreState`](https://ariakit.com/reference/use-store-state) instead.
   */
  useState: UseState<StoreState<T>>;
};
```

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

## 常见问题

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

Ariakit 反应商店公用事业

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

在项目目录运行 npm install @ariakit/react-store，或使用 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-store 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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