# @dani-builder/strapi-client 中文文档

规范地址：https://npmcn.com/package/%40dani-builder/strapi-client/

版本：2\.5\.0
npm 元数据更新时间：2026-11-10T11:34:46.904Z
中文译文更新时间：2026-11-11T10:09:33.271Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dani-builder/strapi-client
原文对照：https://npmcn.com/package/%40dani-builder/strapi-client/?lang=original
项目主页：https://github.com/HJ-company/daniworks-builder-v2/tree/main/packages/strapi-client#readme
源码仓库：https://github.com/HJ-company/daniworks-builder-v2

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

- 包体积（解压后）：267 kB，197 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13
- 运行依赖：3 个
- 首次发布：2026-02-11T10:18:28.138Z
- 最新版本发布：2026-11-10T11:34:46.723Z
- 近 30 天下载量：4873（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

Daniworks 构建器 CMS (Strapi v5) 的脚本客户端

## 安装

```sh
npm install @dani-builder/strapi-client
```

也可以使用：`pnpm add @dani-builder/strapi-client`、`yarn add @dani-builder/strapi-client`、`bun add @dani-builder/strapi-client`

## README

# @dani-builder/strapi-客户端

类型脚本客户端 [Daniworks 构建器](https://github.com/HJ-company/daniworks-builder-v2) CMS (Strapi v5) (英语). 手接型、人多型、安全型 函数用于每个内容类型——对 [`@dani-builder/strapi-plugin-builder`](https://www.npmjs.com/package/@dani-builder/strapi-plugin-builder)。 。 。 .

## 安装

```bash
pnpm add @dani-builder/strapi-client
```

现有的客户条目仅为无害环境管理(`"type": "module"`) (中文(简体) ). 只有服务器 `/preview` 条目支持无害环境管理和通用JS,没有Strapi运行时间或同行.

TypeScript 消费者需要 `moduleResolution: "bundler"`, (中文(简体) ), `"node16"`,或 `"nodenext"`; 遗产 `"node10"` 仅支持 `/preview` b. 通过下列方式发表声明: `typesVersions`。 。 。 .

## 使用量

每个 API 函数需要一个 `AxiosInstance` (无单通-SSR安全):

```ts
import { createStrapiClient } from "@dani-builder/strapi-client/client";
import { getPageBySlug, getGlobal } from "@dani-builder/strapi-client/api";

const strapi = createStrapiClient({
  baseUrl: process.env.STRAPI_URL,
  apiToken: process.env.STRAPI_TOKEN,
});

const page = await getPageBySlug(strapi, "about");
const global = await getGlobal(strapi);

// Editor preview: pass status: "draft" (authenticated requests only).
const draft = await getPageBySlug(strapi, "about", { status: "draft" });
```

页面列表/细节和Global端点使用固定的服务器侧插件. `getPageBySlug` 用读取的 Smart 列表解决 sult, 然后获取 Smart 细节 . 遗产 `listPagesRest` 财务报告和审定财务报表 `getGlobalRest` 发送弹出参数为 处理者忽略。 其他收藏使用有客户端填充功能的Builder Core REST.

## 站点设置和分析

`getSiteSettings` 自动填充分析设置。 用于自定义 REST 请求中,包括共享集成构建器:

```ts
import { getSiteSettingsPopulate } from "@dani-builder/strapi-client/populate";
import type {
  SiteSettingsDocument,
  StrapiResponse,
} from "@dani-builder/strapi-client/types";

const { data } = await strapi.get<StrapiResponse<SiteSettingsDocument>>(
  "/api/builder/site-setting",
  { params: { populate: getSiteSettingsPopulate() } },
);
const configs = data.data.analyticsSettings;
// Pass configs to AnalyticsProvider from @dani-builder/blocks/analytics.
```

## 分出口

| 导入 | 目录 |
| --- | --- |
| `@dani-builder/strapi-client/types` | 手加工内容类型( B) |
| `@dani-builder/strapi-client/client` | `createStrapiClient` |
| `@dani-builder/strapi-client/api` | 21 API 函数 |
| `@dani-builder/strapi-client/populate` | 9个填充器+ `coreBlockPopulates`, (中文(简体) ), `seoPopulate`, (中文(简体) ), `footerPopulate` |
| `@dani-builder/strapi-client/utils` | 媒体 URL, SIO, 校验, JSON- LD 和 FAQ 帮助器 |
| `@dani-builder/strapi-client/preview` | 只有节点.js服务器 `verifyPreviewToken`, (中文(简体) ), `isSafePreviewPath`, (中文(简体) ), `PREVIEW_TTL_SECONDS` |

见 [`docs/block-reference.md`](https://npmcn.com/package/%40dani-builder/strapi-client/docs/block-reference.md) 整块的图案.

## 许可证

麻省理工学院

预览验证需要客户端0.1.20. 仅在节点中导入 服务器代码和保存 `PREVIEW_SECRET` 私处. 共享核查人约束签名 路径和草稿/已公布的状态以及过期时的拒绝令牌(300秒). 现有插件 `/preview` 核查者仍然兼容.

## 代理浏览器客户端

`createAgentClient({ baseUrl, apiPrefix?, fetch? })` 从软件包中导出 树根。 它规定 `session()` 发行, `session(credentials)` 恢复, `history(credentials)`, (中文(简体) ), `chat(credentials, request, { onEvent? })` 财务报告和审定财务报表 `cancel(credentials, requestId)`。聊天手柄会暴露它的马厩 `requestId`, (中文(简体) ), `result` 承诺和 `cancel()` 马上 串流事件使用共享 `@dani-builder/agent-contract` par. 用会话ID保存已发行的代号 在呼叫者拥有的存储中,处理结果和取消。 键 仅以 Bearer 信头发送; cookie 省略。 现有轴线 API 仍在继续 独立工作.

见 [代理会话和对话背景](https://npmcn.com/package/docs/guides/agent-conversation-context.md) 用于浏览器使用、错误/取消行为、重试和CMS源许可列表.

## 小型和小型数据及结构化数据

这些帮助者返回简单数据,没有框架依赖性。 导入它们 从软件包根或 `/utils`; 调整结果以适应您的 框架的元数据或 HTML 渲染器.

```ts
import {
  resolveSeo,
  siteVerificationMeta,
  faqPageJsonLd,
  mergeStructuredData,
  serializeJsonLd,
} from "@dani-builder/strapi-client/utils";

const seo = resolveSeo(page.seo, {
  title: "About us",
  description: "Meet our team",
  url: "https://example.com/about",
  ogImageUrl: "https://example.com/default-og.png",
  mediaHost: "https://cms.example.com",
  indexingEnabled: true,
});
// seo: {
//   title, description?, canonical?, robots: { index, follow },
//   openGraph: { title, description?, url?, images: string[] },
//   twitter: { title, description?, url?, images: string[], card }
// }
const verification = siteVerificationMeta(siteSettings);
// [{ name: "google-site-verification", content: "configured token" }, ...]
const faq = faqPageJsonLd(faqs);
// { "@context": "https://schema.org", "@type": "FAQPage", mainEntity: [...] }
// or null when no usable question/answer pairs exist.
const { data, excluded } = mergeStructuredData(faq, page.seo?.structuredData);
const jsonLd = serializeJsonLd(data);
// Use jsonLd as the text of a script with type="application/ld+json".
// Inspect excluded for invalid CMS entries before publishing.
```

`resolveSeo` 更喜欢剪接、非空白的 CMS 标题和描述,然后调用 堕倒. 其CMS Canonical 必须是带有 主机名; 相对的、 协议相对的和错误的值返回到 `url`。 。 。 . 按规定使用调用默认值。 要启用索引默认值 。 全球 `indexingEnabled: false` 使两个机器人的旗帜都是假的; 否则 `noindex` 财务报告和审定财务报表 `nofollow` 独立禁用各自的旗帜。 CMS OG 媒体用途 `getMediaUrl(url, mediaHost)` 并回到 `ogImageUrl` 丢失或空白 媒体。 这两种社会产出都具有既定价值; Twitter的使用 `summary_large_image` 带有图像和 `summary` 没有一个。 可选元数据 字段在不存在倒计时被省略,然后图像数组为空.

`siteVerificationMeta` 接受无效设置 `siteVerifications`地图 进入谷歌 `google-site-verification`宾至 `msvalidate.01`导航 `naver-site-verification`,并自定义其已配置名称的服务。 它会修剪 名称/内容,省去空白内容、自定义名称和未知服务,并保存 配置顺序和重复标记 。 每个条目通过您的框架 正常属性退出.

`serializeJsonLd` 用途 `JSON.stringify`,然后逃离每一个 `<` 作为 `\u003c` 这样 包含 CMS 字符串 `</script>` 无法结束脚本元素。 结果 字符串解析回到相同的 JSON 值 。 它会扔 `TypeError` 用于顶级 未定义的函数、符号或值 `toJSON` 返回未定义。 土著 JSON错误用于循环引用和 BigInt 传播. 它将数据序列化; 它不会验证 Schema.org 词汇表或发出脚本标记.

`mergeStructuredData(auto, cms)` 接受单个对象或数组。 努尔/未定义 没有投入。 每个被接受的对象必须有一个非空白字符串 `@type` 或一个 非空数组非空字符串。 无效条目被省略并报告于 `excluded` 作为 `{ source: "auto" | "cms", index, reason }`;原因为 `"not-object"` 财务报告和审定财务报表 `"invalid-type"`,以零为基础的指数(单一指数为零) (注一) 自动录入建立秩序. CMS 条目中包含一个平等的 `@type` 替换现有对象;新类型附件。 重复类型使用 最后一个条目,包括自动重复。 类型数组精确匹配 排序独有的集 : `["Thing", "Product"]` 等于 `["Product", "Thing"]`不过 两者均等于 `"Product"`。单元素数组等于其字符串形式。 类型 值保留其原始拼写;仅白空值无效. 帮助者保存对象引用, 不变异, 深处, 扩展 `@graph`,或验证超出 `@type`。 。 。 .

`blocksToPlainText(blocks)` 从Strapi Blocks中提取文本并链接孩子, 将文字内化,将段落、标题、引文、代码和 列表中含有新行的项目。 它忽略图像,未知的节点类型和畸形 节点,并返回缺/非数组输入的空字符串。 外部结果 已经修剪. `faqPageJsonLd` 接受一组只读的问答记录, 用于解答、修剪问题并省去空白对。 结果 用途 `Question` 财务报告和审定财务报表 `Answer` 实体; 返回 `null` 这意味着不需要FAQ脚本.

## 机器人 . txt

站点设置可选 `robotsTxt` 语句。 保存接受 `User-agent`, (中文(简体) ), `Allow`, (中文(简体) ), `Disallow`, (中文(简体) ), `Sitemap`,以及 `Crawl-delay` 指令名称( 大小写不敏感), 遵循 加上注释和空白行。 无效行返回验证错误 有字段名称和原一行编号。 这是基本指令 语法验证;指令值和爬行者行为仍然是作者拥有的.

`resolveRobotsTxt(siteSetting, { indexingAllowed, siteUrl, defaultRules })` 实值 从根导出并 `/utils`。空的、空的或仅白空间的 CMS 文本使用消费者的 `defaultRules`在索引化后,它保留了 规则和附件 `Sitemap: <siteUrl>/sitemap.xml` 除非是活动、对大小写不敏感 `Sitemap` 指令已经存在 。 被从拖倒的鞭子取出 `siteUrl`· ; 备注的站点地图指令不算数。 与 `indexingAllowed: false`总是 准确返回 `User-agent: *\nDisallow: /`,没有网站地图.

从纯文本路径服务返回的字符串, 例如 Next.js at `app/robots.txt/route.ts`数字 :

```ts
import { getSiteSettings, resolveRobotsTxt } from "@dani-builder/strapi-client";
import { client } from "@/lib/strapi";
import { indexingAllowed, siteUrl } from "@/lib/site-config";

export async function GET() {
  const siteSetting = await getSiteSettings(client);
  const body = resolveRobotsTxt(siteSetting, {
    indexingAllowed,
    siteUrl,
    defaultRules: "User-agent: *\nAllow: /",
  });
  return new Response(body, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

消费者控制指数化政策,必须提供自己的客户和网站 配置 。 避免界定一个框架 `robots.ts` 相同 URL 的路由.

代理消费者需要 `@dani-builder/agent-contract >=1.0.0 <2`。 。 。 . 共享解析器忽略已删除 `inquiry_draft` 扩展框并过滤 保留有效兄弟姐妹。 使用消费者拥有的行动 和用于准备联系表的渲染器 [产出迁移指南](https://npmcn.com/package/docs/guides/agent-output-extensions.md#migration-from-inquiry-specific-agent-apis)。 。 。 .

## 常见问题

### @dani-builder/strapi-client 是什么？

Daniworks 构建器 CMS \(Strapi v5\) 的脚本客户端

### 如何安装 @dani-builder/strapi-client？

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

### @dani-builder/strapi-client 支持 TypeScript 吗？

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

### @dani-builder/strapi-client 支持 ESM 还是 CommonJS？

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

### @dani-builder/strapi-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dani-builder/strapi-client 可以商用吗？

@dani-builder/strapi-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dani-builder/strapi-client 的下载量有多少？

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

### @dani-builder/strapi-client 还在维护吗？

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