# @bloomreach/spa-sdk 中文文档

规范地址：https://npmcn.com/package/%40bloomreach/spa-sdk/

版本：28\.2\.0
npm 元数据更新时间：2026-11-02T10:59:48.519Z
中文译文更新时间：2026-11-08T07:55:11.237Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bloomreach/spa-sdk
原文对照：https://npmcn.com/package/%40bloomreach/spa-sdk/?lang=original
项目主页：https://www.bloomreach.com/
源码仓库：https://github.com/bloomreach/spa-sdk

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

- 包体积（解压后）：406 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：5 个
- 首次发布：2019-11-25T15:25:10.720Z
- 最新版本发布：2026-11-02T10:59:48.340Z
- 近 30 天下载量：46198（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：110（近 12 个月 13 个）

## 中文简介

Bloomreach SPA SDK 软件

## 安装

```sh
npm install @bloomreach/spa-sdk
```

也可以使用：`pnpm add @bloomreach/spa-sdk`、`yarn add @bloomreach/spa-sdk`、`bun add @bloomreach/spa-sdk`

## README

# Bloomreach SPA SDK 软件

Bloomreach SPA SDK 提供简化的无头集成 与 [Bloomreach 内容](https://www.bloomreach.com/en/products/content) 用于基于 JavaScript 的应用程序。 此库与 页:1 [页面模型 API](https://documentation.bloomreach.com/library/concepts/page-model-api/introduction.html) 并曝光页面模型上的简化和框架不可知界面.

## 特征

-   页面模型 API 客户端
-   Page 模式 Javascript 执行
-   URL 生成器
-   与 Bloomreach 体验管理器集成预览

## 开始

### 安装

让SDK进入你的项目 [国家预防机制](https://docs.npmjs.com/cli/npm)数字 :

```bash
npm install @bloomreach/spa-sdk
```

还有 [雅伦](https://yarnpkg.com/)数字 :

```bash
yarn add @bloomreach/spa-sdk
```

### 使用量

以下代码片段请求相关页面模式并显示该页面的标题.

```javascript
import axios from "axios";
import { initialize } from "@bloomreach/spa-sdk";

async function showPage(path) {
  const page = await initialize({
    // The path to request from the Page Model API, should include query
    // parameters if those are present in the url
    path,
    // The location of the Page Model API of the brX channel
    endpoint: "http://localhost:8080/delivery/site/v1/channels/brxsaas/pages",
    // The httpClient used to make requests
    httpClient: axios,
  });

  document.querySelector("#title").innerText = page.getTitle();
}

showPage(`${window.location.pathname}${window.location.search}`);
```

或者,使用当地人 `fetch` API(由于 `fetch` 无法直接兼容 `HttpClient` 签名 :

```javascript
import { initialize } from "@bloomreach/spa-sdk";

const httpClient = async ({ method, url, headers, data }) => {
  const response = await fetch(url, {
    method,
    headers: headers,
    body: data !== undefined ? JSON.stringify(data) : undefined,
  });
  return { data: await response.json() };
};

async function showPage(path) {
  const page = await initialize({
    path,
    endpoint: "http://localhost:8080/delivery/site/v1/channels/brxsaas/pages",
    httpClient,
  });

  document.querySelector("#title").innerText = page.getTitle();
}

showPage(`${window.location.pathname}${window.location.search}`);
```

### 相关性 整合

(不适用于 SaaS 内容)

SDK提供基础 [快递 中间软件](https://expressjs.com/en/guide/using-middleware.html) 用于无缝 融合 与 [相关性模块](https://documentation.bloomreach.com/14/library/enterprise/enterprise-features/targeting/targeting.html)。 。 。 .

```javascript
import express from "express";
import { relevance } from "@bloomreach/spa-sdk/dist/express";

const app = express();

app.use(relevance);
```

中间软件可以使用 `withOptions` 方法.

```javascript
app.use(relevance.withOptions({ name: "_visitor", maxAge: 24 * 60 * 60 }));
```

### 安全渲染 HTML 内容

为了安全起见,您应该/必须将页面模型中返回的HTML内容进行消毒。 撤走之前 消毒方法,我们使用 [`sanitize-html`](https://www.npmjs.com/package/sanitize-html) 用于此目的的 SDK 软件包。 你现在可以用你喜欢的 根据您的项目要求进行消毒的图书馆或技术。 确保保存 `data-type` 属性 当SDK确定哪些链接是外部链接和哪些链接是外部链接时,在丰富的内容字段中的链接 使用时的内部 [`rewriteLinks`](https://bloomreach.github.io/spa-sdk/interfaces/index.Page.html#rewriteLinks) 方法.

例如,在反应的例子中,您可以将来自后端的 HTML 内容像 实例如下:

```tsx
import sanitize from 'sanitize-html';
  
function sanitizeRichContent(content: string): string {
  return sanitize(content, {
    allowedAttributes: {
      a: ['href', 'name', 'target', 'title', 'data-type', 'rel'],
      img: ['src', 'srcset', 'alt', 'title', 'width', 'height', 'loading'],
    },
    allowedTags: sanitizeHTML.defaults.allowedTags.concat(['img']),
  });
}
/* ... */

/* Suppose the content.value below contains HTML markups string. */
<div>
   {content && <div dangerouslySetInnerHTML={{ __html: page.rewriteLinks(sanitizeRichContent(content.value)) }} />}
</div>
```

同一原则可适用于其他框架。 例如, `v-html` 在 Vue.js 中或 `[innerHTML]` 在角质.

## 没有 SDK 实例的页面的持续预览数据

如果您在某些页面上选择性地使用 SPA SDK, 您需要坚持预览相关数据 浏览有和没有SDK实例的页面. 实现这一结果的最简单方法是 如下文所示,使用饼干储存.

代码的以下片段显示了构建配置对象到 传入 `initialize` 从 SPA SDK 函数或直接到 a `BrPage` 组件. 它从查询字符串中读取预览数据并将其保存到 cookie, 如果无法在 查询字符串。 用来管理饼干 `cookie` 图书馆或任何其他图书馆.

### 重要说明

-   预览站点应该与现场站点相比在单独的域上服务,以避免保存预览相关内容 现场的饼干.
-   如果在预览中加载的首页不使用 SPA SDK, 您应该解析查询参数和 将预览相关数据保存到 cookie 中.

这是一个通用的例子,你应该根据你的具体框架进行调整.

```typescript
import axios from 'axios';
import cookie from 'cookie';
import { Configuration } from '@bloomreach/spa-sdk';

export default function buildConfiguration(): Configuration {
  const PREVIEW_TOKEN_KEY = 'token';
  const PREVIEW_SERVER_ID_KEY = 'server-id';
  // Read a token and server id from the query string
  const searchParams = new URLSearchParams(window.location.search);
  const queryToken = searchParams.get(PREVIEW_TOKEN_KEY);
  const queryServerId = searchParams.get(PREVIEW_SERVER_ID_KEY);

  const cookies = cookie.parse(document.cookie);

  // Prioritize values from the query string because cookies might be outdated.
  const authorizationToken = queryToken ?? cookies[PREVIEW_TOKEN_KEY];
  const serverId = queryServerId ?? cookies[PREVIEW_SERVER_ID_KEY];

  // Save the values from the query string to have ability to restore them when switch back from legacy page to the SPA-SDK rendered page.
  if (queryToken) {
    document.cookie = cookie.serialize(PREVIEW_TOKEN_KEY, queryToken);
  }

  if (queryServerId) {
    document.cookie = cookie.serialize(PREVIEW_SERVER_ID_KEY, queryServerId);
  }

  const configuration = {
    endpoint: 'your-pda-endpoint',
    httpClient: axios,
    path: `${location.pathname}${location.search}`,
    // Provide authorization token and server id if they exist to the SPA-SDK initialization method.
    ...(authorizationToken ? { authorizationToken } : {}),
    ...(serverId ? { serverId } : {}),
  };

  return configuration;
};

```

或者,使用当地人 `fetch` API : (英语)

```typescript
import cookie from 'cookie';
import { Configuration, HttpClient } from '@bloomreach/spa-sdk';

const httpClient: HttpClient<any> = async ({ method, url, headers, data }) => {
  const response = await fetch(url, {
    method,
    headers: headers as Record<string, string>,
    body: data !== undefined ? JSON.stringify(data) : undefined,
  });
  return { data: await response.json() };
};

export default function buildConfiguration(): Configuration {
  const PREVIEW_TOKEN_KEY = 'token';
  const PREVIEW_SERVER_ID_KEY = 'server-id';
  const searchParams = new URLSearchParams(window.location.search);
  const queryToken = searchParams.get(PREVIEW_TOKEN_KEY);
  const queryServerId = searchParams.get(PREVIEW_SERVER_ID_KEY);

  const cookies = cookie.parse(document.cookie);

  const authorizationToken = queryToken ?? cookies[PREVIEW_TOKEN_KEY];
  const serverId = queryServerId ?? cookies[PREVIEW_SERVER_ID_KEY];

  if (queryToken) {
    document.cookie = cookie.serialize(PREVIEW_TOKEN_KEY, queryToken);
  }

  if (queryServerId) {
    document.cookie = cookie.serialize(PREVIEW_SERVER_ID_KEY, queryServerId);
  }

  const configuration = {
    endpoint: 'your-pda-endpoint',
    httpClient,
    path: `${location.pathname}${location.search}`,
    ...(authorizationToken ? { authorizationToken } : {}),
    ...(serverId ? { serverId } : {}),
  };

  return configuration;
};
```

## 许可证

原载 [Apache 2.0 (英语)](https://www.apache.org/licenses/LICENSE-2.0) 执照.

## 参考文献

用于 SPA SDK 的 Typedoc 自动生成并发布 改为 [https://bloomreach.github.io/spa-sdk/modules/index.html 页面存档备份,存于互联网档案馆](https://bloomreach.github.io/spa-sdk/modules/index.html)

## 常见问题

### @bloomreach/spa-sdk 是什么？

Bloomreach SPA SDK 软件

### 如何安装 @bloomreach/spa-sdk？

在项目目录运行 npm install @bloomreach/spa-sdk，或使用 pnpm add / yarn add / bun add。

### @bloomreach/spa-sdk 支持 TypeScript 吗？

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

### @bloomreach/spa-sdk 支持 ESM 还是 CommonJS？

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

### @bloomreach/spa-sdk 需要什么版本的 Node\.js？

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

### @bloomreach/spa-sdk 可以商用吗？

@bloomreach/spa-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bloomreach/spa-sdk 的下载量有多少？

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

### @bloomreach/spa-sdk 还在维护吗？

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