@94ai-plus/nf-softphone
v1.0.0-rc.1
Published
Vue 3 and framework-independent micro-frontend adapter for the 94AI online softphone
Maintainers
Readme
@94ai-plus/nf-softphone
HomePage
简介
使用 qiankun(默认)或 wujie 接入九四公共在线网页软电话微前端,支持拨打、进线、转人工、接听、忽略、挂断、小休、网络检测、静音、实时音量追踪、签入签出、聊天文本拉取,语言切换及坐席监控日志上报等能力。通过动作派发与回调通知整合九四在线公共电话条实现现有通用软电话的所有功能。
NfSoftphone适合mvvm架构使用的sfc,如果只需软电话单实例可以采用nfSoftphone默认实例,多实例则通过nfSoftphoneManager工厂new出多实例,多实例之间通过name属性隔离不同的微前端应用
本包合并旧 nf-microphone / nf-microphone-vue 的接入方式,不在本地重写 SIP 电话,也不沿用旧同名 nf-softphone 的 iframe/postMessage 协议。
安装与导入
业务项目的 Vue 版本需满足本包的 peerDependencies(当前为 ^3.5.44)。
npm install @94ai-plus/nf-softphone
# 或 yarn add @94ai-plus/nf-softphoneimport NfSoftphone, { nfSoftphone, nfSoftphoneManager } from '@94ai-plus/nf-softphone'
import '@94ai-plus/nf-softphone/style.css'NfSoftphone(默认导出):原 nf-microphone-vue 的 Vue 3 SFC 封装,适合 Vue/MVVM 架构,内部管理初始化与卸载。nfSoftphone:原 softphoneManager 的默认单例,适合只需一条电话条的库接入。nfSoftphoneManager:原 SoftphoneManager 构造函数;new nfSoftphoneManager()创建独立控制器,适合多实例,通过唯一name隔离微前端应用。
三种入口使用相同的微前端原理,传递 shared 配置并通过具名数据总线执行动作、接收通知。单包和 @94ai-plus/common-ui 总包均导出签名工具、渲染检测方法及对应类型。
Vue 组件接入
下面演示先从业务后端获取签名,再手动初始化。/api/softphone/credentials 是示例业务接口,需替换为自己的后端;返回 appKey、agentTag、sign 和配对的 timestamp,不要把 appSecret 放进前端。
<script setup lang="ts">
import { nextTick, onBeforeUnmount, onMounted, reactive, ref } from 'vue'
import NfSoftphone, { type SoftphoneProps, type SoftphoneSign } from '@94ai-plus/nf-softphone'
import '@94ai-plus/nf-softphone/style.css'
interface Credentials extends SoftphoneSign {
appKey: string
agentTag: string
}
const phone = ref<InstanceType<typeof NfSoftphone>>()
const options = reactive<SoftphoneProps>({ env: 'prod', lang: 'zh' })
const fetching = ref(true)
const requestError = ref('')
let disposed = false
onMounted(async () => {
try {
const response = await fetch('/api/softphone/credentials')
if (!response.ok) throw new Error('获取软电话签名失败')
const credentials: Credentials = await response.json()
if (disposed) return
Object.assign(options, {
appKey: credentials.appKey, agentTag: credentials.agentTag,
sign: credentials.sign, timestamp: credentials.timestamp,
})
// 等待响应式属性刷新,使已挂载的 NfSoftphone 收到最新签名。
await nextTick()
if (!disposed) await phone.value?.initSoftphone()
} catch (error) {
if (!disposed) requestError.value = error instanceof Error ? error.message : String(error)
} finally {
if (!disposed) fetching.value = false
}
})
// 阻止已卸载页面的异步请求继续初始化;子组件会自行销毁微应用。
onBeforeUnmount(() => { disposed = true })
</script>
<template>
<p v-if="fetching">正在获取签名并初始化软电话...</p>
<p v-if="requestError" role="alert">{{ requestError }}</p>
<NfSoftphone ref="phone" v-bind="options" :auto-start="false">
<template #loading>软电话加载中...</template>
<template #error="{ error }"><p role="alert">{{ error.message }}</p></template>
</NfSoftphone>
</template>nextTick() 等待的是属性更新,不是子组件首次挂载。disposed 防止获取签名期间页面被卸载后,异步逻辑仍继续启动电话条。正常卸载时无需再通过 runtime 手动 unmount();组件内部会销毁管理器和微应用。
已有有效签名时,可直接 <NfSoftphone v-bind="options" />,默认在挂载后自动初始化。使用异步 setup/顶层 await 的消费组件时,父级需要提供 <Suspense>;上面的 onMounted 写法不需要异步 setup。
管理类接入:工厂与单例
SoftphoneState.type 使用导出的 SoftphoneMessageType 字面量联合类型,覆盖旧代码中的 14 种初始化/动作/通知消息;单包及总包均可导入。microCommunicat() 的消息名也使用此类型,拼写错误或任意 string 会在类型检查时报错。消息名保留旧协议(包括 softphone-sign-overdued),与 data.type 中的 manual/auto 操作标记不同;此约束不改变运行时收发行为,也不新增动作或推断远程业务数据结构。
工厂接入需要先创建并保留可见的 <div id="phone"></div> 容器;以下 credentials 为业务后端返回的签名配置,与上例一致。
import { nfSoftphoneManager, waitForSoftphoneRender } from '@94ai-plus/nf-softphone'
import '@94ai-plus/nf-softphone/style.css'
const phone = new nfSoftphoneManager()
let disposed = false
let rendering: ReturnType<typeof waitForSoftphoneRender> | undefined
async function disposePhone() {
disposed = true
rendering?.cancel()
await phone.destroy()
}
// 在发起初始化前,将 disposePhone 注册到业务页面的退出/卸载生命周期。
phone.initSoftphone({
...credentials, el: '#phone', env: 'prod', lang: 'zh',
name: 'business-phone', ancestorOrigin: 'business-phone', destinationOrigin: 'business-phone',
})
await phone.ready
if (!disposed) {
rendering = waitForSoftphoneRender(document.querySelector<HTMLElement>('#phone')!)
await rendering.ready // 电话条可见后再结束业务 loading;挂载/渲染错误须 catch。
}
// 按需派发动作(例如签入),不必在每次加载后自动调用。
// phone.connect()只需要一个实例时,用 nfSoftphone 替换 new nfSoftphoneManager();初始化、动作、回调、渲染检测和销毁方式相同。两种接入方式按需选择,不要让多个页面同时控制同一个单例。
import { nfSoftphone } from '@94ai-plus/nf-softphone'
nfSoftphone.initSoftphone({ ...credentials, el: '#phone', name: 'business-phone' })
await nfSoftphone.ready
// 后续在所属页面退出时 await nfSoftphone.destroy()。多实例使用独立的 name / ancestorOrigin / destinationOrigin。签名应由业务后端生成,不要把 appSecret 放进文档、仓库或前端构建。在线电话条须允许 CORS,HTTPS 页面需加载 HTTPS 电话条,并由部署方配置 CSP、麦克风权限及坐席授权。浏览器引擎在初始化时按需加载;SSR 导入和渲染不会连接电话服务。
配置、生命周期与加载状态
| 配置/入口 | 行为 |
| --- | --- |
| mode | 默认 qiankun,也支持 wujie。 |
| env / url / envMap | 默认 prod(国内),sg 为海外;url 可显式指定微应用入口,envMap 可覆盖部署地址,不根据语言自动选区。 |
| lang | 远程电话条语言,默认 zh;如 en、ja 等,以远程应用实际支持为准。 |
| isOem / numberKeyBoard | 默认 true;未传或初始 undefined 沿用管理类默认值,显式 false 可关闭。 |
| autoStart | Vue 组件默认自动初始化;:auto-start="false" 后通过组件 ref 调用 initSoftphone()。 |
| runtime | 自定义微应用接入;mount(config) 从 config.shared.getUserInfo() 读取签名等用户信息,返回 send() 与 unmount()。 |
| ready / error | Vue 组件事件:微前端挂载完成/加载失败;管理类使用 phone.ready、status 和 error 获取状态。 |
| loading / error 插槽 | 自定义加载文案和错误展示;error 插槽接收 { error }。 |
组件保留功能显示开关、事件及实例动作;Vue 2 的 .sync 改为 v-model:sign / v-model:timestamp。
组件加载微前端时显示 loading 插槽,默认文案为“加载中...”(随 CommonUI 语言配置切换);等待电话条可见内容渲染并经过浏览器绘制帧后隐藏,不仅等待微前端挂载,也不等待坐席签入。支持 qiankun 容器、无界 Shadow DOM/可访问的同源 iframe;空容器和隐藏内容不算渲染完成,跨域 iframe 不绕过隔离。挂载失败或挂载后 30 秒仍无可见内容时显示 error 插槽,重试时重新显示加载提示。ready 事件仍表示微前端已挂载、管理器动作可用,不代表电话条已经显示;组件 ref 的 initSoftphone() 还会等待渲染检测。:auto-start="false" 时,调用组件 ref 的 initSoftphone() 后才显示;destroy()/卸载会取消检测并清除加载状态。
<NfSoftphone v-bind="options">
<template #loading>正在加载软电话,请稍候...</template>
</NfSoftphone>加载提示与电话条在同一网格区域叠放:检测完成前由不透明的加载层覆盖正在渲染的电话条,完成后一次性揭开,避免两者同时显示或提示另占一行造成跳动。容器始终保留并可测量,不用 display:none、visibility:hidden 或固定延时判断完成。样式由组件 CSS/Chalk/OEM 主题提供,白黑外观使用 --el-bg-color。
文档中的软电话示例显式传入对应 lang,中文为 zh、英文为 en,其余为 ja/es/id/th/tl/pt,组件和管理类均适用。切换官方文档语言会销毁并重新挂载示例,再由远程应用读取 shared.getLanguage() 初始化;不承诺通话中无损热切换。业务接入仍默认 zh;NfConfigProvider 的顶层 locale 只负责组件库提示文案,不自动映射远程电话条的语言。可通过 nfSoftphone.lang 统一配置远程语言,组件显式 lang 优先;语言不会切换国内/海外环境。
管理类接入时,await phone.ready 仅等待微前端挂载。若需让 loading 持续到电话条显示,可在其后调用 waitForSoftphoneRender(container, timeout?) 并等待返回对象的 ready;默认超时为 30 秒,超时会拒绝 Promise。单包及总包均可导入此方法;卸载时调用返回对象的 cancel() 清理检测(取消会结束等待,需同时用卸载标记避免继续更新界面)。挂载容器必须一直保留且可见,不要随 loading 使用 v-if/v-show 隐藏;失败或超时在 catch 显示错误,在 finally 关闭 loading。完整示例见官网“管理类接入”。
isOem 和 numberKeyBoard 未传或初始传入 undefined 时,沿用 manager 的默认值 true;显式传入 :is-oem="false" / :number-key-board="false" 可关闭对应功能。Vue 包装层不重复定义这些业务默认值,autoStart 仍默认 true。
组件初始化不加载 CryptoJS,也不创建/修改 window.CryptoJS;远程电话条不依赖该全局对象。签名由消费方提供,正式业务应由后端保管 appSecret 并生成签名。
签名与调试工具
调试签名:原生 Web Crypto 与旧浏览器回退
仅限本机联调,公开方法 createSoftphoneSign(appKey, timestamp, appSecret, options?) 返回 Promise<string>,替代 CryptoJS.HmacSHA1(appKey + timestamp, appSecret) 后转 Base64 的写法。单包和 @94ai-plus/common-ui 总包均可具名导入。字符串按 UTF-8 编码,使用标准 Base64(不是 Base64URL);appSecret 不可为空。不要在公开前端部署中嵌入真实 appSecret。
import { createSoftphoneSign } from '@94ai-plus/nf-softphone'
// Capture the timestamp before awaiting; update the signature/timestamp pair together.
const signedAt = Date.now()
const nextSign = await createSoftphoneSign(appKey, signedAt, appSecret)
timestamp.value = signedAt
sign.value = nextSign优先使用 crypto.subtle 的 HMAC/SHA-1(通常要求 HTTPS 或 localhost);原生能力不可用或算法不支持时,才通过 script 加载 CryptoJS。第四参数使用组件相同的 env 标识:{ env: 'sg' } 为海外,默认及其他环境为国内;独立签名方法不读取组件实例、语言或 IP,需要消费方传入一致的环境。
| 签名 options | 默认脚本 |
| --- | --- |
| env: 'sg' | https://seat.teleai.com/CryptoJS.js |
| 默认/dev/test/gray/prod | https://seat.94ai.com/CryptoJS.js |
const nextSign = await createSoftphoneSign(appKey, signedAt, appSecret, { env: 'sg' })已有兼容的 window.CryptoJS 则直接复用,同页并发调用/独立打包副本共享首次发起的加载,不按地区重复下载;15 秒超时、网络/CSP 失败或库接口缺失会拒绝 Promise 并清理加载状态,以便再次尝试,不自动跨区切源。普通原生签名错误不触发回退,也不会把密钥写入错误信息。
回退脚本会提供 window.CryptoJS,但不会覆盖宿主已有实例;已有不兼容对象时明确报错。回退库不再作为 npm 运行时依赖打入组件包。内网/离线环境可用第四参数 { cryptoJsUrl: 'https://trusted.example/crypto-js.js' } 指向自托管可信副本,优先于 env 默认地址;部署方须允许对应 CSP script-src。这里的“旧浏览器”指能运行组件库但缺少 Web Crypto 的环境,并非新增对不支持 Vue 3/组件产物的浏览器的兼容承诺。
显式挂载 window.CryptoJS
第三方 jsDelivr 地址通过 SOFTPHONE_CRYPTO_JS_CDN_URL 常量导出,固定为 https://cdn.jsdelivr.net/npm/[email protected]/crypto-js.js。单包与总包均可导入;仅在显式传入 cryptoJsUrl 时使用,不改变国内/海外默认地址,也不自动作为故障回退源。
import { SOFTPHONE_CRYPTO_JS_CDN_URL, installSoftphoneCryptoJS } from '@94ai-plus/nf-softphone'
await installSoftphoneCryptoJS({ cryptoJsUrl: SOFTPHONE_CRYPTO_JS_CDN_URL })
// createSoftphoneSign 的第四参数同样支持 { cryptoJsUrl: SOFTPHONE_CRYPTO_JS_CDN_URL }。消费方调试旧签名写法时,可调用 installSoftphoneCryptoJS(options?)。即使原生 Web Crypto 可用,也会按需加载并提供 window.CryptoJS;返回 Promise<SoftphoneCryptoJS>,解析后返回值就是该全局实例。必须先 await 再使用,同样支持 env/cryptoJsUrl、已有兼容实例复用、并发去重及失败重试。组件初始化不会调用此方法,也不会在组件卸载时删除共享全局;SSR 调用会拒绝 Promise,SSR 导入不访问浏览器对象。
import { installSoftphoneCryptoJS } from '@94ai-plus/nf-softphone'
// Default: domestic. For overseas, pass { env: 'sg' }.
const CryptoJS = await installSoftphoneCryptoJS()
// CryptoJS === window.CryptoJS; use only test credentials locally.
const sha1 = CryptoJS.HmacSHA1(appKey + timestamp.value, appSecret)
sign.value = CryptoJS.enc.Base64.stringify(sha1)单包及 @94ai-plus/common-ui 总包均可导入;类型中的 window.CryptoJS 为可选,直接访问时请先判空或在安装完成后使用返回值。SoftphoneCryptoJS 类型描述签名所需的 HmacSHA1/Base64 接口。
全局默认配置
通过总包的 NfConfigProvider 的 nfSoftphone 配置项设置默认属性。支持响应式更新和嵌套继承,优先级为组件显式属性 → 最近一层配置 → 外层配置 → 组件原有默认值。undefined 继续继承,false、0 和空字符串保留;按属性合并,数组、对象和函数整体替换,不深度合并。初始化选项仍按组件原有生命周期生效,事件、插槽和原生 attributes 在组件上设置,必填业务数据仍需显式提供。详见全局配置文档。
nfSoftphone 配置项作用于 NfSoftphone Vue 组件;nfSoftphone 单例与 new nfSoftphoneManager() 不读取 Provider,需要在各自的初始化 options 中显式传入配置。远程微应用的入口、语言等初始化配置变更需按原生命周期销毁并重新挂载;全局配置更新不会自动重建实例。
Contributors
感谢每一位参与项目建设的贡献者!
以上为随本版本发布的贡献者统计快照,统计日期与分支见图中说明;仅统计 Git 非合并提交,头像使用姓名首字母,不是 GitLab 个人照片。
License
本项目采用 MIT License 开源许可。
Copyright (c) 2026-present Jiahe Zou, 94 Intelligent Technology Co., Ltd.
