# @gadgetinc/client-hooks 中文文档

规范地址：https://npmcn.com/package/%40gadgetinc/client-hooks/

版本：0\.1\.7
npm 元数据更新时间：2026-02-09T21:49:30.496Z
中文译文更新时间：2026-11-15T20:51:10.988Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gadgetinc/client-hooks
原文对照：https://npmcn.com/package/%40gadgetinc/client-hooks/?lang=original
项目主页：https://github.com/gadget-inc/js-clients/tree/main/packages/client-hooks
源码仓库：https://github.com/gadget-inc/js-clients

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

- 包体积（解压后）：380 kB，118 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-10-29T21:01:43.971Z
- 最新版本发布：2026-02-09T21:49:30.071Z
- 近 30 天下载量：31191（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 4 个）

## 中文简介

此套件包含用于React/Preact库中用于Gadget应用程序的核心钩子的共享执行. `@gadgetinc/client-hooks` 提供框架不可识别的钩子执行,这些执行被像 qqgadgetinc 这样的框架特定包所消耗

## 安装

```sh
npm install @gadgetinc/client-hooks
```

也可以使用：`pnpm add @gadgetinc/client-hooks`、`yarn add @gadgetinc/client-hooks`、`bun add @gadgetinc/client-hooks`

## README

# 客户钩

此套件包含用于React/Preact库中用于Gadget应用程序的核心钩子的共享执行. `@gadgetinc/client-hooks` 提供框架不可知的钩子执行,这些钩子被框架特定软件包所消耗,如 `@gadgetinc/react` 财务报告和审定财务报表 `@gadgetinc/preact`。 。 。 .

注意开发人员不需要直接使用此软件包,而是应该使用其生成的客户端加特定框架绑定软件包,如 `@gadgetinc/react`。 。 。 .

## 概览

`@gadgetinc/client-hooks` 设计为: **运行时间适配器模式** ,允许相同的钩子逻辑跨越不同的UI框架(React,Preact等). 套件导出 :

-   查询和变异 Gadget API 的核心钩子执行
-   A 类 `RuntimeAdapter` 用于执行特定框架软件包的接口
-   登记系统 `registerClientHooks` 将钩子绑入特定框架

## 建筑

库使用适配器模式保持框架不可知性:

```typescript
interface RuntimeAdapter {
  GadgetApiContext: Context<GadgetApiContext>;
  framework: FrameworkBindings; // useState, useEffect, useMemo, etc.
  urql: UrqlBindings; // useQuery, useMutation
}
```

特定框架软件包( 如 `@gadgetinc/react`)提供适配器的应用,将其映射到其框架的原始,然后调用 `registerClientHooks` 用适配器初始化钩子.

## 可用钩

### 查询钩

-   `useFindOne` - 以身份证获取单一记录
-   `useMaybeFindOne` - 通过身份证获取单一记录,如果找不到则返回无效
-   `useFindMany` - 获取带有过滤、排序和页码的记录页面
-   `useFindFirst` - 获取第一个记录匹配标准
-   `useMaybeFindFirst` - 获取第一个记录匹配标准, 如果找不到则返回无效
-   `useFindBy` - 以独特的字段值获取记录
-   `useGet` - 获取单通记录(例如当前会话)
-   `useView` - 从后端视图获取记录

### 变形钩

-   `useAction` - 在模型记录上运行动作(创建、更新、删除等)
-   `useBulkAction` - 立即对多个记录进行动作
-   `useGlobalAction` - 开展全球行动

### 工具钩

-   `useFetch` - 让 HTTP 请求到后端路由
-   `useEnqueue` - 安排背景行动
-   `useQuery` - 低等图形QL 查询钩
-   `useMutation` - 低等图克QL突变钩
-   `useApi` - 访问 Gadget API 客户端实例
-   `useConnection` - 访问 Gadget 连接实例
-   `useCoreImplementation` - 获取核心实施细节

## 框架软件包如何使用此软件包

框架专用软件包,如 `@gadgetinc/react` 遵循此模式 :

1.  进口车钩和公用事业 `@gadgetinc/client-hooks`
2.  创建一个 `RuntimeAdapter` 执行《公约》和《京都议定书》
3.  创建一个 `Provider` 调用组件 `registerClientHooks`
4.  再出口终端用户的钩子

示例

```typescript
import { registerClientHooks, useAction, useFindMany } from "@gadgetinc/client-hooks";
import { useContext, useMemo /* ... */ } from "react";
import { useQuery, useMutation } from "urql";

// Create adapter for React
const adapter: RuntimeAdapter = {
  framework: { useContext, useMemo /* ... */ },
  urql: { useQuery, useMutation, Provider },
  GadgetApiContext: createContext(/* ... */),
};

// Provider component initializes the hooks
export const Provider = ({ api, children }) => {
  const { gadgetClient, urqlClient } = registerClientHooks(api, adapter);
  // ... render provider with context
};

// Re-export hooks for users
export { useAction, useFindMany /* ... */ };
```

## 对于 Gadget 开发者

这个包旨在减少React和Preact(以及可能的其他框架)之间的代码重复. 添加新功能时 :

1.  执行钩入逻辑 `@gadgetinc/client-hooks`
2.  使用 `RuntimeAdapter` 任何针对具体框架的呼吁
3.  从包中导出钩子
4.  从框架包中再出口, 如 `@gadgetinc/react`

钩子注册系统使用支架图案,如果在正常位置外调用,钩子会丢出有用的错误 `Provider` 上下文,然后改为一次实际执行 `registerClientHooks` 名为.

## 常见问题

### @gadgetinc/client-hooks 是什么？

此套件包含用于React/Preact库中用于Gadget应用程序的核心钩子的共享执行\. @gadgetinc/client-hooks 提供框架不可识别的钩子执行,这些执行被像 qqgadgetinc 这样的框架特定包所消耗

### 如何安装 @gadgetinc/client-hooks？

在项目目录运行 npm install @gadgetinc/client-hooks，或使用 pnpm add / yarn add / bun add。

### @gadgetinc/client-hooks 支持 TypeScript 吗？

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

### @gadgetinc/client-hooks 支持 ESM 还是 CommonJS？

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

### @gadgetinc/client-hooks 可以商用吗？

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

### @gadgetinc/client-hooks 的下载量有多少？

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

### @gadgetinc/client-hooks 还在维护吗？

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