更新记录

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。

安装与准备

  1. 将插件安装到宿主的 uni_modules/hans-rtc-call/,保留客户端目录及原生依赖。两种框架都使用这一个目录。
  2. 真机运行需要包含插件原生依赖的自定义基座;原生依赖更新后需重新制作基座,WGT 不能替换原生 SDK。市场普通授权版按 DCloud 付费 UTS 插件规则使用云端编译/自定义基座。
  3. 在服务器部署 LiveKit 和随包信令服务。插件内的 server/、deploy/ 用于服务端,复制到服务器运行,不在手机上执行。详见 部署与账号配置。
  4. 从业务登录流程取得当前用户的 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() 取得本地脱敏日志,完成后关闭。不要输出整个登录配置或媒体凭据响应。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Voice calls request microphone access. Android declarations: INTERNET, CAMERA, RECORD_AUDIO, MODIFY_AUDIO_SETTINGS, BLUETOOTH_CONNECT, FOREGROUND_SERVICE, FOREGROUND_SERVICE_MICROPHONE. Android calls use an ongoing foreground-service notification. iOS declarations: Camera, Microphone, Bluetooth usage descriptions. Camera declarations are retained for inherited low-level media APIs; the voice call UI does not request camera access. Requires a self-hosted LiveKit server plus the bundled signaling reference server.

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。