# @dotcms/types 中文文档

规范地址：https://npmcn.com/package/%40dotcms/types/

版本：26\.11\.2-3
npm 元数据更新时间：2026-11-11T19:25:18.824Z
中文译文更新时间：2026-11-12T19:20:45.854Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40dotcms/types
原文对照：https://npmcn.com/package/%40dotcms/types/?lang=original

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

- 包体积（解压后）：151 kB，29 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-05-02T17:26:23.776Z
- 最新版本发布：2026-11-11T19:25:18.634Z
- 近 30 天下载量：9224（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：257（近 12 个月 192 个）

## 中文简介

这个 `@dotcms/types` 软件包中包含用于dotCMS生态系统的TypeScript类型定义. 在与dotCMS API和结构化内容合作时,利用它实现类型安全并增强开发者的经验.

## 安装

```sh
npm install @dotcms/types
```

也可以使用：`pnpm add @dotcms/types`、`yarn add @dotcms/types`、`bun add @dotcms/types`

## README

# dotCMS 类型库

这个 `@dotcms/types` 软件包中包含用于dotCMS生态系统的TypeScript类型定义. 在与dotCMS API和结构化内容合作时,利用它实现类型安全并增强开发者的经验.

📦 [@ dotcms/ npm 上的类型](https://www.npmjs.com/package/@dotcms/types) 🛠️ [在 GitHub 上查看来源](https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/types)

## 目录

-   [概览](https://npmcn.com/package/%40dotcms/types/#readme-overview)
-   [安装](https://npmcn.com/package/%40dotcms/types/#readme-installation)
-   [我该用哪个SDK版本?](https://npmcn.com/package/%40dotcms/types/#readme-which-sdk-version-should-i-use)
-   [常用类型](https://npmcn.com/package/%40dotcms/types/#readme-commonly-used-types)
-   [类型等级( 合并到定义)](https://npmcn.com/package/%40dotcms/types/#readme-type-hierarchy-jump-to-definitions)
    -   [AI 搜索](https://npmcn.com/package/%40dotcms/types/#readme-ai-search)
    -   [dotCMS 内容和页面](https://npmcn.com/package/%40dotcms/types/#readme-dotcms-content--pages)
    -   [通用视觉编辑器( UVE)](https://npmcn.com/package/%40dotcms/types/#readme-universal-visual-editor-uve)
    -   [块编辑器](https://npmcn.com/package/%40dotcms/types/#readme-block-editor)
    -   [客户端 & HTTP](https://npmcn.com/package/%40dotcms/types/#readme-client--http)
    -   [处理错误](https://npmcn.com/package/%40dotcms/types/#readme-error-handling)
-   [用法实例](https://npmcn.com/package/%40dotcms/types/#readme-usage-examples)
    -   [类型检查出错](https://npmcn.com/package/%40dotcms/types/#readme-error-type-checking)
-   [支助](https://npmcn.com/package/%40dotcms/types/#readme-support)
-   [捐款](https://npmcn.com/package/%40dotcms/types/#readme-contributing)
-   [许可证发放](https://npmcn.com/package/%40dotcms/types/#readme-licensing)
-   [更改日志](https://npmcn.com/package/%40dotcms/types/#readme-changelog)

## 概览

### 何时使用

-   以 dotCMS 构建类型脚本应用程序
-   在您的点CMS集成中启用类型安全
-   获得更好的 IDE 自动完成和错误检查
-   与 dotCMS 客户端 SDK 或其他 SDK 软件包合作

### 主要惠益

-   **类型安全**: 在编译时间而不是运行时间获取错误
-   **IDE 支持**: 丰富的自动完成和内置文档
-   **更好的开发者经验**: 清除所有点CMS数据结构的接口
-   **框架不可知论**: 任何类型脚本工程的工程

## 安装

```bash
npm install @dotcms/types@latest --save-dev
```

## 我该用哪个SDK版本?

dotCMS SDKs 发布在锁定步骤中,同时发布 dotCMS 本身: 每 `@dotcms/*` 货包船 地点 **完全相同的版本编号** 作为点CMS的发布,它是为(例如:点CMS)而建的 `26.7.14-1` → `@dotcms/client@26.7.14-1`, (中文(简体) ), `@dotcms/react@26.7.14-1`,等等).

**简单的拇指规则:使用匹配您点CMS实例版本的 SDK 版本.**

每次dotCMS发布新版本(反之亦然)时,你不必升级SDK. 大部分的发布都不会改变SDK所依赖的东西,所以一个更老的SDK通常会继续工作 对一个新的点CMS案例,罚款。 但偶尔,释放确实包括一个真正的 打破更改——如果您的 SDK 年龄超过此点, 它会停止正确工作 .

你不需要自己去跟踪它: 你的点CMS实例总是知道最古老的SDK 版本它仍然支持,SDK自动对照它检查自己. 狦琌 使用SDK这个太老了,你会看到一个清晰的警告 在你的控制台上告诉你 升级.

**建议:** 将您的 SDK 与您的点CMS 实例相同的版本连接, 并且只接通 当您升级了点CMS, 或者当控制台告诉你.

> **在LTS发布?** LTS发行版目前没有获得自己匹配的SDK版本. 在解决之前,请使用所出版的SDK版本,以便最接近定期发布 或者在你的LTS版本之前.
> 
> 想要更多关于dotCMS发布和支持窗口如何工作的背景吗? 见 [发布和支持生命周期( S)](https://dev.dotcms.com/docs/release-support-lifecycle)。 。 。 .

## 常用类型

```ts
import {
  DotCMSPageAsset,
  DotCMSPageResponse,
  UVEEventType,
  DotCMSInlineEditingPayload,
  DotHttpClient,
  DotHttpError,
  DotErrorPage,
  DotErrorContent,
  DotErrorNavigation,
  DotErrorAISearch,
  DotCMSAISearchParams,
  DISTANCE_FUNCTIONS
} from '@dotcms/types';
```

## 类型等级( 合并到定义)

### AI 搜索

> **实验:** AI搜索类型是实验性的,未来发布时可能会有突破性变化.

**AI 搜索参数:**

| 类型 | 说明 |
| --- | --- |
| [DotCMSAISearch 图片](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L85) | 完成 AI 搜索参数,包括查询和 AI 配置 |
| [DotCMSAISearch 查询](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L9) | 查询参数(限制、偏移、内容Type等) |
| [DotCMSAI 图形](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L50) | AI 配置( 门槛、 距离、 功能、 响应) |
| [分离-职能](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L103) | 向量相似性的现有距离函数 |

**AI 搜索回复 :**

| 类型 | 说明 |
| --- | --- |
| [DotCMSAISearch 响应](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L182) | AI 搜索 API 响应结构 |
| [DotCMSAISearch 压缩数据](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L213) | 与 AI 信息匹配的内容 |
| [DotCMSAISearch 游戏](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L195) | 与距离比对并提取出文本 |

**AI 搜索错误 :**

| 类型 | 说明 |
| --- | --- |
| [点错误AISearch](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L136) | AI 搜索 API 特定错误, 带有快捷、 索引Name 和参数上下文 |

### dotCMS 内容和页面

**页: 1**

| 类型 | 说明 |
| --- | --- |
| [DotCMSPage 组合](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L18) | 包含布局和内容的完整页面 |
| [点CMPage](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L515) | 核心页面数据 |
| [DotCMPage 响应](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1175) | API 对页面请求的回应 |
| [DotGraphQLAPI 响应](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1186) | 图QL API 响应结构 |

**内容 :**

| 类型 | 说明 |
| --- | --- |
| [DotCMS 基本内容](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1141) | 基本内容结构 |

**站点布局( B) :**

| 类型 | 说明 |
| --- | --- |
| [点数](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L733) | 站点信息 |
| [DotCMSTemplate 虚拟平台](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L432) | 页面模板 |
| [点数CMSLayout](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L622) | 页面布局结构 |
| [DotCMSPage 集成容器](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L138) | 集装箱定义 |

**导航 :**

| 类型 | 说明 |
| --- | --- |
| [DotCMSNAvigation 项目](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/nav/public.ts#L73) | 有等级支持的导航结构项目 |
| [DotCMSVanity 乌尔尔](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L80) | URL 重写和虚构 URL |
| [DotCMSURL 连接图](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L41) | URL 到内容映射 |

### 通用视觉编辑器( UVE)

**编辑器状态 :**

| 类型 | 说明 |
| --- | --- |
| [UVE 状态](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L30) | 当前编辑器状态 |
| [UVE 模式](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L55) | 编辑器模式( EDIT, PreviEW, PUBLSID) |
| [DotCMPage 渲染器模式](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L44) | 页面渲染模式 |

**编辑器事件 :**

| 类型 | 说明 |
| --- | --- |
| [UVEEvent Handler (英语)](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L67) | 事件处理器功能 |
| [UVEEvent 订阅器](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L90) | 事件订阅管理 |
| [紫外线](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L169) | 可用事件类型 |
| [UVEESTPayload 地图](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L199) | 事件有效载荷定义 |

**内置编辑 :**

| 类型 | 说明 |
| --- | --- |
| [DotCMS 内置编辑夹](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/events/public.ts#L13) | 内置编辑数据 |
| [DotCMS 内置编辑模式](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/events/public.ts#L1) | 线内编辑类型 |

### 块编辑器

| 类型 | 说明 |
| --- | --- |
| [块编辑器](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/components/block-editor-renderer/public.ts#L38) | 块编辑器内容结构 |
| [块编辑器节点](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/components/block-editor-renderer/public.ts#L18) | 单个区块/节点 |
| [块编辑器Mark](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/components/block-editor-renderer/public.ts#L7) | 文本格式化标记 |

### 客户端 & HTTP

**HTTP 客户端 :**

| 类型 | 说明 |
| --- | --- |
| [DotHttp 客户端](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L108) | HTTP 客户端接口用于自定义执行 |
| [BaseHttp 客户端](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L196) | 处理工具错误的抽象基类 |

**客户端配置 :**

| 类型 | 说明 |
| --- | --- |
| [DotCMS 客户端配置](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L395) | 客户端配置选项 |
| [点请求选项](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L383) | HTTP 请求选项 |
| [DotCMPage 请求标签](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L378) | 页面请求参数 |
| [DotCMS GraphQLParams (中文(简体) )](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L280) | 图QL 查询参数 |
| [DotCMSNavigation 请求标签](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/nav/public.ts#L39) | 导航请求选项 |

### 处理错误

**基准出错类型 :**

| 类型 | 说明 |
| --- | --- |
| [Http 错误细节](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L6) | HTTP 错误细节接口 |
| [DotHtp 错误](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L26) | 标准化的 HTTP 错误类 |

**域- 特定错误 :**

| 类型 | 说明 |
| --- | --- |
| [点错误](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1253) | 带有 GraphQL 上下文的页面 API 错误 |
| [Dot 错误](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/content/public.ts#L7) | 内容 API 特定错误处理 |
| [Dot 错误导航](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/nav/public.ts#L7) | 导航 API 错误处理 |
| [点错误AISearch](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L136) | AI 搜索 API 错误处理, 带有快取和参数 |

## 用法实例

### 类型检查出错

```typescript
import {
  DotHttpError,
  DotErrorPage,
  DotErrorContent,
  DotErrorNavigation,
  DotErrorAISearch
} from '@dotcms/types';

// Type-safe error handling
if (error instanceof DotHttpError) {
  // Access standardized HTTP error properties
  console.error(`HTTP ${error.status}: ${error.statusText}`);
  console.error('Response data:', error.data);
}

if (error instanceof DotErrorPage) {
  // Page-specific error with GraphQL context
  console.error('GraphQL query:', error.graphql?.query);
}

if (error instanceof DotErrorContent) {
  // Content-specific error context
  console.error(`${error.operation} failed for ${error.contentType}`);
}

if (error instanceof DotErrorAISearch) {
  // AI Search-specific error context
  console.error('AI Search failed for prompt:', error.prompt);
  console.error('Index name:', error.indexName);
  console.error('Search params:', error.params);
}
```

> **说明**: 完整的实施实例和使用模式,见 [@ dotcms/ 客户端](https://npmcn.com/package/%40dotcms/client/README.md) 软件包文档.

## 支助

我们提供多个渠道来获取对点CMS类型库的帮助:

-   **GitHub 问题**: 对于错误报告和特性请求,请 [打开一个问题](https://github.com/dotCMS/core/issues/new/choose) 在 GitHub 仓库中
-   **社区论坛**: 加入我们 [社区讨论](https://community.dotcms.com/) 问问题和分享解决方案
-   **叠叠流**:使用标签 `dotcms-types` 张贴问题时
-   **企业支助**:企业客户可通过 [dotCMS 支持门户](https://www.dotcms.com/support)

在报告问题时,请包括:

-   您使用的软件包版本
-   类型脚本版本
-   最小复制步骤
-   预期与实际行为

## 捐款

GitHub 拖取请求是向dotCMS提供代码的首选方法. 我们欢迎对 DotCMS 类型库的贡献! 如果你想作出贡献,请遵循这些步骤:

1.  叉子存储器 [点/核心](https://github.com/dotCMS/core)
2.  创建特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) )
3.  提交更改( E)`git commit -m 'Add some amazing feature'`(中文(简体) )
4.  推向分行(`git push origin feature/amazing-feature`(中文(简体) )
5.  打开拉请求

请确保您的代码遵循现有的样式并包含适当的测试 .

## 更改日志

### \[1.3.0\]

#### QQ 添加 - AI 搜索类型( 实验)

> **实验:** AI搜索类型是实验性的,在未来的发布中可能会有突破性的变化.

**新建 AI 搜索类型 :**

-   `DotCMSAISearchParams` - 完成AI搜索参数,包括查询和AI配置
-   `DotCMSAISearchQuery` - 查询参数(限制、偏移、内容Type等)
-   `DotCMSAIConfig` - AI配置(门槛、距离、功能、反应)
-   `DotCMSAISearchResponse<T>` - AI搜索API响应结构
-   `DotCMSAISearchContentletData<T>` - 与AI相匹配的信息内容
-   `DotCMSAISearchMatch` - 个人与距离比分匹配并提取出文本
-   `DotErrorAISearch` - AI 搜索 API 特定错误,包括快捷、索引Name和参数上下文
-   `DISTANCE_FUNCTIONS` - 矢量相似性的现有相距函数(黄素、L2、内出物等)

### \[1.1.1\]

#### 已添加

-   `DotHttpClient` 用于自定义 HTTP 客户端执行的接口
-   `BaseHttpClient` 带有内置错误处理工具的抽象类
-   `DotHttpError` 标准化 HTTP 错误处理的类别
-   `DotErrorPage` 带有 GraphQL 查询上下文的页面特定错误分类
-   `DotErrorContent` 包含操作细节的 API 错误分类
-   `DotErrorNavigation` 用于导航特定错误处理的类
-   `DotGraphQLApiResponse` 图QL API 响应的界面
-   `HttpErrorDetails` hTTP 错误标准化接口
-   所有错误类别包括 `toJSON()` 方便记录和序列化的方法

#### 已更改

-   已重命名 `RequestOptions` 改为 `DotRequestOptions` 为更好的命名一致性
-   已重命名 `DotCMSGraphQLPageResponse` 改为 `DotGraphQLApiResponse` 说明
-   增强 `DotCMSClientConfig` 用于支持自定义 `httpClient` 执行情况

## 许可证发放

点CMS 可在 [业务来源许可证1.1(BSL)](https://www.dotcms.com/bsl) 或商业执照.

在BSL下,DotCMS可以免费由个人开发商,小企业或机构在总资金中低于5M美元,也可以由非生产环境下的更大型组织使用. BSL每次发布都会在其发布后四年自动转换为GPL v3. 全文和问题,访问 [dotcms.com/bsl (英语)](https://www.dotcms.com/bsl) 财务报告和审定财务报表 [dotcms.com/bsl-faq (英语)](https://www.dotcms.com/bsl-faq)。 。 。 .

大型组织的生产用途,以及管理下的云、服务级协议、支助和企业能力,均根据点集管理系统的商业许可证提供。 关于商业计划、特点和支助选项的详情,见 [dotcms.com/定价](https://www.dotcms.com/pricing)。 。 。 .

## 常见问题

### @dotcms/types 是什么？

这个 @dotcms/types 软件包中包含用于dotCMS生态系统的TypeScript类型定义\. 在与dotCMS API和结构化内容合作时,利用它实现类型安全并增强开发者的经验\.

### 如何安装 @dotcms/types？

在项目目录运行 npm install @dotcms/types，或使用 pnpm add / yarn add / bun add。

### @dotcms/types 支持 TypeScript 吗？

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

### @dotcms/types 支持 ESM 还是 CommonJS？

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

### @dotcms/types 可以商用吗？

@dotcms/types 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @dotcms/types 的下载量有多少？

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

### @dotcms/types 还在维护吗？

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