# @ahoo-wang/fetcher-react 中文文档

规范地址：https://npmcn.com/package/%40ahoo-wang/fetcher-react/

版本：6\.0\.1
npm 元数据更新时间：2026-10-04T12:11:28.510Z
中文译文更新时间：2026-11-06T03:00:54.406Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40ahoo-wang/fetcher-react
原文对照：https://npmcn.com/package/%40ahoo-wang/fetcher-react/?lang=original
项目主页：https://github.com/Ahoo-Wang/fetcher/tree/main/packages/react
源码仓库：https://github.com/Ahoo-Wang/fetcher

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

- 包体积（解压后）：437 kB，153 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.20\.8
- 运行依赖：2 个
- peer 依赖：react ^19\.0\.0，@ahoo-wang/fetcher ^6\.0\.1，@ahoo-wang/fetcher-cosec ^6\.0\.1，@ahoo-wang/fetcher-storage ^6\.0\.1，@ahoo-wang/fetcher-eventbus ^6\.0\.1
- 首次发布：2025-09-13T05:08:43.091Z
- 最新版本发布：2026-10-04T12:11:28.076Z
- 近 30 天下载量：6014（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：266（近 12 个月 139 个）

## 中文简介

Faster HTTP 客户端的响应集成 。 反应钩将可取消请求变为组件状态,并加上安全,存储和事件-bus绑定.

## 安装

```sh
npm install @ahoo-wang/fetcher-react
```

也可以使用：`pnpm add @ahoo-wang/fetcher-react`、`yarn add @ahoo-wang/fetcher-react`、`bun add @ahoo-wang/fetcher-react`

## README

# `@ahoo-wang/fetcher-react`

面向 Fetcher 请求、查询状态、存储、事件与 CoSec 安全的 React Hooks。组件需要持有异步状态和取消行为时使用。

## 安装

```bash
pnpm add react react-dom @ahoo-wang/fetcher @ahoo-wang/fetcher-react
```

按导入的集成安装对应 peer 包：EventBus、Storage 或 CoSec。

> **Wow 查询 Hook 已迁出。** `useSingleQuery`、`useListQuery`、`usePagedQuery`、 `useCountQuery`、`useListStreamQuery` 等 Wow Hook 已迁往 [Wow 仓库](https://github.com/Ahoo-Wang/Wow/tree/main/typescript) 的 `@ahoo-wang/wow-react`，版本跟随 Wow。数据监控 Hook（`useDataMonitor`、 `DataMonitorService`）随 `@ahoo-wang/fetcher-viewer` 一起退役。 `@ahoo-wang/wow-react` 自 Wow 9.2.0 起已发布到 npm，自 Wow 9.2.1 起兼容 fetcher 6。升级时先切换到 `@ahoo-wang/wow-react`（9.2.1 及以上），再升级 fetcher；文档见 [wow.ahoo.me](https://wow.ahoo.me/)。5.x 版本线（`5.x` 分支， npm 上的 5.1.x）继续为存量用户提供 `@ahoo-wang/fetcher-react` 里的 Wow Hook 与数据监控 Hook。

## 示例

查询放在你自己的状态里；内容变化时 Hook 执行它，并取消被替换的请求。

```tsx
import { useState } from 'react';
import { useQuery } from '@ahoo-wang/fetcher-react';

export function UserSearch() {
  const [query, setQuery] = useState({ keyword: '' });
  const { loading, result, error } = useQuery({
    query,
    execute: (query, abortController) =>
      api.searchUsers(query, abortController),
  });

  return (
    <section>
      <input
        value={query.keyword}
        onChange={e => setQuery({ keyword: e.target.value })}
      />
      {loading && <p>搜索中…</p>}
      {error && <p role="alert">搜索失败</p>}
      {result?.map(user => (
        <p key={user.id}>{user.name}</p>
      ))}
    </section>
  );
}
```

`execute` 从不 reject：它 resolve 为本次请求结束时的状态；被新请求、`abort()`、 `reset()` 或卸载取消时为 `idle`。

```tsx
import { ResultExtractors } from '@ahoo-wang/fetcher';
import { useFetcher } from '@ahoo-wang/fetcher-react';

export function SaveButton({ user }: { user: User }) {
  const { loading, execute } = useFetcher<User>({
    resultExtractor: ResultExtractors.Json,
  });

  const save = async () => {
    const { status, error } = await execute({
      url: `/api/users/${user.id}`,
      method: 'PUT',
      body: user,
    });
    if (status === 'success') toast('已保存');
    else if (status === 'error') toast(error.message);
  };

  return (
    <button disabled={loading} onClick={() => void save()}>
      保存
    </button>
  );
}
```

## 按任务选择 Hook

-   异步核心：Promise 状态、可取消的执行、受控查询、防抖值与防抖回调、最新引用。
-   Fetcher：请求执行、JSON 查询、防抖请求与防抖查询。
-   API 对象：从返回 Promise 的方法派生 execute/query Hooks。
-   状态：类型化 KeyStorage 与事件总线订阅。
-   CoSec：安全 Provider、用户状态与路由守卫。

## 文档

-   [React 数据流](https://fetcher.ahoo.me/zh/guides/react/)
-   [React 参考](https://fetcher.ahoo.me/zh/reference/react)
-   [交互式 Hook Story](https://fetcher.ahoo.me/storybook/)

[English](https://npmcn.com/package/%40ahoo-wang/fetcher-react/README.md) · [许可证](https://npmcn.com/package/LICENSE)

### 子路径入口

核心 Hook（`useExecutePromise`、`useQuery`、`useDebouncedQuery` 等）也可从 ESM 子路径 `@ahoo-wang/fetcher-react/core` 导入，Fetcher Hook（`useFetcher`、 `useFetcherQuery` 及其防抖版本）也可从 `@ahoo-wang/fetcher-react/fetcher` 导入。 两者都不加载安全、存储与事件总线集成。根入口与它们共用模块，不同入口的 Hook 可以 混用；`pnpm test:package` 在构建产物上验证这一点，并包含在 `build` 中。

## 常见问题

### @ahoo-wang/fetcher-react 是什么？

Faster HTTP 客户端的响应集成 。 反应钩将可取消请求变为组件状态,并加上安全,存储和事件-bus绑定\.

### 如何安装 @ahoo-wang/fetcher-react？

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

### @ahoo-wang/fetcher-react 支持 TypeScript 吗？

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

### @ahoo-wang/fetcher-react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ahoo-wang/fetcher-react 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.20\.8。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ahoo-wang/fetcher-react 可以商用吗？

@ahoo-wang/fetcher-react 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ahoo-wang/fetcher-react 的下载量有多少？

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

### @ahoo-wang/fetcher-react 还在维护吗？

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