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 参考最后更新于
这有帮助吗?