# @gadgetinc/core 中文文档

规范地址：https://npmcn.com/package/%40gadgetinc/core/

版本：0\.15\.1
npm 元数据更新时间：2025-12-16T17:56:16.936Z
中文译文更新时间：2026-11-15T20:50:53.171Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：333 kB，83 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@urql/core \>=4\.0\.0
- 首次发布：2025-10-08T00:52:19.646Z
- 最新版本发布：2025-12-16T17:56:16.681Z
- 近 30 天下载量：39531（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 2 个）

## 中文简介

此软件包包含所有 Gadget 客户端执行必须遵循的核心类型和接口 . `@gadgetinc/core` 定义所有生成的API客户端、连接、模型管理器、记录和业务共享的合同

## 安装

```sh
npm install @gadgetinc/core
```

也可以使用：`pnpm add @gadgetinc/core`、`yarn add @gadgetinc/core`、`bun add @gadgetinc/core`

## README

# 核心

此软件包包含所有 Gadget 客户端执行必须遵循的核心类型和接口 . `@gadgetinc/core` 定义所有生成的 Gadget 客户端共享的API 客户端、连接、模型管理器、记录和操作的合同.

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

## 概览

`@gadgetinc/core` 提供 **类型系统基础** 为 Gadget 框架。 它导出 TypeScript 类型和接口:

