# @bloomreach/vue-sdk 中文文档

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

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

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

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

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

- 包体积（解压后）：131 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vue ^3\.2\.45
- 首次发布：2020-06-05T14:21:24.652Z
- 最新版本发布：2026-11-02T10:58:43.408Z
- 近 30 天下载量：5154（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 14 个）

## 中文简介

Bloomreach SPA SDK 用于 Vue

## 安装

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

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

## README

# Bloomreach Vue SDK 软件

Bloomreach Vue SDK 提供了简化的无头集成 [Bloomreach 内容](https://www.bloomreach.com/en/products/content) 用于基于 Vue 的应用程序。 此库与 [页面模型 API](https://documentation.bloomreach.com/api-reference/content/delivery/page-delivery-api/page-delivery-api.html) 财务报告和审定财务报表 [Bloomreach SPA SDK 软件](https://www.npmjs.com/package/@bloomreach/spa-sdk) 财务报告和审定财务报表 在Page Model上曝光了简化的Vue.js接口.

## 先决条件

要使用Vue SDK,需要安装Vue 3.

## 特征

-   Bloomreach Page Vue 组件;
-   Bloomreach 组件 Vue 组件;
-   管理内容按钮;
-   管理菜单按钮;

## 开始

### 安装

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

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

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

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

### 使用量

以下代码片段使一个简单的页面带有 [横幅](https://documentation.bloomreach.com/library/setup/hst-components/overview.html) 组件.

#### `src/main.ts`

在应用程序的条目文件中,它需要导入和 [安装](https://vuejs.org/guide/reusability/plugins.html) 页:1 `BrSdk` 使 SDK 组件在全球开放的插件 .

```typescript
import { createApp } from 'vue'
import { BrSdk } from '@bloomreach/vue-sdk';

const app = createApp(/*... */);
app.use(BrSdk);

/*... */
```

#### `src/App.vue`

在那个 `App` 组件,它需要通过配置和 Bloomreach 内容组件 绘制 `br-page` 构成部分投入.

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping">
    <template v-slot="props">
      <header>
        <a :href="props.page.getUrl('/')">Home</a>
        <br-component component="menu" />
      </header>
      <section>
        <br-component component="main" />
      </section>
      <footer>
        <br-component component="footer" />
      </footer>
    </template>
  </br-page>
</template>

<script lang="ts" setup>
  import Banner from './components/Banner.vue';
  
  const configuration = {
    /* ... */
  };
  const mapping = { Banner };
</script>
```

#### `src/components/Banner.vue`

最后,在 `Banner` 组件,它可以通过 `component` 道具 (英语).

```html
<template>
  <div>Banner: {{ component.getName() }}</div>
</template>

<script lang="ts" setup>
  import { toRefs } from 'vue';
  
  const props = defineProps<{ component: Component }>();
  const { component } = toRefs(props);
</script>
```

### 非阻塞渲染模式( NBRMODE)

非屏蔽渲染模式可用于减少应用程序在客户端完全加载的时间. 以 默认 NBRMODE 配置为 `false` 以避免打破现有设置。 设为 `true` 将启用 非阻塞渲染模式。 当模式激活时, BrPage 组件的子将开始安装, 同时 正在获取页面模型 。 这些孩子可能包含逻辑本身,可以查询一些外部API并使用 非屏蔽渲染模式将允许在请求页面模型的同时执行.

```html
<!-- MyComponent.vue -->
<template>
  Hello
</template>

<script lang="ts" setup>
  import { onMounted } from 'vue';
  
  onMounted(async () => {
    // This will run in parallel to fetching the Page Model from the Delivery API
    await fetch('https://yourapi.com');
  });
</script>
```

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping">
    <my-component></my-component>
    <template v-slot:default="props">
      ...
  </br-page>
</template>

<script lang="ts" setup>
  const configuration = {
    NBRMode: true,
    /* ... */
  };
  const mapping = {/* ... */};
</script>
```

### 重要使用说明

#### 每页/路特单页

**只用一个 `br-page` 每个页面或路由的组件.** 这个 `br-page` 组成部分旨在:

-   从 Page 模型 API 获取特定路径的页面模型
-   为内容更新设置 CMS 预览听众
-   为所有子组件提供页面上下文
-   管理完整页面状态

使用多个 `br-page` 同页上的组件将引发冲突,不支持。 如果您需要制作不同的页面段落, 请使用 `br-component` 单人之内 `br-page` 换句话说.

### 配置

这个 `br-page` 组件支持您可用于自定义页面的多个选项 初始化。 这些选项将转交给 `initialize` 函数从 [`@bloomreach/spa-sdk`](https://www.npmjs.com/package/@bloomreach/spa-sdk)。见 [这里](https://bloomreach.github.io/spa-sdk/modules/index.html#Configuration) 联 合 国 sPA SDK Typedocs中的完整配置文档.

### 绘图

这个 `br-page` 组件提供了一个将 Vue 组件与 Bloomreach 内容链接的方法 这些。 它需要通过 `mapping` 属性,用于映射组件类型 及其代表.

这个 [集装箱物品](https://bloomreach.github.io/spa-sdk/interfaces/index.ContainerItem.html) 可能会是 他们的标签.

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping" />
</template>

<script lang="ts" setup>
  import NewsList from './components/NewsList.vue';
  
  const configuration = {
    /* ... */
  };
  const mapping = { 'News List': NewsList };
</script>
```

这个 [集装箱](https://bloomreach.github.io/spa-sdk/interfaces/index.ContainerItem.html) 只能用他们的 [类型](https://documentation.bloomreach.com/library/concepts/template-composer/channel-editor-containers.html), (中文(简体) ), 因此,你需要使用 [常数](https://bloomreach.github.io/spa-sdk/modules/index.html#TYPE_CONTAINER_BOX) 从 [`@bloomreach/spa-sdk`](https://npmcn.com/package/%40bloomreach/vue-sdk/www.npmjs.com/package/@bloomreach/spa-sdk)默认情况下, vue SDK 提供了所有集装箱类型的实施 定义 [文档](https://documentation.bloomreach.com/library/concepts/template-composer/channel-editor-containers.html)。 。 。 .

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping" />
</template>

<script lang="ts" setup>
  import { TYPE_CONTAINER_INLINE } from '@bloomreach/spa-sdk';
  import InlineContainer from './components/InlineContainer.vue';
  
  const configuration = {
    /* ... */
  };
  const mapping = { [TYPE_CONTAINER_INLINE]: InlineContainer };
</script>
```

在集装箱部分内,集装箱物品可通过 `getChildren` 方法。 这可用于重排或包装子元素.

```html
<template>
  <div>
    <span v-for="(child, key) in component.getChildren()" :key="key">
      <br-component :component="child" />
    </span>
  </div>
</template>

<script lang="ts" setup>
  import { toRefs } from 'vue';
  
  const props = defineProps<{ component: Component }>();
  const { component } = toRefs(props);
</script>
```

这个 [构成部分](https://bloomreach.github.io/spa-sdk/interfaces/index.Component.html) 可以用他们的名字绘制地图。 对菜单组件映射很有用.

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping" />
</template>

<script lang="ts" setup>
  import Menu from './components/Menu.vue';

  const configuration = {
    /* ... */
  };
  const mapping = { menu: Menu };
</script>
```

默认情况下,未绘制地图的集装箱项目将用作警告 语句。 有一种选择可以推翻倒计时.

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping" />
</template>

<script lang="ts" setup>
  import { TYPE_CONTAINER_ITEM_UNDEFINED } from '@bloomreach/spa-sdk';
  import Fallback from './components/Fallback.vue';

  const configuration = {
    /* ... */
  };
  const mapping = { [TYPE_CONTAINER_ITEM_UNDEFINED]: Fallback };
</script>
```

### 内置映射

还有另一种方式可以构成一个组成部分。 如果你需要显示 静态组件或抽象页面中的组件,可以使用内线 组件映射.

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping">
    <template>
      <br-component component="menu">
        <template v-slot:default="{ component, page }">
          <Menu :component="component" :page="page" />
        </template>
      </br-component>
    </template>
  </br-page>
</template>

<script>
  import Menu from './components/Menu.vue';
  
  const configuration = {
    /* ... */
  };
  const mapping = {
    /* ... */
  };
</script>
```

在一个组成部分中,也可以指出该组成部分的儿童在哪里 将会被安置.

```html

<template>
  <div>
    @copy; Bloomreach
    <br-component/>
  </div>
</template>

<script lang="ts" setup>
  import { Component } from '@bloomreach/spa-sdk';
  import { toRefs } from 'vue';
  
  const props = defineProps < { component: Component } > ();
  const { component } = toRefs(props);
</script>
```

内部映射的组件数据可通过模板访问 上下文.

```html
<template>
  <br-page :configuration="configuration" :mapping="mapping">
    <template>
      <br-component component="menu">
        <template v-slot:default="{ component, page }">
          <ul>
            <li><a :href="page.getUrl('/')">Home</a></li>
            <li v-for="(item, key) in component.getModels()" :key="key">...</li>
          </ul>
        </template>
      </br-component>
    </template>
  </br-page>
</template>

<script lang="ts" setup>
  const configuration = {
    /* ... */
  };
  const mapping = {
    /* ... */
  };
</script>
```

### 按钮

建议添加 Css 风格 `position: relative` 切入按钮 因此,他们将正确定位在母容器组件内.

管理菜单按钮可使用 `br-manage-menu-button` 组件.

```html
<template>
  <ul v-if="menu" :class="{ 'has-edit-button': page.isPreview() }">
    <!-- ... -->

    <br-manage-menu-button :menu="menu" />
  </ul>
</template>

<script lang="ts" setup>
  import { toRefs, computed } from 'vue';
  import { Menu, Reference, Component, Page } from '@bloomreach/spa-sdk';

  interface MenuModels {
    menu: Reference;
  }
  
  const props = defineProps<{ component: Component; page: Page }>();
  const { component, page } = toRefs(props);
  const menu = computed(() => {
    const { menu: menuRef } = component.value.getModels<MenuModels>();
    return menuRef && page.value.getContent<Menu>(menuRef);
  });
</script>
```

管理内容按钮可使用 `br-manage-content-button` 非空组件 `content` 属性.

```html
<template>
  <div v-if="document" :class="{ 'has-edit-button': page.isPreview() }">
    <!-- ... -->

    <br-manage-content-button
      :content="document"
      document-template-query="new-banner-document"
      folder-template-query="new-banner-folder"
      parameter="document"
      root="banners"
      :relative="true"
    />
  </div>
</template>

<script>
  import { toRefs, computed } from 'vue';
  import { Document, Reference, Page, Component } from '@bloomreach/spa-sdk';

  interface BannerModels {
    document: Reference;
  }
  
  const props = defineProps<{ component: Component; page: Page }>();
  const { component, page } = toRefs(props);
  
  const document = computed(() => {
    const { document: documentRef } = component.value.getModels<BannerModels>();
    return documentRef && page.value.getContent<Document>(documentRef);
  });
</script>
```

添加新内容按钮可使用 `br-manage-content-button` 指令,但不传递内容实体.

```html
<template>
  <div :class="{ 'has-edit-button': page.isPreview() }">
    <!-- ... -->

    <br-manage-content-button
      document-template-query="new-news-document"
      folder-template-query="new-news-folder"
      root="news"
    />
  </div>
</template>

<script lang="ts" setup>
  import { Component, Page } from '@bloomreach/spa-sdk';
  
  const props = defineProps<{ component: Component, page: Page }>();
  const { component, page } = toRefs(props);
</script>
```

## 许可证

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

## 参考文献

Vue SDK 正在使用 [Bloomreach SPA SDK 软件](https://www.npmjs.com/package/@bloomreach/spa-sdk) 要交互 与 Bloomreach 内容.

### br 页面

这是页面模型的切入点 。 本构成部分要求和 初始化页面模型,然后使页面根组件 递相取取.

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `configuration` | _对_ | 这个 [配置](https://npmcn.com/package/%40bloomreach/vue-sdk/#readme-configuration) (原始内容存档于2015-03-30). SPA SDK. |
| `mapping` | _对_ | BrXM和Vue.js组件 [绘图](https://npmcn.com/package/%40bloomreach/vue-sdk/#readme-mapping)。 。 。 . |
| `page` | _没有_ | 已初始化的页面实例或被预选的页面模式 。 大部分应该用于将状态从服务器端转移到客户端端端. |

此组件还支持默认插槽转录. `<template>` 从 组件内容将在根组件上下文中提供.

| 变量 | 说明 |
| --- | :-: |
| `component` | 根分分分相为. |
| `page` | 当前页面实例 . |

### b 组件

本部分指出儿童或某些部分应放在何处. `br-component` 可在内部使用 `br-page` 或只绘制组件。 如果是 包含 `<template>` 在内容中,然后模板将在 上下文。 否则,它将试图使所有 儿童成分递归.

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `component` | _没有_ | 组件实例或通往组件的路径。 路径被定义为相对于当前组件(例如. `main/container`) (中文(简体) ). 如果它被省略,所有的孩子将被释放. |

模板上下文包含当前组件和当前 页面实例.

| 变量 | 说明 |
| --- | :-: |
| `component` | 现成部分. |
| `page` | 当前页面实例 . |

### br- 管理内容- 按钮

此组件在打开链接内容的页面上设置按钮 文档编辑器或打开文档编辑器以创建新的编辑器。 按钮会 仅以预览模式显示.

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `content` | _没有_ | 要打开编辑的内容实体 . |
| `document-template-query` | _没有_ | 用于创建新文档的模板查询 。 对于Content SaaS来说,关键是 `new-banner-document` 页:1 `banner` 文档类型。 如果文档类型在名称空间之外 `brxsaas`,键中还包括命名空间前缀,例如 `new-vuestorefront-accordion-document` 页:1 `accordion` 文档类型 `vuestorefront` 名称空间. |
| `folder-template-query` | _没有_ | 在指定的大小写文件夹中使用的模板查询 `path` 尚不存在,必须建立。 对于Content SaaS来说,关键是 `new-banner-folder` 页:1 `banner` 文档类型。 如果文档类型在名称空间之外 `brxsaas`,键中还包括命名空间前缀,例如 `new-vuestorefront-accordion-folder` 页:1 `accordion` 文档类型 `vuestorefront` 名称空间. |
| `path` | _没有_ | 新文件的初始位置,相对于 `root`。 。 。 . |
| `parameter` | _没有_ | 存储文档路径的组件参数名称. |
| `pickerConfiguration` | _没有_ | 用于拾取器的 CMS 配置的根路径,相对于 `/hippo:configuration/hippo:frontend/cms`。 。 。 . |
| `pickerEnableUpload` | _没有_ | 当此拾取器用于图像时, 此旗会决定上传是否启用 . |
| `pickerInitialPath` | _没有_ | 相对于拾取器 RootPath, 如果还没有选择, 在拾取器中使用的初始路径 . |
| `pickerRemembersLastVisited` | _没有_ | 采取者是否记得上次访问过的路径 . |
| `pickerRootPath` | _没有_ | 采取器中使用的绝对根路径,或者如果使用频道内容路径,则使用空字符串. |
| `pickerSelectableNodeTypes` | _没有_ | 要在拾取器中选择的节点类型,用逗号分隔. |
| `relative` | _没有_ | 表示所选取的数值应作为相对路径存储的旗帜 . |
| `root` | _没有_ | 可选择文档位置的根文件夹路径 . |

### br- 管理- 菜单- 按钮

此指令在打开链接菜单的页面上设置按钮 菜单编辑器。 按钮仅以预览模式显示 .

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `menu` | _对_ | 相关的菜单模式. |

## 常见问题

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

Bloomreach SPA SDK 用于 Vue

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

在项目目录运行 npm install @bloomreach/vue-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.2\.45）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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