# @botpress/webchat 中文文档

规范地址：https://npmcn.com/package/%40botpress/webchat/

版本：5\.5\.8
npm 元数据更新时间：2026-10-16T18:00:12.513Z
中文译文更新时间：2026-11-08T12:24:36.733Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40botpress/webchat
原文对照：https://npmcn.com/package/%40botpress/webchat/?lang=original
项目主页：https://github.com/botpress/genisys#readme
源码仓库：https://github.com/botpress/genisys

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

- 包体积（解压后）：3.3 MB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：39 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2021-11-11T01:29:18.757Z
- 最新版本发布：2026-10-16T18:00:11.208Z
- 近 30 天下载量：25459（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：168（近 12 个月 29 个）

## 中文简介

一个完全自定义的 React 库,可以让你无缝地将 Botpress Webchat 集成到您的 React 应用程序中.

## 安装

```sh
npm install @botpress/webchat
```

也可以使用：`pnpm add @botpress/webchat`、`yarn add @botpress/webchat`、`bun add @botpress/webchat`

## README

# @ bottpress/ webchat (中文(简体) )

一个完全自定义的 React 库,可以让你无缝地将 Botpress Webchat 集成到您的 React 应用程序中.

## 特征

-   🎨 **完全自定义** - 网络聊天经验的每个方面的样式和配置
-   🔌 **简单整合** - 简单的安装和设置程序
-   🛠️ **弹性结构** - 使用预建组件或构建自定义执行
-   📱 **响应** - 桌面和移动设备之间无缝工作

## 安装

```bash
# npm
npm install @botpress/webchat

# yarn
yarn add @botpress/webchat

# pnpm
pnpm install @botpress/webchat
```

## 所需资源

-   反应 18 或以上
-   一个已出版的 Botpress Bot
-   您的机器人客户端身份

## 快速启动

### 获取客户端身份

1.  打开你的机器人 [自动压板](https://app.botpress.cloud/)
2.  导航到 **网络聊天** 在左侧边栏
3.  打开 **特征** 子菜单
4.  转到 **高级设置** 选项卡
5.  收到吗 **客户身份**

### 基本执行

```jsx
import { Fab, Webchat } from '@botpress/webchat'
import { useState } from 'react'

function App() {
  const [isWebchatOpen, setIsWebchatOpen] = useState(false)

  return (
    <>
      <Webchat
        clientId="YOUR_CLIENT_ID"
        style={{
          width: '400px',
          height: '600px',
          display: isWebchatOpen ? 'flex' : 'none',
          position: 'fixed',
          bottom: '90px',
          right: '20px',
        }}
      />
      <Fab
        onClick={() => setIsWebchatOpen(!isWebchatOpen)}
        style={{
          position: 'fixed',
          bottom: '20px',
          right: '20px',
          width: '64px',
          height: '64px',
        }}
      />
    </>
  )
}
```

## 高级使用

### 自定义 Webchat 执行

为了更好地控制网络聊天的经验,请使用单个组件手动构建:

```jsx
import { Container, Header, MessageList, Composer, useWebchat, Fab } from '@botpress/webchat'
import { useState, useMemo } from 'react'

function App() {
  const [isWebchatOpen, setIsWebchatOpen] = useState(false)
  const { client, messages, isTyping, user, clientState, newConversation } = useWebchat({
    clientId: 'YOUR_CLIENT_ID',
  })

  const config = {
    botName: 'SupportBot',
    botAvatar: 'https://example.com/avatar.png',
    botDescription: 'Your virtual assistant',
  }

  const enrichedMessages = useMemo(
    () =>
      messages.map((message) => {
        const direction = message.authorId === user?.userId ? 'outgoing' : 'incoming'
        return {
          ...message,
          direction,
          sender:
            direction === 'outgoing'
              ? { name: user?.name ?? 'You', avatar: user?.pictureUrl }
              : { name: config.botName, avatar: config.botAvatar },
        }
      }),
    [messages, user, config]
  )

  return (
    <>
      <Container
        connected={clientState !== 'disconnected'}
        style={{
          width: '500px',
          height: '800px',
          display: isWebchatOpen ? 'flex' : 'none',
          position: 'fixed',
          bottom: '90px',
          right: '20px',
        }}
      >
        <Header
          closeWindow={() => setIsWebchatOpen(false)}
          restartConversation={newConversation}
          configuration={{
            botName: config.botName,
            botAvatar: config.botAvatar,
            botDescription: config.botDescription,
          }}
        />
        <MessageList
          botName={config.botName}
          botDescription={config.botDescription}
          isTyping={isTyping}
          messages={enrichedMessages}
          sendMessage={client?.sendMessage}
        />
        <Composer
          connected={clientState !== 'disconnected'}
          sendMessage={client?.sendMessage}
          uploadFile={client?.uploadFile}
          composerPlaceholder="Type a message..."
        />
      </Container>
      <Fab
        onClick={() => setIsWebchatOpen(!isWebchatOpen)}
        style={{
          position: 'fixed',
          bottom: '20px',
          right: '20px',
        }}
      />
    </>
  )
}
```

## 配置

### 使用 Webchat 组件

通过配置 `configuration` 道具 :

```jsx
<Webchat
  clientId="YOUR_CLIENT_ID"
  configuration={{
    botName: 'My Bot',
    botAvatar: 'https://example.com/avatar.png',
    botDescription: 'Here to help!',
  }}
/>
```

### 自定义样式

使用 `StylesheetProvider` 自定义主题的组件 :

```jsx
import { StylesheetProvider } from '@botpress/webchat'
;<StylesheetProvider />
{
  /* Your webchat components */
}
```

## 构成部分

-   **网络聊天** - 全网聊天部分
-   **集装箱** - 网络聊天集装箱包装器
-   **页眉** - 装有机器人信息的自定义标题
-   **信件列表** - 信件显示区域
-   **作曲家** - 消息输入和文件上传
-   **发型** - 浮动动作按钮
-   **样式表提供程序** - 自定义型式提供者
-   **使用网络聊天** - 网络聊天状态和方法

## 文档

详细文件、实例和API参考,访问:

**[Botpress Webchat 反应库文档](https://www.botpress.com/docs/webchat/react-library/get-started)**

## 支助

-   📖 [文档](https://www.botpress.com/docs)
-   💬 [迪斯科德社区](https://discord.com/invite/botpress)

## 许可证

这个图书馆是Botpress生态系统的一部分. 见 [Botpress 仓库](https://github.com/botpress/botpress) 获取许可证信息.

## 常见问题

### @botpress/webchat 是什么？

一个完全自定义的 React 库,可以让你无缝地将 Botpress Webchat 集成到您的 React 应用程序中\.

### 如何安装 @botpress/webchat？

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

### @botpress/webchat 支持 TypeScript 吗？

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

### @botpress/webchat 支持 ESM 还是 CommonJS？

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

### @botpress/webchat 可以商用吗？

@botpress/webchat 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @botpress/webchat 的下载量有多少？

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

### @botpress/webchat 还在维护吗？

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