> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/convaiwidget.md).

# ConvaiWidget 组件参考

预构建 React 聊天和语音小组件的参考，包括每个 prop、其默认值，以及小组件在会话期间替你处理的内容。

`ConvaiWidget` 是从 `@convai/web-widget/react` （安装 `@convai/web-widget` ，与 SDK 一起安装；自 2.0 版起，SDK 不再包含 UI）。它会渲染一个可折叠的对话面板，支持文本、语音、摄像头和屏幕共享，并由来自 `useConvaiClient`.

### 属性

该包未导出 props 类型。请直接在 JSX 属性中传入 props。

| 属性                            | 类型                            | 默认值    | 说明                                                                                                       |
| ----------------------------- | ----------------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `convaiClient`                | useConvaiClient `的返回值`        | 必需     | 组件所驱动的客户端。它必须提供 `isAudioMuted`, `isVideoEnabled`和 `isScreenShareActive`，这些属性由该 Hook 提供。                  |
| `showVideo`                   | `boolean`                     | `true` | 在设置栏中显示摄像头按钮。只有当 `connectionType` 为 `"video"`.                                                           |
| `showScreenShare`             | `boolean`                     | `true` | 在设置栏中显示屏幕共享按钮。只有当 `connectionType` 为 `"video"`.                                                          |
| `defaultVoiceMode`            | `boolean`                     | `true` | 以语音模式打开面板，并在每次连接后首次打开时取消麦克风静音。仅文本会话中此设置无效。                                                               |
| `requestPublicationGrant`     | `() => Promise<string>`       | 无      | 返回一个新的、仅可使用一次的启动令牌。设置此项后，组件会使用 `connectWithPublicationGrant` 建立连接，并以纯文本聊天模式运行。重新打开已发布的聊天会话时必须设置此项。       |
| `publishedChatConnectOptions` | `PublishedChatConnectOptions` | 无      | 传递给 `connectWithPublicationGrant`的选项，例如 `url` 和 `signal`。组件会丢弃 `connectAttemptId` ，因此每个新令牌都会获得一个新的尝试 ID。 |
| `publishedChatDescriptor`     | `{ display_name; image_url }` | 无      | 已发布聊天会话的页眉中显示的名称和图片。                                                                                     |

### 连接行为

* 组件挂载时不会连接。首次选择该按钮时，会使用存储在 `connect()` 中的配置调用 `useConvaiClient`，然后打开面板。
* 客户端连接过一次后，该按钮会改为调用 `reconnect()` 。
* 当 `requestPublicationGrant` 已设置，或客户端是已发布的聊天会话时，该按钮会调用 `requestPublicationGrant()` ，然后调用 `connectWithPublicationGrant()`.
* 连接错误会以 `Failed to connect:` 为前缀记录到控制台，面板则保持关闭。订阅客户端的 `error` 事件，即可在 UI 中显示错误。
* 客户端断开连接时，面板会关闭。

### 对话行为

* 组件会播放角色语音。使用 LiveKit 传输时，它会创建自己的 `AudioRenderer`；使用 WebSocket 传输时，则由 Pipecat 传输本身播放语音。
* 消息列表会显示 `ChatMessage` 条目，其类型为 `user-transcription`, `user-llm-text`, `bot-llm-text`, `bot-output`或 `bot-emotion`，且内容不为空。
* 只有在 `state.isConnected` 和 `isBotReady` 都为 `true`.
* 文本模式下，组件会通过 `audioControls.muteAudio()`.
* 将麦克风静音。扬声器按钮会在本地将角色语音静音，但不会停止响应。
* 页眉中的角色名称和图片来自 Convai 中已连接的角色；在已发布的聊天会话中，则来自 `publishedChatDescriptor` 。

### 设置托盘

客户端连接期间会显示设置托盘。

| 控制    | 操作                                                                                                                       |
| ----- | ------------------------------------------------------------------------------------------------------------------------ |
| Reset | 调用 `disconnect()`，然后 `resetSession()`。它不会重新连接；下次选择小组件按钮时会启动新会话。                                                          |
| 断开连接  | 调用 `disconnect()`.                                                                                                       |
| 摄像头   | 调用 `videoControls.enableVideo()` 或 `videoControls.disableVideo()`。当 `showVideo` 为 `true` 且 `connectionType` 为 `"video"`. |
| 屏幕共享  | 调用 `screenShareControls.toggleScreenShare()`。当 `showScreenShare` 为 `true` 且 `connectionType` 为 `"video"`.                |

在已发布且没有 `requestPublicationGrant`的聊天会话中，重置和断开连接选项会隐藏，因为小组件无法启动新会话。

### 示例

```tsx
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';

export default function App() {
  const convaiClient = useConvaiClient({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    enableVideo: true,
    startWithAudioOn: false,
  });

  return (
    <ConvaiWidget
      convaiClient={convaiClient}
      showVideo={true}
      showScreenShare={false}
      defaultVoiceMode={false}
    />
  );
}
```

### 相关参考

{% content-ref url="/pages/68959b8b127b7dad992c41de6f7e87cd945ce3e3" %}
[useConvaiClient Hook 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/useconvaiclient-hook.md)
{% endcontent-ref %}

{% content-ref url="/pages/a3978c3ff1ab0d126b04a15a7cc212776a8745d3" %}
[在 React 中构建自定义 UI](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/custom-ui-and-advanced-usage.md)
{% endcontent-ref %}

{% content-ref url="/pages/454c92abc7b09c6c632d94aa99c7adc9ccd49df0" %}
[开始使用原生 TypeScript](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/vanilla-typescript.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/convaiwidget.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
