For the complete documentation index, see llms.txt. This page is also available as Markdown.

React API 参考

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

React API 导出自 @convai/embody/react。此处的每个组件和 Hook 也都接受在 createCharacter 参考文档,例如 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 固定摄像机。对象可调整限制。

回退内容

React.ReactNode

null

在主体加载期间渲染。

onReady

(character: CharacterHandle) => void

无

每个加载的角色在主体加载完成且连接处于活动状态时调用一次。内联函数也可以:重新渲染不会再次调用它。

onError

(error: Error) => void

无

使用导致加载停止的错误进行调用。

queue

BlendshapeQueue

角色自身的会话

覆盖此主体进行口型同步的转向。仅在一个客户端驱动多个角色时需要。

全部 createCharacter 选项 可作为属性传入。

CharacterModel

仅角色本身,用于放在 <Canvas> 中。它不会添加摄像机、灯光或控制器。

属性
类型
默认值
描述

onReady

(character: CharacterHandle) => void

无

每个加载的角色在主体加载完成且连接处于活动状态时调用一次。内联函数也可以:重新渲染不会再次调用它。

onError

(error: Error) => void

无

使用导致加载停止的错误进行调用。

queue

BlendshapeQueue

角色自身的会话

覆盖此主体进行口型同步的转向。

阴影

布尔值

false

角色的每个网格都会投射并接收阴影。是否投射由你的灯光决定。

全部 createCharacter 选项 可作为属性传入。

OrbitOptions

作为 orbit 的属性传入 ConvaiCharacter,或作为 选项 给 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]

必填

摄像机环绕的点,单位为米。请使用角色头部高度,而不是脚部高度。

选项

OrbitOptions

以上默认值

轨道限制。

useCharacter

加载一个角色并返回它。 UseCharacterOptions 包括所有 createCharacter 选项 加上 queue。必须在 <Canvas>.

字段
类型
描述

角色

CharacterHandle | null

已加载的角色,或 null 在其就绪之前。

客户端

ConvaiClient | null

就绪后连接的客户端。与 character.client.

错误

Error | null

导致加载停止的错误。

状态

'loading' | 'ready' | 'error'

'loading' 直到主体和连接都准备就绪。

当角色重新加载时

组件和 useCharacter 仅在以下属性之一更改时,才会重新加载角色,并关闭后重新打开其连接: characterId, token, authToken, apiKey, baseUrl, resolver,或 modelVariant。比较 resolver 是否为同一引用:将其定义在组件外部或对其进行 memo 化。

camera 以及 correctiveMap 会在无需重新加载的情况下应用到已加载的角色。其他所有选项,例如 动画, idleClip, 会话, 客户端,以及 装饰器,都会在角色加载时读取一次;若要更改其中之一,请使用新的 键.

useWidgetClient

将角色的 ConvaiClient 转换为 convaiClient 的属性传入 ConvaiWidget,而不会打开第二个连接。返回 null 当 客户端 为 null. WidgetClient 为 ConvaiClient 加上 活动状态, 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.

相关参考

createCharacter 参考

最后更新于

这有帮助吗?