# @hcengineering/api-client 中文文档

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

版本：0\.7\.423
npm 元数据更新时间：2026-05-10T01:48:44.523Z
中文译文更新时间：2026-11-17T17:53:29.075Z
软件包许可：EPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40hcengineering/api-client
原文对照：https://npmcn.com/package/%40hcengineering/api-client/?lang=original
项目主页：https://github.com/hcengineering/huly.core#readme
源码仓库：https://github.com/hcengineering/huly.core

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

- 包体积（解压后）：309 kB，81 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2025-10-07T05:36:42.368Z
- 最新版本发布：2026-05-10T01:48:44.089Z
- 近 30 天下载量：13950（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 5 个）

## 中文简介

一个用于与Huly平台API互动的TypeScript客户端库.

## 安装

```sh
npm install @hcengineering/api-client
```

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

## README

# Huly 平台 API 客户端

一个用于与Huly平台API互动的TypeScript客户端库.

## 安装

为了能够安装所需的软件包,您需要获得GitHub访问令牌. 您可以按照指示创建符号 [这里](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token)。 。 。 .

```bash
npm install @hcengineering/api-client
```

## WebSocket 客户端对 REST 客户端

Api客户端包提供两个主要客户端变体:一个WebSocket客户端和一个REST客户端. WebSocket客户端持有与Huly平台API的持续连接. REST客户端使用标准的HTTP请求来进行操作.

### WebSocket 客户端

```ts
import { connect } from '@hcengineering/api-client'

// Connect to Huly
const client = await connect('https://huly.app', {
  email: 'johndoe@example.com',
  password: 'password',
  workspace: 'my-workspace',
})

// Use the client to perform operations
...

// Close the client when done
await client.close()
```

### REST 客户端

```ts
import { connectRest } from '@hcengineering/api-client'

// Connect to Huly
const client = await connectRest('https://huly.app', {
  email: 'johndoe@example.com',
  password: 'password',
  workspace: 'my-workspace'
})

// Use the client to perform operations
...

```

## 认证

客户端支持两种认证方法:使用电子邮件和密码,或者使用符号. 认证后,客户端将可获得与用户相同的资源.

> 注:以下示例使用WebSocket客户端(`connect`) (中文(简体) ). 要使用 REST 客户端, 导入和调用 `connectRest` 有相同的选择.

参数:

-   `url`: Huly 实例的 URL, 用于 Huly Cloud `https://huly.app`
-   `options`连接选项
    -   `workspace`:要连接的工作空间名称,工作空间名称可见于工作空间的URL: `https://huly.app/workbench/<workspace-name>`
    -   `token`: 可选认证符
    -   `email`: 可选用户电子邮件
    -   `password`: 可选用户密码

### 使用电子邮件和密码

```ts
import { connect } from '@hcengineering/api-client'

const client = await connect('https://huly.app', {
  email: 'johndoe@example.com',
  password: 'password',
  workspace: 'my-workspace'
})

...

await client.close()
```

### 使用托肯语

```ts
import { connect } from '@hcengineering/api-client'

const client = await connect('https://huly.app', {
  token: '...',
  workspace: 'my-workspace'
})

...

await client.close()
```

## 客户端 API

客户端提供了一套与Huly平台API互动的方法. 本节介绍客户端可用的主要方法.

### 获取 API

客户端提供了检索文件的两种主要方法: `findOne` 财务报告和审定财务报表 `findAll`。 。 。 .

#### 找到一个

获取符合查询标准的单一文档.

参数:

-   `_class`: 要查找的对象的分类, 结果将包含目标类的所有子分类
-   `query`: 查询标准
-   `options`: 查找选项
    -   `limit`: 限制返回结果的数量
    -   `sort`: 排序标准
    -   `lookup`: 查询标准
    -   `projection`: 预测标准
    -   `total`: 如果返回指定总数

示例

```ts
import contact from '@hcengineering/contact'

...

const person = await client.findOne(
  contact.class.Person,
  {
    _id: 'person-id'
  }
)
```

#### 查找全部

获取符合查询标准的多文档.

参数:

-   `_class`: 要查找的对象的分类, 结果将包含目标类的所有子分类
-   `query`: 查询标准
-   `options`: 查找选项
    -   `limit`: 限制返回结果的数量
    -   `sort`: 排序标准
    -   `lookup`: 查询标准
    -   `projection`: 预测标准
    -   `total`: 如果返回指定总数

示例

```ts
import { SortingOrder } from '@hcengineering/core'
import contact from '@hcengineering/contact'

..

const persons = await client.findAll(
  contact.class.Person,
  {
    city: 'New York'
  },
  {
    limit: 10,
    sort: {
      name: SortingOrder.Ascending
    }
  }
)
```

### API 文档

客户端提供三种管理文件的主要方法: `createDoc`, (中文(简体) ), `updateDoc`,以及 `removeDoc`。这些方法允许您在文档上执行 CRUD 操作.

#### 创建文件

在指定空间创建新文档.

参数:

-   `_class`: 对象的类别
-   `space`: 物体的空间
-   `attributes`: 对象的属性
-   `id`: 对象的可选标识, 如果不提供, 将生成新的标识

示例

