dotCMS 类型库

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

📦 @ dotcms/ npm 上的类型 🛠️ 在 GitHub 上查看来源

目录

• 概览
• 安装
• 我该用哪个SDK版本?
• 常用类型
• 类型等级( 合并到定义)
  • AI 搜索
  • dotCMS 内容和页面
  • 通用视觉编辑器( UVE)
  • 块编辑器
  • 客户端 & HTTP
  • 处理错误
• 用法实例
  • 类型检查出错
• 支助
• 捐款
• 许可证发放
• 更改日志

概览

何时使用

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

主要惠益

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

安装

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

我该用哪个SDK版本?

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

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

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

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

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

在LTS发布? LTS发行版目前没有获得自己匹配的SDK版本. 在解决之前,请使用所出版的SDK版本,以便最接近定期发布 或者在你的LTS版本之前.

想要更多关于dotCMS发布和支持窗口如何工作的背景吗? 见 发布和支持生命周期( S)。 。 。 .

常用类型

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

类型等级( 合并到定义)

AI 搜索

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

AI 搜索参数:

AI 搜索回复 :

AI 搜索错误 :

dotCMS 内容和页面

页: 1

内容 :

站点布局( B) :

导航 :

通用视觉编辑器( UVE)

编辑器状态 :

编辑器事件 :

内置编辑 :

块编辑器

客户端 & HTTP

HTTP 客户端 :

客户端配置 :

处理错误

基准出错类型 :

域- 特定错误 :

用法实例

类型检查出错

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/ 客户端 软件包文档.

支助

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

• GitHub 问题: 对于错误报告和特性请求,请 打开一个问题 在 GitHub 仓库中
• 社区论坛: 加入我们 社区讨论 问问题和分享解决方案
• 叠叠流:使用标签 dotcms-types 张贴问题时
• 企业支助:企业客户可通过 dotCMS 支持门户

在报告问题时,请包括:

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

捐款

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

1. 叉子存储器 点/核心
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) 或商业执照.

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

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