Skip to main content

常见问题

安装与配置​

Widget 和 SDK 有什么区别？​

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

详见 介绍页。

需要同时安装 SDK 吗？​

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

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

支持哪些 Vue 版本？​

支持 Vue 3.3+。需要使用 Composition API。

支持 SSR 吗？​

支持 Nuxt 等 SSR 框架，但需要注意：

<script setup lang="ts">
import {defineAsyncComponent} from 'vue';

const PilotKit = defineAsyncComponent(() =>
    import('@bdky/aaas-pilot-kit-vue3-widget').then(mod => mod.PilotKit)
);
</script>

<template>
    <ClientOnly>
        <PilotKit v-bind="props" />
    </ClientOnly>
</template>

初始化问题​

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

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

cloud-native 模式无需处理

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

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

<script setup lang="ts">
import {ref} from 'vue';
import {PilotKit, StartupScreen} from '@bdky/aaas-pilot-kit-vue3-widget';

const showStartup = ref(false);
</script>

<template>
    <PilotKit
        @needManualActivation="showStartup = true"
        v-bind="props"
    >
        <StartupScreen
            :show="showStartup"
            @ready="showStartup = false"
        />
    </PilotKit>
</template>

为什么组件没有显示？​

检查以下几点：

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

    <!-- ❌ 错误：缺少高度 -->
    <div>
        <PilotKit v-bind="props">
            <ConversationList />
        </PilotKit>
    </div>
</template>

@ready 什么时候触发？​

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

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

交互问题​

如何发送文字消息？​

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

<template>
    <ControlPanel defaultMode="text" />
</template>

方式二：使用 ref 调用

<script setup lang="ts">
import {ref} from 'vue';
import {PilotKit, type IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

const pilotKitRef = ref<IPilotKitRef | null>(null);

function sendMessage() {
    pilotKitRef.value?.input('你好');
}
</script>

<template>
    <button @click="sendMessage">发送</button>
    <PilotKit ref="pilotKitRef" v-bind="props" />
</template>

方式三：使用 usePilotKitContext

<script setup lang="ts">
import {usePilotKitContext} from '@bdky/aaas-pilot-kit-vue3-widget';

const pilotKit = usePilotKitContext();

function sendMessage() {
    pilotKit?.input('你好');
}
</script>

<template>
    <button @click="sendMessage">发送</button>
</template>

如何打断 AI 播报？​

<script setup lang="ts">
import {ref} from 'vue';
import {usePilotKitContext, type IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

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

// 方式二：使用 ref
const pilotKitRef = ref<IPilotKitRef | null>(null);
pilotKitRef.value?.interrupt();

// 方式三：使用 usePilotKitContext
const pilotKit = usePilotKitContext();
pilotKit?.interrupt();
</script>

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

<script setup lang="ts">
import {ref} from 'vue';
import {type IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

const pilotKitRef = ref<IPilotKitRef | null>(null);

// 静音
pilotKitRef.value?.mute(true);

// 取消静音
pilotKitRef.value?.mute(false);

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

<template>
    <ControlPanel />
</template>

如何获取对话历史？​

<script setup lang="ts">
import {usePilotKitContext} from '@bdky/aaas-pilot-kit-vue3-widget';

const {conversations} = usePilotKitContext() ?? {};
</script>

<template>
    <div>
        <div v-for="conv in conversations" :key="conv.id">
            {{ conv.text }}
        </div>
    </div>
</template>

样式问题​

如何修改组件样式？​

方式一：CSS 类名覆盖

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

方式二：class 属性

<template>
    <ControlPanel class="my-control-panel" />
</template>

方式三：style 属性

<template>
    <ControlPanel :style="{marginBottom: '20px'}" />
</template>

方式四：default slot 自定义渲染

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

详见 样式定制。

如何适配移动端？​

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

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

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

详见 响应式适配。

样式被覆盖了怎么办？​

提高选择器优先级：

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

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

/* 方式三：Vue scoped 深度选择器 */
:deep(.apk-control-panel) {
    background: red;
}

事件与回调​

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

事件 payload 类型定义在 Vue 3 SDK 中，详见 Vue 3 SDK Composables。

如何监听 ASR 识别结果？​

<script setup lang="ts">
function handleAsrMessage(payload: any) {
    console.log('识别结果:', payload.text);
    console.log('是否最终结果:', payload.isFinal);
}
</script>

<template>
    <PilotKit
        @asrMessage="handleAsrMessage"
        v-bind="props"
    />
</template>

如何监听对话变化？​

<script setup lang="ts">
function handleConversationChange(payload: any) {
    console.log('对话列表:', payload.conversations);
    console.log('最新对话:', payload.latestConversation);
}
</script>

<template>
    <PilotKit
        @conversationChange="handleConversationChange"
        v-bind="props"
    />
</template>

性能问题​

DebugPanel 影响性能吗？​

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

<script setup lang="ts">
const isDev = import.meta.env.DEV;
</script>

<template>
    <DebugPanel :show="isDev" />
</template>

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

  1. 限制显示数量：
<template>
    <ConversationList v-slot="{conversations}">
        <div>
            <Conversation
                v-for="conv in conversations.slice(-50)"
                :key="conv.id"
                :conversation="conv"
            />
        </div>
    </ConversationList>
</template>
  1. 使用虚拟滚动（如 vue-virtual-scroller）

其他问题​

如何与 Pinia 集成？​

通过事件回调同步状态：

<script setup lang="ts">
import {useConversationStore} from '@/stores/conversation';

const store = useConversationStore();

function handleConversationChange(payload: any) {
    store.setConversations(payload.conversations);
}
</script>

<template>
    <PilotKit
        @conversationChange="handleConversationChange"
        v-bind="props"
    />
</template>

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

使用 ref：

// composables/usePilotKit.ts
import {ref} from 'vue';
import type {IPilotKitRef} from '@bdky/aaas-pilot-kit-vue3-widget';

export const pilotKitRef = ref<IPilotKitRef | null>(null);

export function sendMessage(text: string) {
    pilotKitRef.value?.input(text);
}
<script setup lang="ts">
import {pilotKitRef} from '@/composables/usePilotKit';
</script>

<template>
    <PilotKit ref="pilotKitRef" v-bind="props" />
</template>

Widget 支持 TypeScript 吗？​

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

import type {
    IPilotKitProps,
    IPilotKitRef,
    VariantType
} from '@bdky/aaas-pilot-kit-vue3-widget';

如何报告问题？​

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

相关​