Skip to main content

常见问题

安装与配置​

Widget 和 SDK 有什么区别？​

对比项React WidgetReact SDK
包名@bdky/aaas-pilot-kit-react-widget@bdky/aaas-pilot-kit-react
定位开箱即用的 UI 组件库底层能力封装
UI内置完整 UI无 UI，需自行实现
灵活性样式可定制完全自由
适用场景快速集成深度定制

详见 介绍页。

需要同时安装 SDK 吗？​

不需要。Widget 已经包含了 SDK 的依赖，会自动安装。

# 只需安装 Widget
npm install @bdky/aaas-pilot-kit-react-widget

支持哪些 React 版本？​

支持 React 16.8+ 和 React 19。需要支持 Hooks 的版本。

支持 SSR 吗？​

支持 Next.js 等 SSR 框架，但需要注意：

// 使用动态导入避免 SSR 问题
import dynamic from 'next/dynamic';

const PilotKit = dynamic(
    () => import('@bdky/aaas-pilot-kit-react-widget').then(mod => mod.PilotKit),
    {ssr: false}
);

初始化问题​

iOS Safari 为什么需要手动激活？​

iOS Safari 的安全策略限制了在 iframe 中自动播放音频和使用麦克风。当检测到这种情况时，会触发 onNeedManualActivation 事件。

cloud-native 模式无需处理

如果 rendererMode 配置为 'cloud-native'，则不需要处理手动激活，可以忽略此问题。

解决方案（standard 模式）：使用 StartupScreen 组件：

const [showStartup, setShowStartup] = useState(false);

<PilotKit
    onNeedManualActivation={() => setShowStartup(true)}
    {...props}
>
    <StartupScreen
        show={showStartup}
        onReady={() => setShowStartup(false)}
    />
</PilotKit>

为什么组件没有显示？​

检查以下几点：

  1. PilotKit 包裹：所有组件必须在 PilotKit 内部使用
  2. 容器高度：确保父容器有明确的高度
  3. 配置正确：检查 appKey、appSecret、agentId 是否正确
// ✅ 正确
<div style={{height: '100vh'}}>
    <PilotKit appKey="..." appSecret="..." agentId="...">
        <ConversationList />
    </PilotKit>
</div>

// ❌ 错误：缺少高度
<div>
    <PilotKit {...props}>
        <ConversationList />
    </PilotKit>
</div>

onReady 什么时候触发？​

当 SDK 初始化完成、WebSocket 连接成功后触发。此时可以：

  • 隐藏加载页
  • 开始语音交互
  • 调用 ref 方法

交互问题​

如何发送文字消息？​

方式一：使用 ControlPanel 内置的输入框

<ControlPanel defaultMode="text" />

方式二：使用 ref 调用

const pilotKitRef = useRef(null);

<button onClick={() => pilotKitRef.current?.input('你好')}>
    发送
</button>

<PilotKit ref={pilotKitRef} {...props} />

方式三：使用 usePilotKitContext

function SendButton() {
    const {input} = usePilotKitContext();
    return <button onClick={() => input('你好')}>发送</button>;
}

如何打断 AI 播报？​

// 方式一：用户说话自动打断（默认开启）

// 方式二：调用 interrupt 方法
pilotKitRef.current?.interrupt();

// 方式三：使用 usePilotKitContext
const {interrupt} = usePilotKitContext();
interrupt();

如何实现静音/取消静音？​

// 使用 ref
pilotKitRef.current?.setMuted(true);  // 静音
pilotKitRef.current?.setMuted(false); // 取消静音

// 或使用 ControlPanel 内置的静音按钮
<ControlPanel />

如何获取对话历史？​

function ConversationHistory() {
    const {conversations} = usePilotKitContext();

    return (
        <div>
            {conversations.map(conv => (
                <div key={conv.id}>{conv.text}</div>
            ))}
        </div>
    );
}

样式问题​

如何修改组件样式？​

方式一：CSS 类名覆盖

.apk-control-panel {
    background: rgba(0, 0, 0, 0.8);
}

方式二：className 属性

<ControlPanel className="my-control-panel" />

方式三：style 属性

<ControlPanel style={{marginBottom: 20}} />

方式四：children 自定义渲染

<ControlPanel>
    <div className="my-custom-panel">...</div>
</ControlPanel>

详见 样式定制。

如何适配移动端？​

组件默认自动适配。如需强制使用特定模式：

// 强制移动端样式
<ControlPanel variant="mobile" />

// 强制桌面端样式
<ConversationList variant="desktop" />

详见 响应式适配。

样式被覆盖了怎么办？​

提高选择器优先级：

/* 方式一：更具体的选择器 */
.my-app .apk-control-panel {
    background: red;
}

/* 方式二：使用 !important（慎用） */
.apk-control-panel {
    background: red !important;
}

事件与回调​

事件回调的参数类型在哪里？​

事件 payload 类型定义在 React SDK 中，详见 React SDK Hooks。

如何监听 ASR 识别结果？​

<PilotKit
    onAsrMessage={(payload) => {
        console.log('识别结果:', payload.text);
        console.log('是否最终结果:', payload.isFinal);
    }}
    {...props}
/>

如何监听对话变化？​

<PilotKit
    onConversationChange={(payload) => {
        console.log('对话列表:', payload.conversations);
        console.log('最新对话:', payload.latestConversation);
    }}
    {...props}
/>

性能问题​

DebugPanel 影响性能吗？​

是的，DebugPanel 会持续监听事件。建议仅在开发环境使用：

<DebugPanel show={process.env.NODE_ENV === 'development'} />

如何优化大量对话的性能？​

  1. 限制显示数量：
<ConversationList>
    {({conversations}) => (
        <div>
            {conversations.slice(-50).map(conv => (
                <Conversation key={conv.id} conversation={conv} />
            ))}
        </div>
    )}
</ConversationList>
  1. 使用虚拟滚动（如 react-window）

其他问题​

如何与 Redux/Zustand 集成？​

通过事件回调同步状态：

import {useDispatch} from 'react-redux';

function App() {
    const dispatch = useDispatch();

    return (
        <PilotKit
            onConversationChange={(payload) => {
                dispatch(setConversations(payload.conversations));
            }}
            {...props}
        />
    );
}

如何在组件外调用方法？​

使用 ref：

// 全局 ref
const pilotKitRef = createRef();

// 在任何地方调用
function sendMessage(text) {
    pilotKitRef.current?.input(text);
}

Widget 支持 TypeScript 吗？​

完全支持。包含完整的类型定义：

import type {
    PilotKitProps,
    PilotKitRef,
    Variant
} from '@bdky/aaas-pilot-kit-react-widget';

如何报告问题？​

  1. 检查控制台错误信息
  2. 使用 DebugPanel 查看事件日志
  3. 提供最小复现示例
  4. 联系技术支持

相关​