> 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 参考文档](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md)中的角色选项，例如 `characterId`, `token`，以及 `apiKey`.

### ConvaiCharacter

一个自包含的角色视图：一个 `<Canvas>`、摄像机、灯光、轨道控制和角色。它既是命名导出，也是 `@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 选项](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md#options) 可作为 props 接受。

### CharacterModel

单独的角色，供在你创建的 `<Canvas>` 中使用。它不添加摄像机、灯光或控制。

| 属性        | 类型                                     | 默认      | 说明                 |
| --------- | -------------------------------------- | ------- | ------------------ |
| `onReady` | `(character: CharacterHandle) => void` | 无       | 当身体加载完成且连接建立后调用一次。 |
| `onError` | `(error: Error) => void`               | 无       | 在导致加载停止的错误发生时调用。   |
| `queue`   | `BlendshapeQueue`                      | 角色自身的会话 | 覆盖此身体进行口型同步的回合。    |

全部 [createCharacter 选项](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.md#options) 可作为 props 接受。

### OrbitOptions

作为 `orbit` 的 `ConvaiCharacter`，或者作为 `options` 为 `OrbitRig`.

| 字段                | 类型    | 默认               | 说明                                                   |
| ----------------- | ----- | ---------------- | ---------------------------------------------------- |
| `minDistance`     | `数值`  | `0.6`            | 摄像机最近可到达的距离，单位为米。                                    |
| `maxDistance`     | `数值`  | `8`              | 摄像机最远可移动的距离，单位为米。                                    |
| `minPolarAngle`   | `数值`  | `Math.PI * 0.12` | 摄像机可上升的最高角度，单位为相对于正上方的弧度。                            |
| `maxPolarAngle`   | `数值`  | `Math.PI * 0.52` | 摄像机可下降的最低角度，单位为相对于正上方的弧度。超过 `Math.PI / 2` 后，它会从下方仰视。 |
| `enablePan`       | `布尔值` | `false`          | 拖动角色可在画面中移动。                                         |
| `enableZoom`      | `布尔值` | `true`           | 滚动可放大和缩小。                                            |
| `autoRotate`      | `布尔值` | `false`          | 自动绕角色缓慢旋转。                                           |
| `autoRotateSpeed` | `数值`  | `1.2`            | 速度，开启 `autoRotate` 已开启。                              |

### OrbitRig

用于 `<Canvas>` 你围绕 `CharacterModel`创建的轨道控制，匹配 `ConvaiCharacter` 提供的行为。

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

### useCharacter

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

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

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

### useWidgetClient

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

适配角色的 `ConvaiClient` 连接到 `convaiClient` 的 `ConvaiWidget`，而不打开第二个连接。返回 `null` 在 `client` 是 `null`. `WidgetClient` 是 `ConvaiClient` 加上 `活动`, `isAudioMuted`, `isVideoEnabled`，以及小组件读取的其他状态字段。

### 从 Convai Web SDK 重新导出

这些是 Convai Web SDK 自身的导出项，未经更改地重新导出，因此应用只需要 `@convai/embody`.

| 导出                | Kind                                   |
| ----------------- | -------------------------------------- |
| `ConvaiWidget`    | React 组件                               |
| `useConvaiClient` | React hook。构造一个独立的客户端和连接；不要将其用于角色的小组件。 |
| `AudioRenderer`   | React 组件                               |
| `音频上下文`           | React 上下文                              |
| `ConvaiClient`    | 类                                      |
| `ConvaiConfig`    | 类型                                     |

### 相关参考

{% content-ref url="/pages/b60906ed5049da52cc6ddb85571a9101f1eacdb4" %}
[createCharacter 参考](/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.