```ts
import contact, { AvatarType } from '@hcengineering/contact'

..

const personId = await client.createDoc(
  contact.class.Person,
  contact.space.Contacts,
  {
    name: 'Doe,John',
    city: 'New York',
    avatarType: AvatarType.COLOR
  }
)
```

#### 更新文件

更新现有文档.

参数:

-   `_class`: 对象的类别
-   `space`: 物体的空间
-   `objectId`: 对象编号
-   `operations`: 要更新的对象属性

示例

```ts
import contact from '@hcengineering/contact'

..

await client.updateDoc(
  contact.class.Person,
  contact.space.Contacts,
  personId,
  {
    city: 'New York',
  }
)
```

#### 删除文件

删除已存在的文档.

参数:

-   `_class`: 对象的类别
-   `space`: 物体的空间
-   `objectId`: 对象编号

示例

```ts
import contact from '@hcengineering/contact'

..

await client.removeDoc(
  contact.class.Person,
  contact.space.Contacts,
  personId
)
```

### 收藏 API

#### 添加缩放

在指定的收藏中创建新的附加文档.

参数:

-   `_class`: 要创建的对象的类别
-   `space`: 创建对象的空间
-   `attachedTo`: 附加到
-   `attachedToClass`: 附加到
-   `collection`: 载有所附文件的集合名称
-   `attributes`: 对象的属性
-   `id`: 对象的可选标识, 如果不提供, 将生成新的标识

示例

```ts
import contact, { AvatarType } from '@hcengineering/contact'

..

const personId = await client.createDoc(
  contact.class.Person,
  contact.space.Contacts,
  {
    name: 'Doe,John',
    city: 'New York',
    avatarType: AvatarType.COLOR
  }
)

await client.addCollection(
  contact.class.Channel,
  contact.space.Contacts,
  personId,
  contact.class.Person,
  'channels',
  {
    provider: contact.channelProvider.Email,
    value: 'john.doe@example.com'
  }
)
```

#### 更新

更新收藏中现有的附件文档.

参数:

-   `_class`: 要更新的对象的分类
-   `space`: 需更新的天体空间
-   `objectId`: 需更新的天体空间
-   `attachedTo`: 父对象的ID
-   `attachedToClass`: 母对象的类
-   `collection`: 载有所附文件的集合名称
-   `attributes`: 要更新的对象属性

示例

```ts
import contact from '@hcengineering/contact'

..

await client.updateCollection(
  contact.class.Channel,
  contact.space.Contacts,
  channelId,
  personId,
  contact.class.Person,
  'channels',
  {
    city: 'New York',
  }
)
```

#### 删除收集

从收藏中删除已存在的附件文档.

参数:

-   `_class`: 要删除的对象的类别
-   `space`: 删除对象的空间
-   `objectId`: 删除对象的空间
-   `attachedTo`: 父对象的ID
-   `attachedToClass`: 母对象的类
-   `collection`: 载有所附文件的集合名称

示例

```ts
import contact from '@hcengineering/contact'

..

await client.removeCollection(
  contact.class.Channel,
  contact.space.Contacts,
  channelId,
  personId,
  contact.class.Person,
  'channels'
)
```

### 混合 API

客户端提供两种管理混音的方法: `createMixin` 财务报告和审定财务报表 `updateMixin`。 。 。 .

#### 创建密克辛

为指定的文档创建新组合.

参数:

-   `objectId`: 混合体附着于
-   `objectClass`: 组合符所附加的对象的类别
-   `objectSpace`: 混合体附着在物体上的空间
-   `mixin`: 要更新的混音类型代码
-   `attributes`: 混音的属性

```ts
import contact, { AvatarType } from '@hcengineering/contact'

..

const personId = await client.createDoc(
  contact.class.Person,
  contact.space.Contacts,
  {
    name: 'Doe,John',
    city: 'New York',
    avatarType: AvatarType.COLOR
  }
)

await client.createMixin(
  personId,
  contact.class.Person,
  contact.space.Contacts,
  contact.mixin.Employee,
  {
    active: true,
    position: 'CEO'
  }
)
```

#### 更新密克辛

更新已有的混音符.

参数:

-   `objectId`: 混合体附着于
-   `objectClass`: 组合符所附加的对象的类别
-   `objectSpace`: 混合体附着在物体上的空间
-   `mixin`: 要更新的混音类型代码
-   `attributes`: 组合的属性以更新

```ts
import contact, { AvatarType } from '@hcengineering/contact'

..

const person = await client.findOne(
  contact.class.Person,
  {
    _id: 'person-id'
  }
)

await client.updateMixin(
  personId,
  contact.class.Person,
  contact.space.Contacts,
  contact.mixin.Employee,
  {
    active: false
  }
)
```

## 常见问题

### @hcengineering/api-client 是什么？

一个用于与Huly平台API互动的TypeScript客户端库\.

### 如何安装 @hcengineering/api-client？

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

### @hcengineering/api-client 支持 TypeScript 吗？

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

### @hcengineering/api-client 支持 ESM 还是 CommonJS？

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

### @hcengineering/api-client 可以商用吗？

@hcengineering/api-client 使用 EPL-2\.0 许可。声明的许可为 EPL-2\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @hcengineering/api-client 的下载量有多少？

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

### @hcengineering/api-client 还在维护吗？

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

