PilotKit

核心容器组件，集成 Provider 和数字人渲染，是所有 Widget 组件的根组件。

基本用法

import {PilotKit, ControlPanel} from '@bdky/aaas-pilot-kit-react-widget';

function App() {
    return (
        <PilotKit
            token="your-token"
            figureId="your-figure-id"
            ttsPer="your-tts-per"
            agentConfig={{
                robotId: 'your-robot-id'
            }}
        >
            <ControlPanel />
        </PilotKit>
    );
}

使用 Ref

通过 ref 可以访问控制器方法：

import {useRef} from 'react';
import {PilotKit, type IPilotKitRef} from '@bdky/aaas-pilot-kit-react-widget';

function App() {
    const pilotKitRef = useRef<IPilotKitRef>(null);

    const handleSendMessage = () => {
        pilotKitRef.current?.input('你好');
    };

    const handleInterrupt = () => {
        pilotKitRef.current?.interrupt();
    };

    return (
        <PilotKit ref={pilotKitRef} {...props}>
            <button onClick={handleSendMessage}>发送消息</button>
            <button onClick={handleInterrupt}>打断</button>
        </PilotKit>
    );
}

Props

必填属性

属性	类型	说明
token	string	认证 Token
figureId	string	数字人形象 ID
ttsPer	string	TTS 音色 ID

Agent 配置

属性	类型	说明
agentConfig	{robotId: string; token?: string}	Agent 配置，与 agentService 二选一
agentService	typeof BaseAgentService	自定义 AgentService 类

agentConfig vs agentService

• 使用百度默认 Agent：配置 agentConfig
• 使用私有 Agent API：提供自定义 agentService，详见 自定义 AgentService

行为配置

属性	类型	默认值	说明
prologue	string	-	开场白，SDK 就绪后自动播报
interruptible	boolean	false	是否允许打断播报
timeoutSec	number	120	无操作超时时间（秒）
typeDelay	number	100	中文打字机效果延迟（ms）
enTypeDelay	number	50	英文打字机效果延迟（ms）
minSplitLen	number	10	流式文本最小分割长度

渲染配置

属性	类型	默认值	说明
rendererMode	'cloud-native' | 'standard'	'standard'	渲染模式
scaleX	number	1	水平缩放
scaleY	number	1	垂直缩放
translateX	number	0	水平偏移
translateY	number	0	垂直偏移

样式属性

属性	类型	说明
className	string	自定义类名
style	CSSProperties	自定义样式
backgroundUrl	string	背景图片 URL
autoMount	boolean	是否自动挂载，默认 true

事件回调

属性	类型	说明
onReady	() => void	SDK 就绪
onNeedManualActivation	() => void	需要手动激活（iOS iframe）
onAsrStart	() => void	ASR 开始
onAsrMessage	(payload) => void	ASR 识别结果
onRenderStart	(payload) => void	开始播报
onInactivity	(payload) => void	用户无操作超时
onBusy	(payload) => void	系统繁忙
onInterrupt	(payload) => void	播报被打断
onConversationChange	(payload) => void	对话内容变化
onIsRenderingChange	(isRendering) => void	播报状态变化
onReplyStart	(payload) => void	回复开始
onTtft	(payload) => void	首字延迟指标

事件 Payload 类型

事件回调的 Payload 类型定义详见 React SDK Hooks 文档。

Ref 方法

通过 ref 可以访问以下方法：

方法	类型	说明
input	(text: string) => void	发送文字输入
mute	(muted: boolean) => void	设置静音状态
interrupt	() => void	打断当前播报
dispose	() => void	销毁实例
playPrologue	() => void	播放开场白
playFromFullText	(text: string) => void	播放完整文本
playFromStreamText	(text: string) => void	流式播放文本
keepAlive	() => void	保持连接活跃
checkAudioDevice	() => Promise<Result>	检测音频设备
activateManually	() => Promise<void>	手动激活（iOS）
getIsReady	() => boolean	获取就绪状态
getIsMuted	() => boolean	获取静音状态
getIsRendering	() => boolean	获取播报状态

Context

PilotKit 内部创建了 PilotKitContext，子组件可以通过 usePilotKitContext 访问：

import {usePilotKitContext} from '@bdky/aaas-pilot-kit-react-widget';

function ChildComponent() {
    const pilotKit = usePilotKitContext();

    return (
        <button onClick={() => pilotKit?.input('你好')}>
            发送消息
        </button>
    );
}

样式定制

CSS 类名

类名	说明
.apk-pilot-kit	根容器
.apk-pilot-kit__mask	遮罩层（children 渲染位置）

背景图片

使用 backgroundUrl 设置背景：

<PilotKit
    backgroundUrl="https://example.com/background.jpg"
    // ...
>

相关

• React SDK Provider - 底层 Provider 文档
• 配置选项 - 完整配置选项参考