voice-widget-sdk

一个轻量的宿主接入包。安装后初始化即可在页面右下角展示一个聊天头像入口，点击后弹出可拖拽的客服窗口，并通过 iframe 承载你们自己的语音客服页面。

适合场景：

• 宿主站点不想直接耦合客服前端实现
• 客服页面独立部署，只需要一个 URL
• 希望入口悬浮、窗口可拖拽、尺寸可配置、并自动适配移动端屏幕

安装

npm install @wanglg/voice-widget-sdk

使用

import { createVoiceWidget } from '@wanglg/voice-widget-sdk';

const widget = createVoiceWidget({
  url: 'https://your-domain.com/voice-web/mobile.html',
  title: '语音客服',
  width: 375,
  height: 600,
  launcherSize: 64,
  themeColor: '#ff6a00',
  accentColor: '#ffb000',
  startOpen: false,
});

// widget.open()
// widget.close()
// widget.toggle()
// widget.destroy()

本地 demo

这个包内置了一个本地调试页，目录也在 packages 下面，不会影响现有应用。

cd packages/voice-widget-sdk
npm run demo

然后打开：

http://127.0.0.1:3200

默认会把 widget 的 iframe 指向：

/voice-web/mobile.html

这个 demo 会把请求自动代理到你本地现有服务：

• /voice-web/* -> http://127.0.0.1:5175
• /api/* -> http://127.0.0.1:8010

所以通常需要先启动：

1. voice-web 的 Vite 开发服务
2. Python 后端接口服务

如果你本地端口不同，也可以在启动 demo 时覆盖：

PORT=3201 VOICE_WEB_DEV_ORIGIN=http://127.0.0.1:5175 VOICE_WIDGET_API_ORIGIN=http://127.0.0.1:8010 npm run demo

默认行为

• 默认入口位置：右下角
• 默认窗口尺寸：375 x 600
• 窗口会根据视口自动收缩，避免超出屏幕
• 打开后显示顶部标题栏，拖拽标题栏即可移动窗口
• iframe 默认带上 microphone 和 autoplay 权限
• 传入普通页面元素 container 时，会自动切换为基于容器的定位模式，适合 PC 中间手机壳这类布局
• themeColor 和 accentColor 会分别控制按钮与标题栏渐变的起点和终点

推荐接入你们当前页面

如果你们现在的语音客服页已经独立部署，比如：

https://your-domain.com/voice-web/mobile.html

那么宿主只需要把这个 URL 传进来即可，不需要把现有语音页面重新写一遍。

参数

| 参数 | 说明 | 默认值 | | --- | --- | --- | | url | 必填，客服页面 URL | - | | title | 头部标题 | 语音客服 | | width | 弹窗宽度 | 375 | | height | 弹窗高度 | 600 | | launcherSize | 头像入口尺寸 | 64 | | themeColor | 主色，影响入口按钮和顶部标题栏渐变起点 | #1C8CFF | | accentColor | 强调色，影响入口按钮和顶部标题栏渐变终点；不传时回退到 themeColor，再回退到默认绿色 | #23C4A8 | | startOpen | 是否初始展开 | false | | enableDrag | 是否允许拖拽 | true | | responsiveMargin | 与屏幕边缘最小间距 | 16 | | avatarUrl | 自定义头像 | 内置渐变图标 | | iframeTitle | iframe title | voice-widget-frame | | allow | iframe 权限声明 | microphone *; autoplay *; clipboard-read *; clipboard-write * | | positionMode | 定位模式，viewport 或 container；显式传 container 时，document.body 也会按容器边界处理 | 自动判断 | | container | 挂载容器；传普通元素或显式指定 positionMode: 'container' 的 document.body 时，会以该容器为边界定位和拖拽 | document.body |

主题配色

createVoiceWidget({
  url: 'https://your-domain.com/voice-web/mobile.html',
  themeColor: '#ff6a00',
  accentColor: '#ffb000',
});

• themeColor：用于入口按钮和顶部标题栏背景渐变的起始色
• accentColor：用于入口按钮和顶部标题栏背景渐变的结束色
• 如果只传 themeColor，accentColor 会自动复用 themeColor，呈现单色系渐变

发布

本目录已经具备 npm 包结构，后续只需要：

npm login
npm publish --access public

当前已经按 scoped package 配置为 @wanglg/voice-widget-sdk。