Standalone 非 Vue 宿主集成

自 v2.1.4-beta.8 起，@blueking/ai-blueking 提供 /standalone 子入口：将 Vue 3 runtime 与 chat-x 等依赖打入同一 bundle，供 React、Angular、jQuery、纯 HTML 等非 Vue 页面通过 mountAIBlueking / mountChatBot 挂载小鲸，无需在宿主安装 Vue。

适用场景

场景	说明
遗留系统 / 多技术栈页面	主应用不是 Vue，但需要在某一 DOM 区域嵌入 AI 对话
无构建工具的快速接入	通过 <script> 引入 IIFE，全局变量 AIBluekingStandalone
与默认入口对比	默认 @blueking/ai-blueking 要求宿主提供 Vue 3 + chat-x；Standalone 开箱即用，包体积更大

与 Vue 2 入口的区别

Standalone 仅支持 Vue 3 运行时。Vue 2 项目请继续使用 @blueking/ai-blueking/vue2 或升级宿主到 Vue 3 后再评估 Standalone。

安装

npm install @blueking/ai-blueking
# 或 pnpm / yarn

方式一：npm + 打包工具（推荐）

引入样式

Standalone 的 ES/UMD 构建会将 chat-x 与图标样式合并到独立 CSS 文件，必须引入：

import '@blueking/ai-blueking/dist/standalone/style.css';

挂载完整小鲸（AIBlueking）

import { mountAIBlueking } from '@blueking/ai-blueking/standalone';

const handle = mountAIBlueking('#ai-root', {
  props: {
    url: 'https://your-aidev-url.com/api/',
    enablePopup: true,
    requestOptions: {
      headers: () => ({ Authorization: `Bearer ${getToken()}` }),
    },
  },
  on: {
    'send-message': (message: string) => console.log('发送:', message),
    'sdk-error': (error) => console.error('SDK 错误:', error),
  },
});

// 编程式 API（与 Vue 模板 ref 的 expose 一致；show 在 sessionList 就绪后 resolve）
await handle.expose?.show();
handle.expose?.sendMessage('你好');
handle.updateProps({ url: 'https://next-api.example.com/api/' });
handle.unmount();

仅挂载聊天区（ChatBot）

import { mountChatBot } from '@blueking/ai-blueking/standalone';

const chat = mountChatBot('#chat-container', {
  props: {
    url: 'https://your-aidev-url.com/api/',
    height: '600px',
  },
  on: {
    error: (err: Error) => console.error(err),
  },
});

chat.expose?.sendMessage('Hello');

事件监听写法

on 的键支持：

• kebab-case（与组件 emit 名一致）：'send-message'、'sdk-error'
• onXxx（Vue 3 listener 形式）：onSendMessage、onSdkError

内部会统一映射为 Vue 的 onSendMessage 等 props。

方式二：<script> 直引（IIFE）

构建产物：dist/standalone/index.iife.min.js，全局名 AIBluekingStandalone。

<link rel="stylesheet" href="/static/ai-blueking/standalone/style.css" />
<div id="ai-root" style="width: 100%; height: 100vh;"></div>
<script src="/static/ai-blueking/standalone/index.iife.min.js"></script>
<script>
  const ai = AIBluekingStandalone.mountAIBlueking('#ai-root', {
    props: {
      url: 'https://your-aidev-url.com/api/',
      enablePopup: true,
    },
    on: {
      sendMessage: function (message) {
        console.log(message);
      },
    },
  });

  // 打开面板
  ai.expose && ai.expose.show();
</script>

UMD / ES 路径

• ESM：@blueking/ai-blueking/standalone → dist/standalone/index.es.min.js
• UMD：dist/standalone/index.umd.min.js
• 类型：dist/standalone.d.ts（import type { StandaloneMountHandle } from '@blueking/ai-blueking/standalone'）

高级：自定义渲染（h / render）

Standalone 同时导出与 bundle 同源 的 h、render、createApp。自定义侧栏、VNode 组合时必须从本入口导入，不要再安装一份外部 vue，否则会出现 VNode 不同源错误。

import { h, render, ChatBot } from '@blueking/ai-blueking/standalone';
import '@blueking/ai-blueking/dist/standalone/style.css';

const container = document.querySelector('#ai-root');
if (container) {
  render(
    h(ChatBot, {
      url: 'https://your-aidev-url.com/api/',
      onError: (err: Error) => console.error(err),
    }),
    container,
  );
}

侧栏 getSideRenderComponent 的 createElement 参数也应使用本入口的 h，详见 侧栏 Tab 自定义渲染。

StandaloneMountHandle API

成员	说明
app	内部 createApp 实例
expose / getExpose()	组件 defineExpose 暴露的方法（如 show、sendMessage）
updateProps(partial)	合并更新 props，不销毁应用
unmount()	卸载并清理

类型：StandaloneMountOptions、StandaloneMountHandle、StandaloneEventHandlers 见 Standalone API。

与默认入口对比

对比项	@blueking/ai-blueking（默认）	@blueking/ai-blueking/standalone
宿主要求	Vue 3 + 安装 chat-x 等 peer	无 Vue 要求
Vue runtime	由宿主提供	打入 bundle
chat-x	peerDependency	内联
集成方式	<AIBlueking> / <ChatBot> SFC	mountAIBlueking / mountChatBot
包体积	较小	较大（约 2.5MB+ gzip 后仍显著大于默认 ES 包）
Vue 2	./vue2 子入口	不支持

注意事项

1. 样式：ES/UMD 需手动引入 dist/standalone/style.css；IIFE 构建会将 CSS 注入 JS（与 Vue3 IIFE 行为一致），仍建议确认页面无样式冲突。
2. 容器：container 支持 CSS 选择器字符串或 Element；找不到节点时抛出 [ai-blueking] mount container not found: ...。
3. expose 时机：挂载后建议 await nextTick() 或短延迟后再调用 expose 上的方法（与 Vue 组件一致）。
4. Slots：非 Vue 宿主无法使用 Vue 插槽语法；需通过 h 传 slot 对象，或使用 mountStandaloneComponent 自行封装（见 API 文档）。

相关文档

• Standalone API
• 编程式控制（Vue 宿主下的 ref / expose）
• ChatBot 页面嵌入（Vue SFC 等价场景）
• AIBlueking 浮窗模式