更新记录
1.0.0(2026-11-22)
- 提供 Android、iOS 的双人及最多 9 人群组语音通话,包含来电接听/拒绝、取消呼叫、挂断、麦克风与扬声器控制、成员状态及说话指示。
- 同一个插件包提供 uni-app x 的
.uvue页面/组件与 uni-app Vue2 / Vue3 共用的选项式.vue页面/组件,支持完整通话容器和受控展示组件。 - 提供自建 LiveKit 的信令参考服务、账号文件/HTTP 身份适配、部署配置和双框架集成说明。
- 提供
9016xxx媒体错误码与本地诊断日志。
平台兼容性
uni-app(5.34)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| √ | √ | - | - | √ | - | √ | √ | - |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| - | - | - | - | - | - | - | - | - | - | - | - |
uni-app x(5.34)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | √ | √ | - | - |
多人语音通话 · hans-rtc-call
基于自建 LiveKit 的双人及群组语音通话插件,提供来电接听/拒绝、取消呼叫、挂断、麦克风与扬声器控制、成员状态、说话指示和通话时长。群通话最多 9 人,包含本人;通话成员必须属于同一个可信群组目录。
uni-app x 与 uni-app 使用同一个 hans-rtc-call 插件包、同一个插件 ID。 安装后保留完整目录,框架会选择对应的 .uvue 或 .vue 页面/组件,无需修改插件 ID、文件扩展名或另装一份媒体插件。
运行环境与集成差异
建议使用 HBuilderX 5.34 或更新版本。插件原生配置最低为 Android API 23、iOS 13.0;随包的 iOS 媒体框架为 arm64 真机版本。
| 项目 | uni-app x | uni-app |
|---|---|---|
| 宿主页面 | .uvue,<script setup lang="uts"> |
Vue2 / Vue3 .vue,共用下文的选项式 JavaScript 示例 |
| 渲染模式 | 普通模式、Vapor | App 的 Vue 页面 |
| 平台 | Android、iOS App | Android、iOS App |
| 内置组件 | 同名 .uvue 实现,easycom 引入 |
同名 .vue 实现,easycom 引入 |
<hans-rtc-call> 容器 |
自动创建原生媒体驱动 | 必须传入 media 适配对象,见下文 |
| 自定义控制页面 | 插件根路径的 createCallBinding + UTS 类型 |
推荐使用 .vue 容器,由容器管理 JavaScript 控制器 |
| 原生媒体 API | 从 @/uni_modules/hans-rtc-call 导入 |
同一路径导入,使用 JavaScript 回调 |
| 内置页路由 | uni_modules/hans-rtc-call/pages/call/index |
相同路由,都不写扩展名 |
| 界面资源 | 保留 static/ui-icons/ |
同样保留,不要只复制组件文件 |
uni-app Vue2 与 Vue3 共用同一套选项式 .vue 页面/组件和媒体适配方式,保留宿主 manifest.json 原有的 vueVersion("2" 或 "3")即可。nvue 不作为本版完整通话 UI 的支持入口。Web、小程序、鸿蒙不提供媒体通话能力,原生 API 返回不支持错误 9016002。
安装与准备
- 将插件安装到宿主的
uni_modules/hans-rtc-call/,保留客户端目录及原生依赖。两种框架都使用这一个目录。 - 真机运行需要包含插件原生依赖的自定义基座;原生依赖更新后需重新制作基座,WGT 不能替换原生 SDK。市场普通授权版按 DCloud 付费 UTS 插件规则使用云端编译/自定义基座。
- 在服务器部署 LiveKit 和随包信令服务。插件内的
server/、deploy/用于服务端,复制到服务器运行,不在手机上执行。详见 部署与账号配置。 - 从业务登录流程取得当前用户的
accessToken;参考服务的文件账号模式可使用setup.mjs生成的账号。双方使用不同账号,并属于相同groupId。
| 参数 | 含义 |
|---|---|
serviceUrl |
信令服务根地址,如 https://rtc.example.com,不加 /v1,不以 / 结尾;不是 LiveKit WebSocket 地址 |
accessToken |
当前用户的业务登录令牌,经 Authorization 请求头发送;不是 LiveKit API Secret 或媒体 JWT |
groupId |
服务端可信群组 ID,1–80 字符 |
inviteeIds / 示例中的 peerId |
成员目录里的业务用户 ID,如 test-user-02,不是电话号码或房间 ID |
serviceUrl 最长 2048 字符,accessToken 最长 8192 字符。媒体地址和短时入会 JWT 由信令服务返回,客户端不签发媒体令牌。不要将登录令牌放入页面 URL、本地持久化存储或日志。
uni-app x 集成示例
下面的 .uvue 页面使用控制器加受控展示组件。替换信令地址与群组,输入当前账号的令牌后,即可监听来电、拨号或加***通话。
<template>
<view class="call-demo">
<view v-if="snapshot.state == 'idle'" class="call-form">
<input v-model="accessToken" password placeholder="当前账号的登录令牌" />
<input v-model="peerId" placeholder="对方业务用户 ID" />
<button @click="listen">监听来电</button>
<button @click="callPeer">发起双人通话</button>
<button @click="joinGroup">加***通话</button>
<text>{{ notice }}</text>
</view>
<hans-rtc-call-view
v-else
:state="snapshot.state"
:mode="snapshot.mode ?? ''"
:peer-name="snapshot.peerName"
:peer-avatar="snapshot.peerAvatar"
:members="snapshot.members"
:duration-seconds="snapshot.durationSeconds"
:microphone-enabled="snapshot.microphoneEnabled"
:speaker-enabled="snapshot.speakerEnabled"
:audio-route="snapshot.audioRoute"
:pending-action="snapshot.pendingAction ?? ''"
:message="snapshot.message"
:safe-top="44"
:safe-bottom="24"
@accept="accept"
@reject="reject"
@cancel="cancel"
@hangup="hangup"
@microphone-change="changeMicrophone"
@speaker-change="changeSpeaker"
@close="close"
/>
</view>
</template>
<script setup lang="uts">
import {
CallController, CallSnapshot, CreateCallBindingOptions,
createCallBinding, createCallSnapshot,
} from '@/uni_modules/hans-rtc-call'
const accessToken = ref('')
const peerId = ref('test-user-02')
const notice = ref('')
const snapshot = ref<CallSnapshot>(createCallSnapshot())
let controller: CallController | null = null
function ensureController(): boolean {
if (controller != null) return true
if (accessToken.value.length == 0) {
notice.value = '请先提供当前账号的登录令牌'
return false
}
const config: CreateCallBindingOptions = {
serviceUrl: 'https://rtc.example.com',
groupId: 'demo-group',
accessToken: accessToken.value,
allowInsecureLocal: false,
showDiagnostics: false,
}
controller = createCallBinding(config, (value: CallSnapshot) => {
snapshot.value = value
})
controller!.startListening()
return true
}
function listen(): void {
if (ensureController()) notice.value = '正在监听来电'
}
async function callPeer(): Promise<void> {
if (ensureController()) await controller!.start('direct', [peerId.value])
}
async function joinGroup(): Promise<void> {
if (ensureController()) await controller!.joinGroup()
}
async function accept(): Promise<void> { await controller?.accept() }
async function reject(): Promise<void> { await controller?.reject() }
async function cancel(): Promise<void> { await controller?.cancel() }
async function hangup(): Promise<void> { await controller?.hangup() }
async function changeMicrophone(enabled: boolean): Promise<void> {
await controller?.setMicrophoneEnabled(enabled)
}
async function changeSpeaker(enabled: boolean): Promise<void> {
await controller?.setSpeakerEnabled(enabled)
}
async function close(): Promise<void> {
const current = controller
controller = null
if (current != null) await current.dispose()
snapshot.value = createCallSnapshot()
notice.value = ''
}
onUnload(() => { close() })
</script>
<style>
.call-demo { flex: 1; }
.call-form { padding: 24px; }
</style>
safe-top、safe-bottom 单位为 px,按宿主导航栏与设备安全区调整。
如需完整容器,可改用 <hans-rtc-call>:uni-app x 只需传 service-url、access-token、group-id,组件挂载后自动监听,无需 media 属性;通过组件 ref 调用下文的通话方法。
uni-app Vue2 / Vue3 集成示例
下面的选项式写法用于 Vue2 和 Vue3。.vue 容器需要显式传入媒体适配对象,尤其是事件方法名映射:onLiveKitEvent → onEvent、offLiveKitEvent → offEvent。
<template>
<view class="call-demo">
<view v-if="!active" class="call-form">
<input v-model="accessToken" password placeholder="当前账号的登录令牌" />
<input v-model="peerId" placeholder="对方业务用户 ID" />
<button @click="listen">监听来电</button>
<button @click="callPeer">发起双人通话</button>
<button @click="joinGroup">加***通话</button>
<text>{{ notice }}</text>
</view>
<hans-rtc-call
v-if="ready"
v-show="active"
ref="call"
class="call-panel"
:service-url="serviceUrl"
:access-token="accessToken"
:group-id="groupId"
:media="mediaAdapter"
:safe-top="44"
:safe-bottom="24"
@statechange="onStateChange"
@closed="onClosed"
/>
</view>
</template>
<script>
import * as rtc from '@/uni_modules/hans-rtc-call'
export default {
data() {
return {
serviceUrl: 'https://rtc.example.com',
groupId: 'demo-group',
accessToken: '',
peerId: 'test-user-02',
ready: false,
active: false,
notice: '',
}
},
computed: {
mediaAdapter() {
/** @type {import('@/uni_modules/hans-rtc-call').CallMediaDriver} */
const media = {
connectRoom: rtc.connectRoom,
disconnectRoom: rtc.disconnectRoom,
setMicrophoneEnabled: rtc.setMicrophoneEnabled,
setSpeakerEnabled: rtc.setSpeakerEnabled,
getParticipants: rtc.getParticipants,
onEvent: rtc.onLiveKitEvent,
offEvent: rtc.offLiveKitEvent,
}
return media
},
},
methods: {
configured() {
if (this.accessToken) return true
this.notice = '请先提供当前账号的登录令牌'
return false
},
listen() {
if (!this.configured()) return
this.ready = true
this.notice = '正在监听来电'
},
async callPeer() {
if (!this.configured()) return
this.ready = true
await this.$nextTick()
await this.$refs.call.start('direct', [this.peerId])
},
async joinGroup() {
if (!this.configured()) return
this.ready = true
await this.$nextTick()
await this.$refs.call.joinGroup()
},
onStateChange(snapshot) {
this.active = snapshot.state !== 'idle'
if (snapshot.message) this.notice = snapshot.message
},
onClosed() {
this.ready = false
this.active = false
this.notice = ''
},
},
}
</script>
<style>
.call-demo { height: 100vh; display: flex; flex-direction: column; }
.call-form { padding: 24px; }
.call-panel { flex: 1; min-height: 0; }
</style>
v-if 控制容器创建和释放,v-show 只控制可见性。挂载后即开始监听;页面卸载时容器清理信令订阅与本人媒体。一个用户的一次通话只交给一个控制器/容器管理,不要同时再创建另一套监听控制器。
不要把 uni-app x 示例的 UTS 类型和脚本原样放进 JavaScript .vue。 两种框架共用媒体 API 和服务端协议,页面语言、控制器承载方式及容器的 media 参数不同。
完整通话容器
两种框架均可用 <hans-rtc-call>。easycom 默认规则下无需手动注册;如项目关闭自动扫描,按宿主框架显式注册对应组件。
| 属性 | 类型 / 默认值 | 用途 |
|---|---|---|
service-url |
string,必填 | 信令服务根地址 |
access-token |
string,必填 | 当前用户的业务登录令牌 |
group-id |
string,必填 | 可信群组 ID |
media |
object | 仅 .vue 容器需要,上文提供完整适配对象 |
request |
function | 仅 .vue 容器可传,默认 uni.request |
microphone-enabled |
boolean / true |
首份通话快照前的显示默认值,不用于预设入会静音 |
speaker-enabled |
boolean / true |
首份通话快照前的显示默认值,实际路由由控制器管理 |
allow-insecure-local |
boolean / false |
仅本地联调时允许 HTTP 信令 |
show-diagnostics |
boolean / false |
开启本地脱敏诊断日志 |
safe-top / safe-bottom |
number / 44、24 |
上下安全区,单位 px |
通过组件 ref 使用以下命令。通话命令返回 Promise<void>,操作结束不等于双方已接通,业务以 statechange 的 snapshot.state 为准。
| 方法 | 用途 |
|---|---|
start('direct', [userId]) |
发起双人呼叫,等待对方接听 |
start('group', userIds) |
创建群呼叫并邀请目录内成员 |
joinGroup() |
创建或加入当前群的活动群通话,无需被叫逐个接听 |
invite(userIds) |
向当前通话追加邀请 |
hangup() |
离开当前通话,群中其他成员可以继续 |
setDiagnostics(enabled) |
切换诊断日志,返回 void |
diagnosticsDump() |
返回本地脱敏日志字符串 |
容器自行处理来电的接听/拒绝,以及取消、挂断和音频开关。statechange 传出完整 CallSnapshot;closed 在关闭界面并清理本人资源后触发,宿主可隐藏组件或返回上一页。hangup() 不等于立即触发 closed,结束界面仍可供用户查看。
当前通话流程入会时默认尝试开启麦克风和扬声器。静音与路由切换使用通话界面或控制器命令,不要仅靠上述两个显示属性控制实际采集。
自定义界面与控制器
<hans-rtc-call-view> 只展示状态并发出操作事件,不会自动连接媒体或监听来电。由宿主提供快照并处理 accept、reject、cancel、hangup、microphone-change(enabled)、speaker-change(enabled)、close;uni-app x 示例已展示这种用法。
uni-app x 从插件根路径导入 createCallBinding(config, onUpdate),返回 CallController。除容器列出的通话命令外,控制器还提供:
| 方法 | 用途 |
|---|---|
startListening() |
开始轮询来电与通话状态,返回 void |
accept() / reject() |
接听或拒绝当前来电 |
cancel() |
取消尚未接听的呼叫 |
setMicrophoneEnabled(enabled) / setSpeakerEnabled(enabled) |
修改当前通话的音频设置 |
refresh() |
主动刷新信令状态 |
snapshot() |
返回当前 CallSnapshot |
reset() |
清空控制器界面状态,不代替退出通话 |
dispose() |
离开通话并释放监听、计时器和本人媒体 |
accept/reject/cancel/refresh/dispose 和音频设置方法返回 Promise<void>,snapshot、reset 为同步调用。页面退出、退出登录或替换账号前释放旧控制器;更换 serviceUrl/groupId/accessToken 时重新创建绑定,避免保留两个账号的会话。
快照提供 state、mode、callId、peerName、peerAvatar、members、durationSeconds、microphoneEnabled、speakerEnabled、audioRoute、pendingAction、message、call。成员类型为 RtcUiViewMember,包含身份、名称、头像、是否本人、麦克风状态、说话状态及成员状态。
常见状态:idle 未通话、outgoing 等待对方接受、incoming 来电、connecting 正在连接媒体、connected 已接通、reconnecting 重连中、ending 正在挂断、ended 已结束、failed 失败。错误提示读取 message。不要用信令 HTTP 200 自行标记已接通,也不要自行累加通话时长。
内置通话页
两种框架都在宿主 pages.json 的 pages 数组加入:
{
"path": "uni_modules/hans-rtc-call/pages/call/index",
"style": {
"navigationBarTitleText": "语音通话",
"navigationStyle": "custom"
}
}
uni-app x 中打开页面:
import { PrepareCallUiPageOptions, prepareCallUiPage } from '@/uni_modules/hans-rtc-call'
function openCallPage(accessToken: string): void {
const config: PrepareCallUiPageOptions = {
serviceUrl: 'https://rtc.example.com',
groupId: 'demo-group',
accessToken,
}
const handoff: string = prepareCallUiPage(config)
uni.navigateTo({ url: '/uni_modules/hans-rtc-call/pages/call/index?handoff=' + handoff })
}
uni-app 中使用相同路由,配置对象用普通 JavaScript:
import { prepareCallUiPage } from '@/uni_modules/hans-rtc-call'
function openCallPage(accessToken) {
const handoff = prepareCallUiPage({
serviceUrl: 'https://rtc.example.com',
groupId: 'demo-group',
accessToken,
})
uni.navigateTo({ url: '/uni_modules/hans-rtc-call/pages/call/index?handoff=' + handoff })
}
配置只在当前 App 进程内存中交接,60 秒有效且只能读取一次。超时、重复打开或 App 重启后需重新生成 handoff。
当前内置页用于打开容器并监听前台来电。 它读取 serviceUrl/groupId/accessToken;给配置增加 mode、callId 或 title 不会自动拨号、恢复旧通话或设置标题。主动呼叫/加***使用前面的页面示例或容器 ref。内置页没有本地 HTTP 调试开关,使用 HTTPS 信令。
原生媒体 API
自行管理媒体时,两种框架都从 @/uni_modules/hans-rtc-call 导入。媒体异步 API 使用 success/fail/complete 回调,区别于控制器的 Promise 命令;不要在完整容器管理的同一通话上重复调用连接/断开 API。
| API | 用途 |
|---|---|
connectRoom / disconnectRoom |
用服务端下发的短时媒体凭据连接/断开房间 |
setMicrophoneEnabled |
发布或关闭麦克风,可配置降噪、回声消除等采集参数 |
setSpeakerEnabled |
设置扬声器偏好,实际输出取决于设备及系统路由 |
getRoomState / getLocalMediaState |
查询连接状态、本地媒体状态 |
getParticipants / getTracks |
查询成员与音轨 |
setTrackSubscribed |
修改远端音轨订阅 |
onLiveKitEvent / offLiveKitEvent |
订阅/取消事件,取消时传原回调引用 |
setLiveKitLogEnabled |
修改原生媒体日志开关 |
uni-app x 调用示例,roomId 使用本次 connectRoom 成功返回的值:
import { SetMicrophoneEnabledOptions, TrackOperationResult, LiveKitFail,
setMicrophoneEnabled } from '@/uni_modules/hans-rtc-call'
function mute(roomId: string): void {
const options: SetMicrophoneEnabledOptions = {
roomId,
enabled: false,
success: (_result: TrackOperationResult): void => {},
fail: (error: LiveKitFail): void => {
console.error(error.errCode, error.errMsg)
},
}
setMicrophoneEnabled(options)
}
uni-app 中移除 UTS 类型注解,使用相同字段和回调。完整参数和结果类型见 interface.uts。语音接入不需要调用摄像头或视频接口。
Android / iOS 配置差异
| 项目 | Android | iOS |
|---|---|---|
| 语音权限 | RECORD_AUDIO,首次启用麦克风时申请 |
NSMicrophoneUsageDescription,首次启用麦克风时申请 |
| 已接通通话的后台音频 | microphone 前台服务与常驻通知 | 最终 App 的 UIBackgroundModes 包含 audio |
| 音频设备 | 插件提供 MODIFY_AUDIO_SETTINGS、BLUETOOTH_CONNECT 等声明 |
插件提供蓝牙用途声明,路由由系统音频会话管理 |
| 局域网 HTTP 联调 | 还需宿主允许调试用明文网络 | 还需宿主配置本地网络权限及调试用 ATS 例外 |
| 自建原生宿主 | 合并插件 Manifest 中的权限、CallAudioService 和服务类型 |
合并插件 Info.plist 的用途声明及后台 audio 模式,嵌入并签名依赖框架 |
插件提供对应声明,自行组装宿主时核对最终应用的合并结果。底层依赖保留摄像头用途声明,本文语音流程不申请摄像头权限。
首次拒绝麦克风权限后,允许权限并重试开启麦克风。“进入通话界面”不代表麦克风一定已发布,读取快照的 microphoneEnabled 与 message。关闭扬声器偏好不保证设备具有听筒,蓝牙/有线耳机输出取决于系统和实际设备。
后台音频用于已经建立的通话。来电监听依赖 App 内的信令轮询,不提供离线来电唤醒、系统电话界面、CallKit/ConnectionService 或厂商离线推送。结束后释放控制器或卸载通话容器。
本地联调
手机与服务端在同一局域网时,将 serviceUrl 改为 http://电脑局域网IP:8787,并在绑定配置设置 allowInsecureLocal: true,或给容器传 :allow-insecure-local="true"。开关只用于本地联调,不代替系统网络权限;生产环境使用 HTTPS/WSS。
手机上的 127.0.0.1 指向手机自身。LiveKit 的 publicUrl 也必须是两台设备可达的地址,不能只修改信令地址。服务端监听地址及端口配置见 部署说明。
错误与排障
媒体错误的 errSubject 为 hans-rtc-call:
| errCode | 处理方式 |
|---|---|
9016001 |
检查服务地址、令牌、房间和参数格式 |
9016002 |
当前平台不提供媒体能力,使用 Android/iOS App |
9016003 |
授予麦克风权限后重试 |
9016004 |
等待当前操作结束,避免重复操作 |
9016005 |
检查媒体地址、证书和网络 |
9016006 |
使用连接成功返回的有效 roomId |
9016007 |
检查音频设备或目标音轨是否可用 |
9016008 |
当前操作已取消 |
9016009 |
连接超时,检查媒体端口、网络及 TURN |
9016010 |
当前版本未实现该能力 |
9016011 |
凭据无效或过期,重新取得登录/入会凭据 |
信令业务错误使用字符串代码:UNAUTHORIZED 检查登录令牌,NOT_GROUP_MEMBER 检查群目录,CALL_BUSY 表示成员正在另一通话,ROOM_FULL 表示人数已满,INVITATION_EXPIRED 表示邀请已过期。UI 提示读取 snapshot.message,这些字符串不是原生 errCode。
| 现象 | 检查项 |
|---|---|
.vue 容器提示缺少媒体对象 |
传入 media,正确映射两个事件方法名 |
| 调用 start 没有动作 | 配置非空;先挂载容器,等待 $nextTick() 再调用 ref |
| 收不到来电 | 当前账号已监听;双方在同群且账号不同;App 进程能继续运行轮询 |
| HTTP 成功但无声音 | 检查媒体连接、双方麦克风状态、LiveKit 可达性和端口 |
| 内置页提示配置失效 | 重新生成 handoff 后立即导航,不能复用旧链接 |
| 图标缺失 | 保留完整 static/ui-icons/,重新编译并检查资源入包 |
| 更新后提示原生模块缺失 | 重新制作包含当前插件的基座,仅更新 WGT 无效 |
排障时可暂时开启 showDiagnostics,用控制器或容器的 diagnosticsDump() 取得本地脱敏日志,完成后关闭。不要输出整个登录配置或媒体凭据响应。

收藏人数:
购买源码授权版(
试用
使用 HBuilderX 导入示例项目
赞赏(0)
下载 403
赞赏 0
下载 12779273
赞赏 1960
赞赏
京公网安备:11010802035340号