-   定义 Gadget API 客户端的长相(`AnyClient`(中文(简体) )
-   指定与 Gadget 后端的连接如何工作( U)`AnyConnection`(中文(简体) )
-   描述模式管理者及其业务`AnyModelManager`, (中文(简体) ), `AnyInternalModelManager`(中文(简体) )
-   定义记录形状和行为( E)`GadgetRecord`, (中文(简体) ), `GadgetRecordList`(中文(简体) )
-   为查询数据提供过滤、排序和选择类型
-   宣布动作和函数元数据结构

## 密钥导出

### 客户端连接类型( C)

-   **`AnyClient`** - Gadget app的 API 客户端实例的接口 。 定义方法如 `query()`, (中文(简体) ), `mutate()`, (中文(简体) ), `transaction()`属性 `connection` 财务报告和审定财务报表 `internal`。 。 。 .
-   **`AnyConnection`** - 管理Gadget后端连接的接口,包括认证、GraphQL客户端访问和交易支持.
-   **`AnyCoreImplementation`** - 核心公用功能的接口,例如 `GadgetRecord` 构造,可变分解,以及错误处理.

### 模式记录类型( R)

-   **`AnyModelManager`** - 代表一个模型的API的通用接口(例如, `api.widget`) (中文(简体) ). 提供方法像 `findOne()`, (中文(简体) ), `findMany()`, (中文(简体) ), `findFirst()`。 。 。 .
-   **`AnyInternalModelManager`** - Gadget后端代码内部使用的API模型管理器的接口.
-   **`GadgetRecord`** - 是GadgetAPI电话回的一张唱片 包括改变跟踪、外地访问和序列化的帮助方法.
-   **`GadgetRecordList`** - 一组 `GadgetRecord` 有内建页化支持的例( e)`hasNextPage`, (中文(简体) ), `nextPage()`(见a/c.5/49/70,附件).

### 动作和函数类型

-   **`ActionFunction`** - 模型动作的元数据和类型(创建、更新、删除、自定义动作).
-   **`BulkActionFunction`** - 多个记录的散装作业元数据.
-   **`GlobalActionFunction`** - 全球行动元数据与具体模式无关.
-   **`ViewFunction`** - 后端视图查询元数据.

### 查询过滤类型( F)

包输出用于查询 Gadget 数据的综合性类型定义 :

-   **过滤类型**数字 : `IDFilter`, (中文(简体) ), `StringFilter`, (中文(简体) ), `IntFilter`, (中文(简体) ), `FloatFilter`, (中文(简体) ), `DateTimeFilter`, (中文(简体) ), `JSONFilter`, (中文(简体) ), `BooleanFilter`, (中文(简体) ), `StateFilter`等 (中文(简体) ).
-   **`AnyFilter`** - 所有过滤器类型的联盟类型,支持 `AND`, (中文(简体) ), `OR`,以及 `NOT` 组合器 .
-   **`AnySort`** - 排序命令的类型,包括基于字段的排序和矢量相似排序.
-   **`FieldSelection`** - 从 GraphQL 回复中选择特定字段的类型.
-   **选项类型**数字 : `FindManyOptions`, (中文(简体) ), `BaseFindOptions`, (中文(简体) ), `InternalFindOptions`等 (中文(简体) ).

### 工具类型

-   **`Select<Schema, Selection>`** - 用于根据选定方法提取一个子集的用途.
-   **`DefaultSelection<Available, Options, Defaults>`** - 在不提供选择时用于默认选择的功能.
-   **`AvailableSelection<Schema>`** - 将计划类型转换为有效的选择选项.
-   **斯卡尔类型**数字 : `GadgetID`, (中文(简体) ), `DateTime`, (中文(简体) ), `EmailAddress`, (中文(简体) ), `URLString`, (中文(简体) ), `JSONBlob`, (中文(简体) ), `CurrencyAmount`等 (中文(简体) ).

## 建筑

这个 `@gadgetinc/core` 软件包使用TypeScript的结构打字来定义合同而无需强制实施细节. 生成了Gadget客户端执行这些接口,确保所有应用程序的API一致.

### 内部状态符号

用于给客户对象附加内部状态的包导符号 :

```typescript
export const $modelRelationships = Symbol.for("gadget/modelRelationships");
export const $coreImplementation = Symbol.for("gadget/coreImplementation");
```

这些符号允许生成的客户端存储元数据和执行细节而不会污染公共API表面.

### 变化跟踪

`GadgetRecord` 包括用于检测修改的内置变化跟踪:

```typescript
record.changed(); // Returns true if any field has changed
record.changes(); // Returns { field: { current, previous } } for changed fields
record.flushChanges(); // Marks current state as "saved"
record.revertChanges(); // Reverts to last saved state
```

这使得乐观的UI更新和高效的数据同步成为可能.

### 倾斜

`GadgetRecordList` 扩展 `Array<GadgetRecord>` 使用页形辅助工具:

```typescript
list.hasNextPage; // boolean
list.endCursor; // string cursor for next page
await list.nextPage(); // Fetches next page of results
```

此执行中继光标风格的光标在全部 Gadget API 上进行 pagination .

## 对于 Gadget 开发者

这个包是 **单一真相来源** 用于整个Gadget生态系统的类型定义。 添加新功能时 :

1.  在此先定义类型 `@gadgetinc/core`
2.  已生成客户端执行新类型
3.  更新框架软件包`@gadgetinc/react`(d) 利用新类型
4.  确保向后兼容或协调断开更改

这个 `testing/` 子目录出口测试公用事业,如 `mockUrqlClient` 用于其他包件的测试套件.

### 出版

发布新版本后 `@gadgetinc/core`,确保:

1.  生成的客户端被重新生成以使用新版本
2.  框架软件包 `@gadgetinc/react` 财务报告和审定财务报表 `@gadgetinc/client-hooks` 正在更新
3.  这个 `PlatformDependencyVersions` 更新 Gadget 主线中的变量

## 常见问题

### @gadgetinc/core 是什么？

此软件包包含所有 Gadget 客户端执行必须遵循的核心类型和接口 \. @gadgetinc/core 定义所有生成的API客户端、连接、模型管理器、记录和业务共享的合同

### 如何安装 @gadgetinc/core？

在项目目录运行 npm install @gadgetinc/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@urql/core（\>=4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gadgetinc/core 支持 TypeScript 吗？

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

### @gadgetinc/core 支持 ESM 还是 CommonJS？

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

### @gadgetinc/core 可以商用吗？

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

### @gadgetinc/core 的下载量有多少？

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

### @gadgetinc/core 还在维护吗？

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