> 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-embody/react-api-reference.md).

# React API 参考

Convai Embody 的 React 组件和 Hooks 参考，包括每个属性、其类型和默认值，以及每个 Hook 的返回值。

React API 从 `@convai/embody/react`导出。此处的每个组件和 Hook 也都接受 [createCharacter 参考文档](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md)中介绍的角色选项，例如 `characterId`, `token`和 `apiKey`.

更改这些选项中的任意一项都会重新加载身体，但有一个例外：新的 `correctiveMap` 会应用于正在运行的角色，因此切换映射不会中断语音。

### ConvaiCharacter

一个独立的角色视图，包含一个 `<Canvas>`、一个摄像机、一组人像灯光、轨道控制和角色。主光位于摄像机左侧 45° 处，并会随摄像机旋转而移动，同时投射柔和阴影；辅光、轮廓光和微弱的环境光让画面更完整，并采用 Neutral 色调映射。它既是命名导出，也是 `@convai/embody/react`.

| 属性           | 类型                                                                                         | 默认值                                                                | 说明                                                |
| ------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------- |
| `style`      | `React.CSSProperties`                                                                      | `{ width: '100%', height: '100%', minHeight: '100vh' }`，并与您提供的样式合并 | 包装元素的样式。                                          |
| `className`  | `string`                                                                                   | 无                                                                  | 包装元素的类名。                                          |
| `background` | `string \| null`                                                                           | `'#17181c'`                                                        | 场景背景颜色。 `null` 会渲染为透明，让页面内容透出。                    |
| `camera`     | `{ position?: [number, number, number]; fov?: number; target?: [number, number, number] }` | `position: [0, 1.45, 3.6]`, `fov: 35`, `target: [0, 0.92, 0]`      | 以米为单位设置摄像机取景参数。                                   |
| `orbit`      | `boolean \| OrbitOptions`                                                                  | `true`                                                             | 拖动可绕角色旋转视角，滚动可拉近或拉远。 `false` 会固定摄像机。传入对象可调整各项限制。  |
| `fallback`   | `React.ReactNode`                                                                          | `null`                                                             | 身体加载期间显示的内容。                                      |
| `onReady`    | `(character: CharacterHandle) => void`                                                     | 无                                                                  | 每个角色加载完成时调用一次，此时身体已加载且连接已建立。可以使用内联函数：重新渲染不会再次调用它。 |
| `onError`    | `(error: Error) => void`                                                                   | 无                                                                  | 加载停止时，会将导致停止的错误传入此回调。                             |
| `queue`      | `BlendshapeQueue`                                                                          | 角色自身的会话                                                            | 指定此身体进行口型同步所使用的会话。仅当一个客户端驱动多个角色时才需要设置。            |

