@hcengineering/api-client

中文文档
0.7.423发布于 2026/05/10EPL-2.0TypeScriptESM + CJS近 30 天下载 1.4万

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

中文使用文档
文档目录12 节
  1. 安装
  2. WebSocket 客户端对 REST 客户端
  3. WebSocket 客户端
  4. REST 客户端
  5. 认证
  6. 使用电子邮件和密码
  7. 使用托肯语
  8. 客户端 API
  9. 获取 API
  10. API 文档
  11. 收藏 API
  12. 混合 API

Huly 平台 API 客户端

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

安装

为了能够安装所需的软件包,您需要获得GitHub访问令牌. 您可以按照指示创建符号 这里。 。 。 .

npm install @hcengineering/api-client

WebSocket 客户端对 REST 客户端

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

WebSocket 客户端

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

// Connect to Huly
const client = await connect('https://huly.app', {
  email: '[email protected]',
  password: 'password',
  workspace: 'my-workspace',
})

// Use the client to perform operations
...

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

REST 客户端

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

// Connect to Huly
const client = await connectRest('https://huly.app', {
  email: '[email protected]',
  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: 可选用户密码

使用电子邮件和密码

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

const client = await connect('https://huly.app', {
  email: '[email protected]',
  password: 'password',
  workspace: 'my-workspace'
})

...

await client.close()

使用托肯语

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: 如果返回指定总数

示例

import contact from '@hcengineering/contact'

...

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

查找全部

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

参数:

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

示例

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: 对象的可选标识, 如果不提供, 将生成新的标识

示例

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: 要更新的对象属性

示例

import contact from '@hcengineering/contact'

..

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

删除文件

删除已存在的文档.

参数:

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

示例

import contact from '@hcengineering/contact'

..

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

收藏 API

添加缩放

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

参数:

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

示例

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: '[email protected]'
  }
)

更新

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

参数:

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

示例

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: 载有所附文件的集合名称

示例

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: 混音的属性
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: 组合的属性以更新
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 共发布 13 个版本,首次发布于 2025/10/07;过去 12 个月发布了 5 个版本。

版本发布日期距今
0.7.423latest2026/05/106 个月前
0.7.4132026/04/147 个月前
0.7.4112026/04/127 个月前
0.7.3822026/03/168 个月前
0.7.192026/02/228 个月前
0.7.182025/10/281.1 年前

关于 @hcengineering/api-client 的常见问题

@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 和提交记录判断。