# @bloomreach/react-sdk 中文文档

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

版本：28\.2\.0
npm 元数据更新时间：2026-11-02T11:01:54.856Z
中文译文更新时间：2026-11-08T07:54:51.906Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：211 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^16\.14 \|\| ^17\.0 \|\| ^18\.0 \|\| ^19\.0
- 首次发布：2019-11-25T15:28:26.750Z
- 最新版本发布：2026-11-02T11:01:54.678Z
- 近 30 天下载量：21457（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：111（近 12 个月 13 个）

## 中文简介

Bloomreach SPA SDK 反应

## 安装

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

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

## README

# Bloomreach 反应 SDK

Bloomreach React SDK 提供了简化的无头集成 [Bloomreach 内容](https://www.bloomreach.com/en/products/content) 用于基于反应的应用程序。 此库与 [页面模型 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上暴露出简化的宣示反应界面.

## 特征

-   页面组件;
-   Bloomreach 组件;
-   管理内容按钮;
-   管理菜单按钮;
-   渲染道具模式支持;
-   [反应服务器组件](https://react.dev/reference/rsc/server-components) 支助;
-   [下一个.js](https://nextjs.org/) 应用路由器支持;
-   [反应路由器](https://reacttraining.com/react-router/) 财务报告和审定财务报表 [下一个路由](https://github.com/fridays/next-routes) 支助;
-   [原生反应](https://reactnative.dev/) 支助;
-   [酶](https://airbnb.io/enzyme/) 财务报告和审定财务报表 [欢乐](https://jestjs.io/) 支助.

## 开始

### 安装

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

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

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

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

### 使用量

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

```jsx
import React from 'react';
import axios from 'axios';
import { BrComponent, BrPage, BrProps } from '@bloomreach/react-sdk';

function Banner({ component, page, mapping }: BrProps) {
  return <div>Banner: {component.getName()}</div>;
}

export default function App() {
  const configuration = { /* ... */ };

  return (
    <BrPage configuration={configuration} mapping={{ Banner }}>
      {({ page, mapping, component }) => (
        <>
          <header>
            {page && <Link to={page.getUrl('/')}>Home</Link>}
            <BrComponent path="menu" page={page} mapping={mapping} component={component}>
              <Menu page={page} mapping={mapping} />
            </BrComponent>
          </header>
          <section>
            <BrComponent path="main" page={page} mapping={mapping} component={component} />
          </section>
          <BrComponent path="footer" page={page} mapping={mapping} component={component}>
            <footer>
              <BrComponent page={page} mapping={mapping} component={component} />
            </footer>
          </BrComponent>
        </>
      )}
    </BrPage>
  );
}
```

如果包含 BrPage 的组件重新提交以防止不必要的请求到 Page Model API 中,则对配置对象进行纪念.

```jsx
const location = useLocation();

const memoizedConfiguration = useMemo(() => {
  return buildConfiguration(`${location.pathname}${location.search}`, axios);
}, [location.pathname, location.search]);

<BrPage configuration={memoizedConfiguration} mapping={mapping}>
  ...
```

### 重要使用说明

#### 单页/轮廓

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

-   从 Page 模型 API 获取特定路径的页面模型
-   为内容更新设置 CMS 预览听众
-   通过渲染道具向所有儿童部件提供页面和绘图数据
-   管理完整页面状态

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

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

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

```jsx
const fetchData = async () => {
  const data = await fetch('https://yourapi.com');
}

function MyComponent() {
  useEffect(() => {
    // This will run in parallel to fetching the PageModel from the Delivery API
    fetchData().catch(console.error);
  }, []);
  
  return `<div>Hello</div>`
}

export default function App() {
  const configuration = {
    /* ... */
    NBRMode: true,
  };

  return (
    <BrPage configuration={configuration} mapping={{ ... }}>
      <MyComponent/>
    </BrPage>
  );
}
```

### React 服务器组件( RSC) 支持

支持编辑 [经验经理](https://xmdocumentation.bloomreach.com/library/end-user-manual/channel-manager/manage-page-components.html),该页面和组件必须使用反应钩在客户端动态地进行. 因此,默认 `BrPage` 财务报告和审定财务报表 `BrComponent` 两者均作为客户部分执行。 然而,这种限制并不适用于现场,使用服务器组件使您的反应应用完全安全. 为支持这种使用 `BrPageServer` 财务报告和审定财务报表 `BrComponentServer` 组件从 `@bloomreach/react-sdk/server` 作为对应方提供一揽子服务.

#### 使用量

要在您的反应应用程序中使用服务器组件, 只需替换所有发生 `BrPage` 财务报告和审定财务报表 `BrComponent` 与 `BrPageServer` 财务报告和审定财务报表 `BrComponentServer` 页:1 例如:

```jsx
import React from 'react';
import axios from 'axios';
import { BrComponentServer, BrPageServer, BrProps } from '@bloomreach/react-sdk/server';

function Banner({ component, page, mapping }: BrProps) {
  return <div>Banner: {component.getName()}</div>;
}

export default function Page() {
  const configuration = { /* ... */ };

  return (
    <BrPageServer configuration={configuration} mapping={{ Banner }}>
      {({ page, mapping, component }) => (
        <>
          <header>
            {page && <Link to={page.getUrl('/')}>Home</Link>}
            <BrComponentServer path="menu" page={page} mapping={mapping} component={component}>
              <Menu page={page} mapping={mapping} />
            </BrComponentServer>
          </header>
          <section>
            <BrComponentServer path="main" page={page} mapping={mapping} component={component} />
          </section>
          <BrComponentServer path="footer" page={page} mapping={mapping} component={component}>
            <footer>
              <BrComponentServer page={page} mapping={mapping} component={component} />
            </footer>
          </BrComponentServer>
        </>
      )}
    </BrPageServer>
  );
}
```

> \[注\]
> 
> -   服务器组件不会在经验管理器中正确工作(更多信息见下文).
> -   依其性质, 您无法使用 NBRMODE 中的服务器组件 !
> -   在服务器组件中不支持管理内容/Menu按钮. 因为他们只应该在经验经理公司.
> -   `BrPageServer` 财务报告和审定财务报表 `BrComponentServer` 具有与 `BrPage` 财务报告和审定财务报表 `BrComponent`分别是:.

#### 混合服务器和客户端组件

在许多情况下,您希望您的反应应用程序同时在现场(使用服务器组件)和体验管理器(使用客户端组件)工作. 要做到这一点,最简单的方法是在您的应用程序中创建两个切入点,并检测使用 [`page.isPreview()`](https://bloomreach.github.io/spa-sdk/interfaces/index.Page.html#isPreview) 来自 spar-sdk 的函数。 下面是使用Next.js的示例:

**页.tsx**

```tsx
import axios from 'axios';
import { initialize } from '@bloomreach/spa-sdk';
import BrxAppClient from '@/components/BrxAppClient';
import BrxAppServer from '@/components/BrxAppServer';

export default async function Page() {
  const configuration = { /* ... */ };

  const page = await initialize({
    ...configuration,
    httpClient: axios,
  });

  const pageModel = page.toJSON();
  if (configuration.NBRMode || page.isPreview()) {
    // Props passed to Client Components need to be serializable by React.
    return (
      <BrxAppClient configuration={configuration} pageModel={pageModel} />
    );
  }

  return (
    <BrxAppServer configuration={configuration} page={page} />
  );
}
```

**BrxAppClient.tsx (英语)**

```tsx
'use client';

import React from 'react';
import axios from 'axios';
import { Banner } from './Banner';
import { Configuration, PageModel } from '@bloomreach/spa-sdk';
import { BrComponent, BrPage, BrProps } from '@bloomreach/react-sdk';

interface Props {
  configuration: Omit<Configuration, 'httpClient'>;
  pageModel: PageModel;
}

export default function BrxAppClient({configuration, pageModel}: Props) {
  const mapping = { Banner };

  return (
    <BrPage configuration={{ ...configuration, httpClient: axios }} mapping={mapping} page={pageModel}>
      {({ page, mapping: pageMapping, component }) => (
        <>
          <header>
            {page && <Link to={page.getUrl('/')}>Home</Link>}
            <BrComponent path="menu" page={page} mapping={pageMapping} component={component}>
              <Menu page={page} mapping={pageMapping} />
            </BrComponent>
          </header>
          <section>
            <BrComponent path="main" page={page} mapping={pageMapping} component={component} />
          </section>
          <BrComponent path="footer" page={page} mapping={pageMapping} component={component}>
            <footer>
              <BrComponent page={page} mapping={pageMapping} component={component} />
            </footer>
          </BrComponent>
        </>
      )}
    </BrPage>
  );
}
```

**BrxAppServer.tsx (英语)**

```tsx
import React from 'react';
import axios from 'axios';
import { Banner } from './Banner';
import { Configuration, Page } from '@bloomreach/spa-sdk';
import { BrComponentServer, BrPageServer } from '@bloomreach/react-sdk/server';

interface Props {
  configuration: Omit<Configuration, 'httpClient'>;
  page: Page;
}

export default function BrxAppServer({configuration, page}: Props) {
  const mapping = { Banner };

  return (
    <BrPageServer configuration={{ ...configuration, httpClient: axios }} mapping={mapping} page={page}>
      {({ page: contextPage, mapping: pageMapping, component }) => (
        <>
          <header>
            {contextPage && <Link to={contextPage.getUrl('/')}>Home</Link>}
            <BrComponentServer path="menu" page={contextPage} mapping={pageMapping} component={component}>
              <Menu page={contextPage} mapping={pageMapping} />
            </BrComponentServer>
          </header>
          <section>
            <BrComponentServer path="main" page={contextPage} mapping={pageMapping} component={component} />
          </section>
          <BrComponentServer path="footer" page={contextPage} mapping={pageMapping} component={component}>
            <footer>
              <BrComponentServer page={contextPage} mapping={pageMapping} component={component} />
            </footer>
          </BrComponentServer>
        </>
      )}
    </BrPageServer>
  );
}
```

**Banner.tsx 页面存档备份,存于互联网档案馆**

```tsx
import { BrProps } from '@bloomreach/react-sdk';

export default function Banner({ component, page, mapping }: BrProps) {
  return <div>Banner: {component.getName()}</div>;
}
```

> \[注\]
> 
> -   你必须把 `'use client'` 客户端切入点组件开头处(`BrxAppClient` (见以上例子) [标记客户端模块的边界](https://react.dev/reference/rsc/use-client)。 。 。 .
> -   通常您不需要为您的映射组件写入单独的客户端/服务器组件( S)`Banner` (见以上例子)。 因为你的出入口部分已经标出边界 为了方便,你可以使用新的布尔地产 `isClientComponent` 从 `BrProps` 界面来检查您的组件是作为客户端还是服务器组件提供的.
> -   如果您想要在您映射的组件中使用管理内容/ 菜单按钮, 请确保仅在组件交付客户端时才会提供 。 见 [按钮](https://npmcn.com/package/%40bloomreach/react-sdk/#readme-buttons) 下节.
> -   检查以下样本项目 `examples/next` 参考执行.

### 配置

这个 `BrPage`编号 :`BrPageServer` 组件支持您可用于自定义页面的多个选项 初始化。 这些选项将转交给 `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中的完整配置文档.

### 绘图

这个 `BrPage`编号 :`BrPageServer` 组件提供了将 React 组件与 brXM 链接的方法 这些。 它需要通过 `mapping` 属性,用于映射组件类型 及其代表.

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

```jsx
import NewsList from "./components/NewsList";

return <BrPage mapping={{ "News List": NewsList }} />;
```

这个 [集装箱](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/react-sdk/www.npmjs.com/package/@bloomreach/spa-sdk)默认情况下, 反应SDK提供了所有容器类型的执行,因为它是 定义 [文档](https://documentation.bloomreach.com/library/concepts/template-composer/channel-editor-containers.html)。 。 。 .

```jsx
import { TYPE_CONTAINER_INLINE } from "@bloomreach/spa-sdk";
import MyInlineContainer from "./components/MyInlineContainer";

return <BrPage mapping={{ [TYPE_CONTAINER_INLINE]: MyInlineContainer }} />;
```

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

```jsx
export default function MyInlineContainer() {
  return (
    <div>
      {React.Children.map(props.children, (child) => (
        <span className="float-left">{child}</span>
      ))}
    </div>
  );
}
```

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

```jsx
import Menu from "./components/Menu";

return <BrPage mapping={{ menu: Menu }} />;
```

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

```jsx
import { TYPE_CONTAINER_ITEM_UNDEFINED } from "@bloomreach/spa-sdk";
import Fallback from "./components/Fallback";

return <BrPage mapping={{ [TYPE_CONTAINER_ITEM_UNDEFINED]: Fallback }} />;
```

### 内置映射

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

```jsx
return (
  <BrComponent path="menu" page={page} mapping={mapping} component={component}>
    <Menu page={page} mapping={mapping} isClientComponent />
  </BrComponent>
);
```

或者,如果您正在使用服务器组件:

```jsx
return (
  <BrComponentServer path="menu" page={page} mapping={mapping} component={component}>
    <Menu page={page} mapping={mapping} isClientComponent={false} />
  </BrComponentServer>
);
```

也可以指出该组成部分的儿童将在哪里 摆放.

```jsx
return (
  <BrComponent path="footer" page={page} mapping={mapping} component={component}>
    <footer>
      <BrComponent page={page} mapping={mapping} />
    </footer>
  </BrComponent>
);
```

内部映射时的组件数据可以通过渲染道具访问.

```jsx
return (
  <BrComponent path="footer" page={page} mapping={mapping} component={component}>
    {({ component: footerComponent }) => (
      <footer>
        &copy; {footerComponent.getName()}
        <BrComponent page={page} mapping={mapping} component={footerComponent} />
      </footer>
    )}
  </BrComponent>
);
```

或者通过传递组件数据作为道具.

```jsx
export default function Menu({ component, page, mapping }) {
  return <ul>{component.getName()}</ul>;
}
```

### 按钮

-   建议添加 Css 风格 `position: relative` 切入按钮 因此,他们将正确定位在母容器组件内.
    
-   管理菜单按钮可使用 `BrManageMenuButton` 组件.
    

```tsx
import React from "react";
import { Menu, Reference } from "@bloomreach/spa-sdk";
import { BrManageMenuButton, BrProps } from "@bloomreach/react-sdk";

interface MenuModels {
  menu: Reference;
}

export default function MenuComponent({ component, page, mapping }: BrProps) {
  const menuRef = component?.getModels<MenuModels>().menu;
  const menu = menuRef && page?.getContent<Menu>(menuRef);

  if (!menu) {
    return null;
  }

  return (
    <ul className={page?.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      <BrManageMenuButton menu={menu} page={page} mapping={mapping} />
    </ul>
  );
}
```

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

```tsx
import React from "react";
import { Document, Reference } from "@bloomreach/spa-sdk";
import { BrManageContentButton, BrProps } from "@bloomreach/react-sdk";

interface BannerModels {
  document: Reference;
}

export default function Banner({ component, page, mapping }: BrProps) {
  const { document: documentRef } = component.getModels<BannerModels>();
  const document = documentRef && page.getContent<Document>(documentRef);

  return (
    <div className={page.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      <BrManageContentButton
        content={document}
        documentTemplateQuery="new-banner-document"
        folderTemplateQuery="new-banner-folder"
        parameter="document"
        root="banners"
        relative
        page={page}
        mapping={mapping}
      />
    </div>
  );
}
```

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

```tsx
import React from "react";
import { BrManageContentButton, BrProps } from "@bloomreach/react-sdk";

export default function News({ component, page, mapping }: BrProps) {
  // ...

  return (
    <div className={page.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      <BrManageContentButton
        documentTemplateQuery="new-news-document"
        folderTemplateQuery="new-news-folder"
        root="news"
        page={page}
        mapping={mapping}
      />
    </div>
  );
}
```

-   如果您的组件能够作为服务器/客户端的组件来渲染, 请确保您的管理内容/菜单按钮只在客户端组件中提供 。 您可以通过检查 `isClientComponent` 属性。 例如:

```tsx
import React from "react";
import { Document, Reference } from "@bloomreach/spa-sdk";
import { BrManageContentButton, BrProps } from "@bloomreach/react-sdk";

interface BannerModels {
  document: Reference;
}

export default function Banner({ component, page, mapping, isClientComponent }: BrProps) {
  const { document: documentRef } = component.getModels<BannerModels>();
  const document = documentRef && page.getContent<Document>(documentRef);

  return (
    <div className={page.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      {isClientComponent &&
        <BrManageContentButton
          content={document}
          documentTemplateQuery="new-banner-document"
          folderTemplateQuery="new-banner-folder"
          parameter="document"
          root="banners"
          relative
          page={page}
          mapping={mapping}
        />
      }
    </div>
  );
}
```

### 原生反应

SDK 完全兼容 [原生反应](https://reactnative.dev/) 但有一些最佳做法.

-   无法使用 `<div>` (原始内容存档于2018-09-31). React Industrial, and it is 建议使用 `hst.nomarkup` 后端的容器类型 配置 .
    
-   如果需要支持其他类型的集装箱,这些类型应当是: 在绘图中明显被压倒。 默认执行使用 HTML 报告所描述的实体 [文档](https://documentation.bloomreach.com/library/concepts/template-composer/channel-editor-containers.html)。 。 。 .
    
    ```jsx
    import React from "react";
    import { View } from "react-native";
    import { TYPE_CONTAINER_BOX } from "@bloomreach/spa-sdk";
    
    function MyBoxContainer() {
      return (
        <View>
          {React.Children.map(props.children, (child) => (
            <View>{child}</View>
          ))}
        </View>
      );
    }
    
    export default function App() {
      return <BrPage mapping={{ [TYPE_CONTAINER_BOX]: MyBoxContainer }} />;
    }
    ```
    
-   逆向绘图应被推翻,以防止生产时出错 一个新组件类型从后端弹出, 因为默认执行是 返回纯文本节点.
    
    ```jsx
    import React from "react";
    import { Text } from "react-native";
    import { TYPE_CONTAINER_ITEM_UNDEFINED } from "@bloomreach/spa-sdk";
    
    function Fallback({ component, page, mapping }) {
      return (
        page.isPreview() && (
          <Text>Component "{component.getType()}" is not defined.</Text>
        )
      );
    }
    
    export default function App() {
      return <BrPage mapping={{ [TYPE_CONTAINER_ITEM_UNDEFINED]: Fallback }} />;
    }
    ```
    
-   与 [相关性 模块](https://documentation.bloomreach.com/14/library/enterprise/enterprise-features/targeting/targeting.html), (中文(简体) ), 应在申请中处理存储和传递的访客身份标识 边 这是 `visitor` 选项 [配置](https://npmcn.com/package/%40bloomreach/react-sdk/#readme-configuration) 那个 启用不使用 cookie 的设置 .
    
    ```jsx
    import React, { useEffect, useMemo, useRef } from "react";
    import { read, write } from "./storage";
    
    export default function App() {
      const ref = useRef(null);
      const configuration = {
        /* ... */
        visitor: read("visitor"),
      };
    
      const visitor =
        ref.current &&
        ref.current.state.page &&
        ref.current.state.page.getVisitor();
    
      useEffect(() => void visitor && write("visitor", visitor), [
        visitor && visitor.id,
      ]);
    
      return <BrPage ref={ref} configuration={configuration} />;
    }
    ```
    

## 许可证

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

## 参考文献

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

### BrPage/ BrPageServer 软件

这是页面模型的切入点 。 本构成部分要求和 初始化页面模型,然后向孩子提供页面和绘图数据 通过渲染道具模式。 该组件使页面根组件与 收到渲染函数.

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `configuration` | _对_ | 这个 [配置](https://npmcn.com/package/%40bloomreach/react-sdk/#readme-configuration) (原始内容存档于2015-03-30). SPA SDK. |
| `mapping` | _对_ | BrXM 和 React 组件 [绘图](https://npmcn.com/package/%40bloomreach/react-sdk/#readme-mapping)。 。 。 . |
| `page` | _没有_ | 已初始化的页面实例或被预选的页面模式 。 大部分应该用于将状态从服务器端转移到客户端端端. |
| `children` | _没有_ | 接收到的渲染函数 `{ page, mapping, component, isClientComponent }` 参数,或常规反应儿童. |

### 编译员/编译员

本部分指出儿童或某些部分应放在何处. `BrComponent`编号 :`BrComponentServer` 可在内部使用 `BrPage`编号 :`BrPageServer` 或只绘制组件. 如果反应儿童被通过,那么他们就会被释放 [作为](https://npmcn.com/package/%40bloomreach/react-sdk/#readme-inline-mapping)。 。 。 . 否则,它将试图使所有儿童的成分循环.

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `path` | _没有_ | 一个组件的路径 。 路径被定义为相对于当前组件(例如. `main/container`) (中文(简体) ). 如果它被省略,所有的孩子将被释放. |
| `page` | _对_ | 当前页面实例来自 Page Model API . |
| `mapping` | _对_ | 动态组件分辨率的组件映射对象. |
| `component` | _没有_ | 父组件上下文 。 需要在其他组件内使用时. |
| `children` | _没有_ | 接收到的渲染函数 `{ page, mapping, component, isClientComponent }` 参数,或常规反应儿童. |

### Brmanage 按钮

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

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `page` | _对_ | 当前预览模式检测和按钮渲染的页面实例 . |
| `mapping` | _对_ | 组件映射对象( 一致性要求) . |
| `content` | _没有_ | 要打开编辑的内容实体 . |
| `documentTemplateQuery` | _没有_ | 用于创建新文档的模板查询 。 对于Content SaaS来说,关键是 `new-banner-document` 页:1 `banner` 文档类型。 如果文档类型在名称空间之外 `brxsaas`,键中还包括命名空间前缀,例如 `new-vuestorefront-accordion-document` 页:1 `accordion` 文档类型 `vuestorefront` 名称空间. |
| `folderTemplateQuery` | _没有_ | 在指定的大小写文件夹中使用的模板查询 `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` | _没有_ | 可选择文档位置的根文件夹路径 . |

### Brmanage 梅努按钮

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

| 财产 | 需求 | 说明 |
| --- | :-: | --- |
| `page` | _对_ | 当前预览模式检测和按钮渲染的页面实例 . |
| `mapping` | _对_ | 组件映射对象( 一致性要求) . |
| `menu` | _对_ | 相关的菜单模式. |

### BrProps 接口

所有映射组件应执行的基础接口以接收页面、映射和组件数据.

```typescript
interface BrProps<T extends Component = Component> {
  component?: T;      // The brXM component instance
  page: Page;         // The current page (required)
  mapping: BrMapping; // Component mapping object (required)
  isClientComponent?: boolean // Whether the component is rendered as a client component
}
```

## 常见问题

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

Bloomreach SPA SDK 反应

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

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

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

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

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

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

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

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

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

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

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

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