全部 [createCharacter 的选项](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md#options) 均可作为属性传入。

### CharacterModel

仅包含角色本身，可在你创建的 `<Canvas>` 中使用。它不会添加相机、灯光或控制器。

| 属性        | 类型                                     | 默认值     | 说明                                                |
| --------- | -------------------------------------- | ------- | ------------------------------------------------- |
| `onReady` | `(character: CharacterHandle) => void` | 无       | 每个角色加载完成时调用一次，此时身体已加载且连接已建立。可以使用内联函数：重新渲染不会再次调用它。 |
| `onError` | `(error: Error) => void`               | 无       | 加载停止时，会将导致停止的错误传入此回调。                             |
| `queue`   | `BlendshapeQueue`                      | 角色自身的会话 | 指定此身体进行口型同步所使用的会话。                                |
| `shadows` | `boolean`                              | `false` | 角色的所有网格都会投射并接收阴影。是否投射阴影由灯光决定。                     |

全部 [createCharacter 的选项](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md#options) 均可作为属性传入。

### OrbitOptions

作为 `orbit` 属性传入 `ConvaiCharacter`，或作为 `options` 传入 `OrbitRig`.

| 字段                | 类型        | 默认值              | 说明                                                     |
| ----------------- | --------- | ---------------- | ------------------------------------------------------ |
| `minDistance`     | `number`  | `0.6`            | 相机允许靠近的最近距离，单位为米。                                      |
| `maxDistance`     | `number`  | `8`              | 相机允许移至的最远距离，单位为米。                                      |
| `minPolarAngle`   | `number`  | `Math.PI * 0.12` | 相机允许升至的最高位置，以相对于正上方的弧度表示。                              |
| `maxPolarAngle`   | `number`  | `Math.PI * 0.52` | 相机允许降至的最低位置，以相对于正上方的弧度表示。超过 `Math.PI / 2` 时，相机会从下方向上看。 |
| `enablePan`       | `boolean` | `false`          | 拖动角色在画面中移动。                                            |
| `enableZoom`      | `boolean` | `true`           | 滚动以拉近或拉远。                                              |
| `autoRotate`      | `boolean` | `false`          | 自动缓慢地围绕角色旋转。                                           |
| `autoRotateSpeed` | `number`  | `1.2`            | 当 `autoRotate` 启用时的速度。                                 |

### OrbitRig

为你创建的 `<Canvas>` 中的 `CharacterModel`，与……的行为一致 `ConvaiCharacter` 提供的行为。

| 属性        | 类型                         | 默认值   | 说明                                  |
| --------- | -------------------------- | ----- | ----------------------------------- |
| `target`  | `[number, number, number]` | 必填    | 摄像机环绕的目标点，单位为米。请使用角色头部的高度，而不是脚部的高度。 |
| `options` | `OrbitOptions`             | 上述默认值 | 环绕限制。                               |

### useCharacter

```tsx
function useCharacter(options: UseCharacterOptions): UseCharacterResult
```

加载角色并返回该角色。 `UseCharacterOptions` 包含所有 [createCharacter 选项](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md#options) 以及 `queue`。必须在 `<Canvas>`.

| 字段          | 类型                                | 说明                                |
| ----------- | --------------------------------- | --------------------------------- |
| `character` | `CharacterHandle \| null`         | 已加载的角色；在其准备就绪前为 `null` 。          |
| `client`    | `ConvaiClient \| null`            | 准备就绪后连接的客户端。与 `character.client`. |
| `error`     | `Error \| null`                   | 导致加载停止的错误。                        |
| `status`    | `'loading' \| 'ready' \| 'error'` | `'loading'` ，直到角色主体和连接都已就绪。       |

### 角色何时重新加载

这些组件和 `useCharacter` 只有在以下某个属性发生变化时，才会重新加载角色并关闭后重新打开其连接： `characterId`, `token`, `authToken`, `apiKey`, `baseUrl`, `onPrem`, `resolver`或 `modelVariant`。按引用身份进行比较：请在组件外定义它，或使用 memoize 缓存它。 `resolver` 。

`camera` 和 `correctiveMap` 会在不重新加载的情况下应用于已加载的角色。其他所有选项（例如 `animations`, `idleClip`, `session`, `client`，以及 `decorators`）均在角色加载时读取一次；要更改其中某个选项，请使用新的 `key`.

### useWidgetClient

```tsx
function useWidgetClient(client: ConvaiClient | null): WidgetClient | null
```

将角色的 `ConvaiClient` 适配为 `convaiClient` 属性，供 `ConvaiWidget`使用，且不会建立第二个连接。当 `null` ；当 `client` 为 `null`. `WidgetClient` 为 `ConvaiClient` 时，返回包含 `activity`, `isAudioMuted`, `isVideoEnabled`以及组件读取的其他状态字段的对象。

仅在以下版本中需要： `@convai/web-widget` 0.3.0 之前的版本。从 0.3.0 开始， `ConvaiWidget` 会直接接收角色的 `ConvaiClient` 。

### 从 Convai Web SDK 重新导出

这些是 Convai Web SDK 自身导出的内容，重新导出时未作任何更改。

| 导出项               | 类型                                     |
| ----------------- | -------------------------------------- |
| `useConvaiClient` | React Hook。会创建一个独立的客户端和连接；请勿将其用于角色的组件。 |
| `ConvaiClient`    | 类                                      |
| `ConvaiConfig`    | 类型                                     |

Convai Embody 仅包含 3D 角色。聊天界面（`ConvaiWidget`以及 React `AudioRenderer` 和 `AudioContext`）处于 `@convai/web-widget/react`.

### 相关参考

{% content-ref url="/pages/b60906ed5049da52cc6ddb85571a9101f1eacdb4" %}
[createCharacter 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.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-embody/react-api-reference.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.
