---
title: 应用文档小部件 - React
slug: docs/cn/react
createdAt: 2023-11-17T14:25:39.130Z
---

我们已经在前一章解释了一些[上下文文档的优势](docId\:r8FcNcVUddkzd2Q2bPq2s)。本指南为`React` 和 `NextJS` 应用提供一种更优雅的方式来集成 Archbee app widget。

## 集成 app widget

:::::WorkflowBlock
:::WorkflowBlockItem
安装我们的 [npm 包](https://www.npmjs.com/package/@archbee/app-widget)：

```shell
# with npm
$ npm install --save @archbee/app-widget

# or with yarn
$ yarn add @archbee/app-widget
```
:::

::::WorkflowBlockItem
安装该包后，前往您的 `jsx/tsx` 文件并实例化组件：

:::CodeblockTabs
React

```typescript
import React from 'react';
import { ArchbeeAppWidget, AbWidgetRef } from '@archbee/app-widget'

function App() {
const widgetRef = useRef<AbWidgetRef>(null);

  return (
    <div>
        <ArchbeeAppWidget
            ref={widgetRef}
            spaceId={ /** published space id **/ }
            onWidgetOpen={() => { /** ... **/ }} // callback function called after widget has open
            onWidgetClose={() => { /** ... **/ }} // callback function called after widget has open
      >
        <button type='button' onClick={() => {
        <!-- Opens widget -->
            widgetRef.current?.open();
        }}>
          Open
        </button>
        
        <button type='button' onClick={() => {
        <!-- Closes widget -->
            widgetRef.current?.close();
        }}>
          Close
        </button>
        
        <button type='button' onClick={() => {
        <!-- Gets the instance of the widget if needed for various event manipulations. -->
            widgetRef.current?.instance();
        }}>
          Get widget instance
        </button>
      </ArchbeeAppWidget>
    </div>
  );
}
```
:::
::::

:::WorkflowBlockItem
您还可以参考 **空间设置** 中的信息：

1. 在编辑器中选择您的 **空间&#x20;**。
2. 点击齿轮图标 (⚙️) 进入 **设置。**
3. 前往 **小部件集成**。
4. 点击 `React` 选项卡，然后点击复制按钮，并将代码粘贴到您的 `tsx/.jsx` 文件中
:::
:::::

现在，该 widget 会处理所有后台逻辑。别担心，一切都已打包并最小化。下载量仅 56Kb，并且是异步加载的，因此您的用户不会感受到任何差别。

### 组件属性

| **属性**              | **类型**         | **是否必需** | **描述**                                                                                                                                                                                                                            |
| ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spaceId`           | `字符串`          | `必需`     | 传递所需的 id 以加载您的文档。                                                                                                                                                                                                                 |
| `docId`             | `字符串`          | `可选`     | 您希望在其中打开 widget 文档的文档。如果传递了 `docId`，则会忽略 `widgetType`，无论传递的属性是什么，它都会以 `文档` 模式打开。                                                                                                                                                  |
| `shareableToken`    | `字符串`          | `可选`     | 传递来自您的私人链接的 shareableToken 以保护您的文档。                                                                                                                                                                                               |
| `className`         | `字符串`          | `可选`     | 将 CSS 类传递给 `div` 包装器。                                                                                                                                                                                                             |
| `widgetType`        | `'文档' \| '搜索'` | `可选`     | 默认值为 `文档`。这将以所需行为打开 widget。`文档` 类型将以默认行为打开 widget，`搜索` 将打开一个搜索 widget 栏，显示带有 AI 支持（如果包含在您的订阅中）的搜索栏。                                                                                                                               |
| `隐藏导航栏`             | `布尔`           | `可选`     | 它会显示或隐藏 widget 模态框顶部的导航栏。默认情况下导航栏可见。如果您不想看到导航栏，请将其传递为 `真`，否则跳过即可。                                                                                                                                                                 |
| `加载策略`              | `'急切' \| '惰性'` | `可选`     | 默认值为 `懒惰`。用于 widget 加载的加载策略方法。                                                                                                                                                                                                    |
| `气泡`                | `隐形 \| 询问`     | `可选`     | 默认值为 `隐形的`。如果设置为 `询问`，将在屏幕右下角显示一个气泡。每当有人点击它时，搜索 widget 将打开。                                                                                                                                                                       |
| `bubblePlaceholder` | `字符串`          | `可选`     | 将在气泡部分显示的占位符。如果未传入，将显示默认值 `提出一个问题`。                                                                                                                                                                                               |
| `锚`                 | `字符串`          | `可选`     | 您可以为 DOM 元素提供 `类`、`id` 或 `路径`，以指定要挂载并实例化 widget 的位置。如果 DOM 中存在多个具有相同 path 的元素，它将锚定到找到的第一个元素。所提供的容器应具有 `position: relative`，因为 widget 将基于找到的第一个 **亲戚** **父母** 显示。<br />例如：`anchor: "#my-container"` / `anchor: ".container-class"` |
| `onWidgetOpen`      | `空`            | `可选`     | 在 widget 打开后调用的回调函数。                                                                                                                                                                                                              |
| `onWidgetClose`     | `空`            | `可选`     | 在 widget 关闭后调用的回调函数。                                                                                                                                                                                                              |

:::hint{type="info"}
可共享的 tokens 可用于 [Scaling plan](https://www.archbee.com/pricing)。阅读更多关于 [公共访问控制](docId\:mlpe5kbw014Xm_x0bWknb)。
:::

### Ref 方法

:::hint{type="info"}
如果未将 `ref` 传递给 `ArchbeeAppWidget`，子元素将在被点击后自动打开 modal 弹出窗口。
:::

| **属性** | **类型** | **描述**          |
| ------ | ------ | --------------- |
| `打开`   | `方法`   | 以编程方式打开 widget。 |
| `关闭`   | `方法`   | 以编程方式关闭 widget。 |
| `实例`   | `方法`   | 返回 widget 的实例。  |