# @bettercms-ai/sdk 中文文档 规范地址：https://npmcn.com/package/%40bettercms-ai/sdk/ 版本：1\.42\.1 npm 元数据更新时间：2026-11-03T09:18:19.740Z 中文译文更新时间：2026-11-08T00:18:09.294Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bettercms-ai/sdk 原文对照：https://npmcn.com/package/%40bettercms-ai/sdk/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.4 MB，56 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：2 个 - 首次发布：2026-06-30T11:07:58.439Z - 最新版本发布：2026-11-03T09:18:19.498Z - 近 30 天下载量：4994（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：51（近 12 个月 51 个） ## 中文简介 为BetterCMS交付API所打入的JavaScript/TypeScript客户端. ## 安装 ```sh npm install @bettercms-ai/sdk ``` 也可以使用：`pnpm add @bettercms-ai/sdk`、`yarn add @bettercms-ai/sdk`、`bun add @bettercms-ai/sdk` ## README # @ bettercms-ai/ sdk (英语) 为BetterCMS交付API所打入的JavaScript/TypeScript客户端. ## 安装 ```bash npm install @bettercms-ai/sdk # or pnpm add @bettercms-ai/sdk # or yarn add @bettercms-ai/sdk ``` ## 快开始 ```ts import { BetterCMS } from "@bettercms-ai/sdk"; const client = BetterCMS.site({ workspace: "my-workspace" }); // Fetch a single page const page = await client.getContent("home"); console.log(page.entry.title); // List pages (paginated) const result = await client.listContent({ page: 1, perPage: 20 }); console.log(result.items); console.log(`Next page? ${result.hasNextPage}`); // Iterate all pages automatically for await (const item of client.listContentAll()) { console.log(item.entry.title); } // Collect with a limit const top = await client.listContentAll().all({ limit: 500 }); ``` ## 带有 API 密钥 ```ts const client = BetterCMS.site({ workspace: "my-workspace", apiKey: process.env.BETTERCMS_API_KEY, }); ``` ## 类型脚本 这个包被用TypeScript来写出,并用自有的种类声明来写出. 无单独的 `@types/` 需要软件包。 所有类型来自 `@bettercms-ai/types` 被再出口. ## 处理错误 SDK抛出 `BetterCMSError` 关于失败。 每个错误都有语义 `code`数字 : ```ts import { BetterCMSError, ErrorCodes } from "@bettercms-ai/sdk"; try { const page = await client.getContent("does-not-exist"); } catch (err) { if (err instanceof BetterCMSError) { switch (err.code) { case ErrorCodes.CONTENT_NOT_FOUND: // 404 break; case ErrorCodes.UNAUTHORIZED: // 401 break; case ErrorCodes.FORBIDDEN: // 403 break; case ErrorCodes.RATE_LIMITED: // 429 break; case ErrorCodes.INTERNAL_ERROR: // 5xx break; case ErrorCodes.NETWORK_ERROR: // Network failure break; } } } ``` ## 预览和视觉编辑草稿 一个客户端创建于 `perspective: "drafts"` 读取未公布的内容——通过 `content:read:draft` API 密钥, 或者通过 a `previewToken` 为一份文件做了薄荷. 草案还载有 **stega 出处**: 附加到每个字的无形零宽字符 出道值,命名出道的入道和出道场. 这就是让仪表板的画布 (和 `` 覆盖) 映射一个已渲染的字符串返回到它的编辑器,而不猜测 它的文本。 没错 **默认值 `perspective: "drafts"` 从1.15.0开始** 在此之前,它不得不 请求,并预览一个未知要询问已变无名字符串的构建. ```ts const draft = createClient({ apiUrl, workspace: "my-workspace", apiKey: process.env.BETTERCMS_DRAFT_KEY, perspective: "drafts", // stega is on }); // Opt out — e.g. when diffing or checksumming draft content, where the invisible // characters would show up as differences. const plain = createClient({ apiUrl, workspace: "my-workspace", apiKey: process.env.BETTERCMS_DRAFT_KEY, perspective: "drafts", stega: false, }); ``` 出版的书从不携带出处,不管什么 `stega` 设定为:有效载荷不能达到 生产建设。 自己脱去 `stripStega(value)` 如果你需要干净的绳子,和 解码为 `decodeStega(value)`。 。 。 . ## 丰富文本 一个丰富的字段到达 `{ format, value, html }` (或作赤弦相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相相相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 从文本切换). 渲染器 `html` 与 `rich()`,或使结构(`value`)你自己: ```ts import { rich, plain, portableText, embeds, resolved } from "@bettercms-ai/sdk"; const entry = await client.getEntry<{ body: RichTextValue }>("launch"); rich(entry.data.body); // HTML for set:html / dangerouslySetInnerHTML: everything drawn plain(entry.data.body); // text for , meta description, alt // Rendering the structure with @bettercms-ai/ui (or your own components): <PortableText value={portableText(entry.data.body) ?? entry.data.body} embeds={embeds(entry.data.body) ?? undefined} resolved={resolved(entry.data.body, entry) ?? undefined} />; ``` 相关帖子和作者的生平由服务器从公布的回复中解决 条目,并且从未存储。 信封价值包含其决心的内容(`value.resolved`页:1 以空块阵列存储的正体不能, 因此条目附带合并的地图 `data` (单位:千美元)`entry.resolved`) (中文(简体) ). `resolved(value, entry)` 返回该值自己的地图,否则则返回条目的地图. ## API 密码 ### `BetterCMS.site(options)` | 选项 | 类型 | 需求 | 默认 | | --- | --- | --- | --- | | `workspace` | `string` | 对 | —— 说 | | `apiKey` | `string` | 没有 | —— 说 | | `baseUrl` | `string` | 没有 | `https://api.bettercms.ai/api/v1/delivery` | 回返a `BetterCMSDeliveryClient` 举个例子. ### `client.getContent(slug)` 以 sattle 获取单个已出版的页面 . ```ts const content = await client.getContent("about-us"); ``` ### `client.listContent(options?)` 返回一个相加结果对象. ```ts const result = await client.listContent({ page: 1, perPage: 20 }); // result.items, result.hasNextPage, result.totalPages, ... ``` ### `client.listContentAll(options?)` 返回一个透明地遵循平面标记的同步指示器. ```ts for await (const item of client.listContentAll()) { ... } // With a limit: const items = await client.listContentAll().all({ limit: 100 }); ``` ## 常见问题 ### @bettercms-ai/sdk 是什么？ 为BetterCMS交付API所打入的JavaScript/TypeScript客户端\. ### 如何安装 @bettercms-ai/sdk？ 在项目目录运行 npm install @bettercms-ai/sdk，或使用 pnpm add / yarn add / bun add。 ### @bettercms-ai/sdk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @bettercms-ai/sdk 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @bettercms-ai/sdk 可以商用吗？ @bettercms-ai/sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @bettercms-ai/sdk 的下载量有多少？ 根据 npm 官方下载统计，@bettercms-ai/sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,994 次，日均约 166 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bettercms-ai/sdk 还在维护吗？ 最新版本 1\.42\.1 发布于 2026/11/03（5 天前）；至今共发布 51 个版本，其中过去 12 个月发布了 51 个；首次发布于 2026/06/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。