更新记录

1.0.1（2026-05-17）

三端同步日志显示逻辑。

1.0.0（2026-05-16）

初始化版本发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

概述

XF-liveKitUTS 封装了 LiveKit 音视频房间的基础能力，当前提供：

• Android、iOS、Harmony 的 App 原生端音视频连接能力
• 本地音频、视频发布
• 远端音视频订阅
• 本地/远端视频原生渲染组件
• 麦克风、摄像头开关与前后摄切换

说明：当前插件主要面向 uni-app x 项目使用。

模块调用

视频渲染组件示例：

<XF-liveKitUTS :track="snapshot.localVideoTrack" :mirror="true"></XF-liveKitUTS>

客户端调用示例：

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
const snapshot = ref<LiveKitClientSnapshot>(client.getSnapshot())

client.onSnapshot((value : LiveKitClientSnapshot) => {
  snapshot.value = value
})

参数说明

XF-liveKitUTS 组件参数

track

• 类型：LiveKitNativeTrackRef | null
• 描述：要渲染的音视频轨道引用。一般传本地视频轨道或远端视频轨道。

mirror

• 类型：boolean
• 描述：是否镜像显示。前置摄像头本地预览通常传 true，远端视频通常传 false。

插件接口

LiveKitClient

创建 LiveKit 客户端实例。

uni-app x 项目（uvue）中调用示例

import {
  LiveKitClient,
  type LiveKitClientSnapshot,
  type LiveKitConnectOptions
} from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
const snapshot = ref<LiveKitClientSnapshot>(client.getSnapshot())

client.onSnapshot((value : LiveKitClientSnapshot) => {
  snapshot.value = value
})

const options : LiveKitConnectOptions = {
  serverUrl: "wss://your-livekit-server",
  token: "your-livekit-token",
  autoPublishAudio: true,
  autoPublishVideo: true,
  autoSubscribe: true,
  cameraFacing: "user"
}

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

connect

连接 LiveKit 房间。

uni-app x 项目（uvue）中调用示例

import {
  LiveKitClient,
  type LiveKitConnectOptions
} from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

const options : LiveKitConnectOptions = {
  serverUrl: "wss://your-livekit-server",
  token: "your-livekit-token",
  autoPublishAudio: true,
  autoPublishVideo: true,
  autoSubscribe: true,
  cameraFacing: "user"
}

await client.connect(options)

参数说明

serverUrl

• 类型：string
• 描述：LiveKit 服务地址，例如 wss://your-livekit-server

token

• 类型：string
• 描述：LiveKit access token

roomName

• 类型：string
• 描述：可选，房间名。是否生效取决于服务端 token 配置。

identity

• 类型：string
• 描述：可选，用户标识。是否生效取决于服务端 token 配置。

autoPublishAudio

• 类型：boolean
• 描述：可选，是否自动发布本地音频

autoPublishVideo

• 类型：boolean
• 描述：可选，是否自动发布本地视频

autoSubscribe

• 类型：boolean
• 描述：可选，是否自动订阅远端轨道

cameraFacing

• 类型：'user' | 'environment'
• 描述：可选，初始摄像头方向

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

disconnect

退出房间并断开连接。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.disconnect()

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

setMicrophoneEnabled

打开或关闭本地麦克风。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.setMicrophoneEnabled(true)
await client.setMicrophoneEnabled(false)

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

setCameraEnabled

打开或关闭本地摄像头。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.setCameraEnabled(true)
await client.setCameraEnabled(false)

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

switchCamera

切换前后摄像头。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.switchCamera()

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

getSnapshot

获取当前房间状态快照。

返回值说明

返回 LiveKitClientSnapshot，主要字段包括：

• connected：是否已连接
• connectionState：连接状态
• roomName：房间名
• micEnabled：麦克风是否开启
• camEnabled：摄像头是否开启
• cameraFacing：当前摄像头方向
• localAudioTrack：本地音频轨道
• localVideoTrack：本地视频轨道
• participants：参与者列表
• remoteVideoTracks：远端视频轨道列表

uni-app x 项目（uvue）中调用示例

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
const snapshot : LiveKitClientSnapshot = client.getSnapshot()
console.log(snapshot.connectionState)

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

onSnapshot

监听快照推送。

说明：推荐三端统一通过 onSnapshot 被动接收最新快照，页面无需主动调用 getSnapshot() 轮询或同步。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

client.onSnapshot((value : LiveKitClientSnapshot) => {
  console.log(value.connectionState)
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

onSnapshotRefresh

监听“快照已变化”的通知。

说明：该接口保留用于兼容旧写法或特殊场景。常规页面建议优先使用 onSnapshot，不再需要主动调用 getSnapshot() 拉取状态。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
client.onSnapshotRefresh(() => {
  console.log("snapshot changed")
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

onLog

监听插件内部日志输出。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

client.onLog((message : string) => {
  console.log(message)
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

destroy

销毁客户端实例，页面卸载时建议调用。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

onUnmounted(() => {
  client.destroy()
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本