> 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` 是从以下位置导出的预构建 React 组件 `@convai/web-widget/react` (安装 `@convai/web-widget` 在 SDK 旁边；自 2.0 起，SDK 不再附带 UI)。它会渲染一个可折叠的对话面板，用于文本、语音、摄像头和屏幕共享，由来自 `useConvaiClient`.

### 属性

props 类型不会从该包中导出。请将 props 以内联方式作为 JSX 属性传入。

| 属性                            | 类型                            | 默认值    | 描述                                                                                                    |
| ----------------------------- | ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `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()`.
* 连接错误会以 `连接失败：` 记录到控制台中，并且面板保持关闭。请订阅客户端的 `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` 在已发布聊天会话中。

### 设置托盘

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

| 控制   | 操作                                                                                                                          |
| ---- | --------------------------------------------------------------------------------------------------------------------------- |
| 重置   | 调用 `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 参考](/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](/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](/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.