# @archbee/app-widget 中文文档

规范地址：https://npmcn.com/package/%40archbee/app-widget/

版本：1\.1\.43
npm 元数据更新时间：2026-10-20T12:58:24.982Z
中文译文更新时间：2026-11-08T12:01:18.010Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40archbee/app-widget
原文对照：https://npmcn.com/package/%40archbee/app-widget/?lang=original

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

- 包体积（解压后）：87.1 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2023-11-17T12:47:58.869Z
- 最新版本发布：2026-10-20T12:58:24.612Z
- 近 30 天下载量：1781（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：104（近 12 个月 10 个）

## 中文简介

-   [安装](https://npmcn.com/package/%40archbee/app-widget/#description-installation) - 说吧 [API 文档](https://npmcn.com/package/%40archbee/app-widget/#description-api-documentation) - 说吧 [实例](https://npmcn.com/package/%40archbee/app-widget/#description-examples)

## 安装

```sh
npm install @archbee/app-widget
```

也可以使用：`pnpm add @archbee/app-widget`、`yarn add @archbee/app-widget`、`bun add @archbee/app-widget`

## README

# Archbee 重现组件部件

## 目录

-   [安装](https://npmcn.com/package/%40archbee/app-widget/#readme-installation)
-   [API 文档](https://npmcn.com/package/%40archbee/app-widget/#readme-api-documentation)
-   [实例](https://npmcn.com/package/%40archbee/app-widget/#readme-examples)

## 安装

要安装、使用 [小时](https://pnpm.io/)数字 :

```
$ pnpm add @archbee/app-widget
```

如果您需要安装Archbee Control Widget SDK, 您可以找到更多细节 [这里](https://docs.archbee.com/app-widget)。 。 。 .

## API 文档

Archbee React 组件部件的主要文档可见于 [文档](https://docs.archbee.com/app-widget),它描述了API 并举例说明其用法.

## 实例

以下是Archbee React 部件在应用程序中使用的简单例子

```tsx
import React from 'react'
import { ArchbeeAppWidget } from '@archbee/app-widget'

function App() {
  return (
    <div>
      <ArchbeeAppWidget
        spaceId={/** published space id **/}
        onWidgetOpen={() => {
          /** ... **/
        }} // callback function called after widget has open
        // onWidgetClose={() => { /** ... **/ }} // callback function called after widget has open
      >
        <button type="button">Open</button>
      </ArchbeeAppWidget>
    </div>
  )
}

ReactDOM.render(<App />, appElement)
```

也可以采用比较有方案的办法:

```tsx
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>
  );
}

ReactDOM.render(<App />, appElement);
```

## 组件道具

| 财产 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `spaceId` | `string` | `required` | 通过理想的ID来装入您的文档. |
| `docId` | `string` | `optional` | 要打开部件文件的医生。 若为 `docId` 已经通过, `widgetType` 无论道具是否通过,它都会以 docs 模式打开. |
| `blockId` | `string` | `optional` | 某个文档打开后要滚动的块 . |
| `jwt` | `string` | `optional` | 传出jwt 令牌,以便看到 jwt 受保护的文档 . |
| `shareableToken` | `string` | `optional` | 从您的私人链接中传递可共享的托肯来保护您的文档 . |
| `className` | `string` | `optional` | 将 CSS 课程传给 `div` 包装 |
| `widgetType` | `docs | search` | `optional` | 默认值是 `docs`。此选项将打开部件,并带有所期望的行为. `docs`` type will open the widget with the default behaviour,` 搜索 \` 将打开一个显示有 AI 支持的搜索栏的搜索部件栏( 如果包含在您的订阅中) |
| `bubble` | `ask | invisible` | `optional` | 默认值是 `invisible`。此道具将显示您屏幕右下方的询问泡。 当有人点击它时, 搜索部件会打开 . |
| `loadingStrategy` | `eager | lazy` | `optional` | 默认值是 `lazy`。虽然 `lazy` 加载延迟资源初始化, `eager` 执行代码后立即加载或初始化部件. |
| `anchor` | `string` | `optional` | 你可以提供你的 `class`, (中文(简体) ), `id` 或者说 `path` 到 DOM 元素中,您想要部件锁定和即时启动 。 提供的集装箱应具有 `position: relative` ,因为部件将基于所找到的第一个相对父文件显示. |
| `onWidgetOpen` | `void` | `optional` | 在部件打开后调用 . |
| `onWidgetClose` | `void` | `optional` | 在部件关闭后调用 . |
| `hideNavbar` | `boolean` | `optional` | 默认值是 `false`。它隐藏了标题导航符与模式. |
| `initialSearchQuery` | `string` | `optional` | 预集搜索输入,并在部件打开时触发搜索。 使用方式 `widgetType: "search"` 打开已显示结果的部件. |

## 泡泡声

使用 `bubble` 要浏览整个文档,请选择一个简单的搜索按钮.

![Ask search bubble](https://archbee.imgix.net/bNBm7nPJgXjbjLyfbHNh2/3AB9jiOJuhR9OtFAE19QP_screenshot-2024-03-22-at-172311.png)

## 查找方法

若为 `ref` 未转至 `ArchbeeAppWidget`时,孩子会自动打开模式弹出.

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `open` | `method` | 程序化打开部件 . |
| `close` | `method` | 程序关闭部件 . |
| `instance` | `method` | 返回部件实例. |

## 演示文稿

下面是演示设置 [代码框](https://codesandbox.io/),哪个 展示出拱蜂应用的各种特征:

-   [演示](https://codesandbox.io/s/funny-austin-gndp8w?file=/src/App.tsx)

## 常见问题

### @archbee/app-widget 是什么？

安装 - 说吧 API 文档 - 说吧 实例

### 如何安装 @archbee/app-widget？

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

### @archbee/app-widget 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/archbee\_\_app-widget 是否存在。

### @archbee/app-widget 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @archbee/app-widget 可以商用吗？

@archbee/app-widget 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @archbee/app-widget 的下载量有多少？

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

### @archbee/app-widget 还在维护吗？

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