uni-app x live-player 组件完全指南实时音视频拉流播放与 LivePlayerContext 控制【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读live-player是 uni-app xuni-app 下一代跨平台框架在 Android / iOS / 微信小程序等平台上提供的实时音视频拉流播放组件与 DCloud 与七牛云合作的「uni直播」服务配套使用。本文将以 docs/component/live-player.md 为主线完整覆盖该组件的全部属性、枚举值、事件对象、状态码与错误码并结合 docs/api/create-live-player-context.md 与仓库内示例 src/pages/component/live-player/live-player.uvue 的源码实现给出可直接复制运行的完整实战代码帮助读者在 uni-app x 中快速接入 rtmp / hls 直播流并实现播放控制、全屏切换、静音等能力。live-player 组件定位与使用前提live-player组件是 uni直播服务DCloud 与七牛云合作推出的直播服务依托云边一体化架构和海量节点资源构建流媒体服务中的拉流播放组件用于在应用中实时播放音视频直播流。需要注意两点使用前提App 端申请绑定在 Android / iOS 平台使用该组件需要申请绑定包名 / Bundle IDAppID详情可咨询 DCloud 官方渠道。Web / HarmonyOS 暂不支持根据组件兼容性表live-player在 Web 端与 HarmonyOS 端均为不支持状态兼容性表格中标记为x微信小程序自4.41版本起支持Android / iOS 自4.81版本起支持。在仓库示例工程的页面注册文件 src/pages.json 中可以看到该示例页面正是通过条件编译限定平台范围注册的// #ifdef APP-ANDROID || APP-IOS || MP-WEIXIN { path: pages/component/live-player/live-player, group: 0,5,4, style: { navigationBarTitleText: live-player | 实时音视频播放 } }, // #endif这一注册方式与文档兼容性表完全一致组件只在 AppAndroid / iOS与微信小程序平台可用。平台兼容性总览| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | 4.81 | 4.81 | x |表格中的数字代表对应平台最低支持版本号x表示不支持。组件属性详解live-player组件的核心属性如下表所示其中兼容性列沿用文档原始标注x表示不支持| 名称 | 类型 | 默认值 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | src | string(string.VideoURIString) | | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 音视频地址。微信小程序支持 flv, rtmp 格式app平台支持 rtmp, hls 协议 | | mode | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x | live直播RTC实时通话 | | autoplay | boolean | false | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 自动播放 | | muted | boolean | false | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 是否静音 | | orientation | string | vertical | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 画面方向可选值有 verticalhorizontal | | object-fit | string | contain | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 填充模式可选值有 containfillCrop | | background-mute | boolean | false | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 进入后台时是否静音 | | min-cache | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x | 最小缓冲区单位s | | max-cache | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x | 最大缓冲区单位s | | sound-mode | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 声音输出方式 | | auto-pause-if-navigate | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 当跳转到本小程序的其他页面时是否自动暂停本页面的实时音视频播放 | | auto-pause-if-open-native | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 当跳转到其它微信原生页面时是否自动暂停本页面的实时音视频播放 | | picture-in-picture-mode | string/Array | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 设置小窗模式 push, pop空字符串或通过数组形式设置多种模式如 [push, pop] | | picture-in-picture-init-position | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 小窗模式下小窗的初始显示位置格式为 (alignment, y)其中 alignment 表示小窗吸附屏幕左侧还是右侧可选值为 left、righty 代表小窗最顶部所在的屏幕高度百分比 | | enable-auto-rotation | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 是否开启手机横屏时自动全屏当系统设置开启自动旋转时生效 | | referrer-policy | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 格式固定为https://servicewechat.com/{appid}/{version}/page-frame.html其中 {appid} 为小程序的 appid{version} 为小程序的版本号版本号为 0 表示为开发版、体验版以及审核版本版本号为 devtools 表示为开发者工具其余为正式版本 | | enable-casting | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 是否支持投屏。开启后可以通过 LivePlayerContext 上相关方法进行操作 | | duration | number | 0 | | | | initial-time | number | 0 | | | | loop | boolean | false | | | | codec | string | auto | | | | show-play-btn | boolean | true | | | | show-mute-btn | boolean | true | | | | show-fullscreen-btn | boolean | true | | | | show-progress | boolean | false | | | | enable-progress-gesture | boolean | true | | | | poster | string | | | | | controls | boolean | true | | | | show-center-play-btn | boolean | true | | | | show-loading | boolean | true | | |属性使用要点src是唯一必填的业务属性直接决定播放哪个流地址。在仓库示例 src/pages/component/live-player/live-player.uvue 中通过:srcsrc双向绑定到 ref 变量用户可在输入框动态填入播放地址。autoplay、muted、background-mute是 App 端Android 4.81 / iOS 4.81均支持的基础播放控制属性而min-cache、max-cache、sound-mode、picture-in-picture-mode等属性目前仅在微信小程序端4.41生效Android / iOS 端标注为x。orientation、object-fit、sound-mode等枚举型属性的合法值见下文枚举值小节。mode 的属性描述| 合法值 | 兼容性 | | :- | :-: | | RTC | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | | live | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |live表示普通直播场景RTC表示实时音视频通话场景注意当前仅在微信小程序端支持。orientation 的属性描述| 合法值 | 兼容性 | | :- | :-: | | vertical | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x | | horizontal | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x |vertical为竖屏方向horizontal为横屏方向App 端Android / iOS与微信小程序均支持。object-fit 的属性描述| 合法值 | 兼容性 | | :- | :-: | | contain | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x | | fillCrop | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x |contain表示画面完整包含在组件内可能留黑边fillCrop表示以填充并裁剪的方式铺满组件区域。sound-mode 的属性描述| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | speaker | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 扬声器 | | ear | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 听筒 |picture-in-picture-mode 的属性描述| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | [] | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 取消小窗 | | push | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 路由 push 时触发小窗 | | pop | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 路由 pop 时触发小窗 |小窗模式支持通过数组形式设置多种模式例如[push, pop]即路由 push 与 pop 时均触发小窗播放置为空数组[]可取消小窗。referrer-policy 的属性描述| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | origin | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 发送完整的referrer | | no-referrer | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 不发送 |事件与事件对象live-player支持以下事件| 事件名 | 类型 | 兼容性 | 说明 | | :- | :- | :-: | :- | | statechange | (event: UniLivePlayerStatechangeEvent) void | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 播放状态变化事件event.detail {code} | | fullscreenchange | (event: UniLivePlayerFullscreenchangeEvent) void | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 全屏变化事件event.detail {direction, fullScreen} | | error | (event: UniLivePlayerErrorEvent) void | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81 | 错误事件event.detail {errCode, errMsg} | | netstatus | (event: UniEvent) void | Web: x; 微信小程序: 4.41; Android: x; iOS: x | 网络状态通知detail {info} | | audiovolumenotify | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 播放音量大小通知detail {} | | enterpictureinpicture | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 播放器进入小窗 | | leavepictureinpicture | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 播放器退出小窗 | | castinguserselect | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 用户选择投屏设备时触发 detail { state: success/fail } | | castingstatechange | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 投屏成功/失败时触发 detail { type, state: success/fail } | | castinginterrupt | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 投屏被中断时触发 |注意error事件在微信小程序端标注为x错误处理在 App 端Android 4.81 / iOS 4.81可用。UniLivePlayerStatechangeEvent 播放状态变化事件属性值| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniLivePlayerStatechangeEventDetail| 是 | | bubbles | boolean | 是 | | cancelable | boolean | 是 | | type | string | 是 | | target | UniElement | 否 | | currentTarget | UniElement | 否 | | timeStamp | Long | 是 |detail 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | code | number | 是 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 状态码 |code 状态码合法值| 合法值 | 描述 | | :- | :- | | 10000 | 空 | | 10001 | 初始化 | | 10002 | 准备播放 | | 10004 | 播放中 | | 10006 | 停止渲染 | | 10007 | 播放完成 | | 10008 | 播放进度跳转中 | | 10009 | 播放停止 | | 10010 | 播放错误 | | 10011 | 播放结束 | | 10012 | 空 | | 10013 | 资源释放 |在仓库示例 src/pages/component/live-player/live-player.uvue 中正是依据e.detail.code维护了按钮的可用状态当收到10004播放中时置playState为true当收到10006停止渲染、10007播放完成、10009播放停止、10010播放错误、10011播放结束时置playState为false。const statechange (e : UniLivePlayerStatechangeEvent) { console.log(statechange, e); switch (e.detail.code) { case 10004: initState.value false; playState.value true; stopState.value false; break; case 10009: stopState.value true; case 10006: case 10007: case 10010: case 10011: playState.value false; break; } };方法| 名称 | 类型 | 必填 | | :- | :- | :- | | stopPropagation | () void | 是 | | preventDefault | () void | 是 |UniLivePlayerFullscreenchangeEvent 全屏事件属性值| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniLivePlayerFullscreenchangeEventDetail| 是 | | bubbles | boolean | 是 | | cancelable | boolean | 是 | | type | string | 是 | | target | UniElement | 否 | | currentTarget | UniElement | 否 | | timeStamp | Long | 是 |detail 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | direction | string | 是 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 屏幕方向 | | fullScreen | boolean | 是 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 是否全屏 |方法| 名称 | 类型 | 必填 | | :- | :- | :- | | stopPropagation | () void | 是 | | preventDefault | () void | 是 |UniLivePlayerErrorEvent 错误事件属性值| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniLivePlayerError| 是 | | bubbles | boolean | 是 | | cancelable | boolean | 是 | | type | string | 是 | | target | UniElement | 否 | | currentTarget | UniElement | 否 | | timeStamp | Long | 是 |detail 的属性描述| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errCode | number | 是 | 错误码 | | errSubject | string | 是 | 统一错误主题模块名称 | | data | any | 否 | 错误信息中包含的数据 | | cause | Error | 否 | 源错误信息可以包含多个错误详见SourceError | | errMsg | string | 是 | 错误信息描述 |errCode 错误码合法值| 合法值 | 描述 | | :- | :- | | 3001 | 当前视频格式不支持视频无法播放 | | 3002 | 视频解码失败 | | 3003 | 不支持的解码格式 | | 3004 | 重连失败请检查网络情况 | | 3005 | 视频播放失败请检查网络或视频资源 |方法| 名称 | 类型 | 必填 | | :- | :- | :- | | stopPropagation | () void | 是 | | preventDefault | () void | 是 |排查提示遇到播放失败时优先核对src协议是否在平台支持范围内微信小程序支持 flv / rtmpApp 支持 rtmp / hls、网络是否可达、以及直播流源是否正常推流错误码 3004 / 3005 均与网络或资源可达性相关。音视频协议支持支持rtmp、hls协议格式。结合src属性说明各平台可用的协议/格式汇总如下| 平台 | 支持的协议 / 格式 | | :- | :- | | 微信小程序 | flv、rtmp | | AppAndroid / iOS | rtmp、hls |因此在实际项目中应根据目标平台选择拉流地址协议例如需要覆盖 App 与微信小程序两端时可优先准备 rtmp 流仅面向微信小程序时亦可使用 flv 流。LivePlayerContext 上下文对象 API通过uni.createLivePlayerContext(livePlayerId, component?)可创建并返回 live-player 组件的上下文对象LivePlayerContext用于以命令式方式控制播放。完整 API 文档见 docs/api/create-live-player-context.md。createLivePlayerContext 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | x | 4.81 | 4.81 | x |与组件本身的差异createLivePlayerContext在微信小程序端标注为x仅 App 端Android 4.81 / iOS 4.81可用。参数| 名称 | 类型 | 必填 | 兼容性 | | :- | :- | :- | :-: | | livePlayerId | string | 是 | Web: x; 微信小程序: x; HarmonyOS: x | | component | ComponentPublicInstance | 否 | |返回值| 类型 | 描述 | 必备 | | :- | :- | :- | | LivePlayerContext | live-player 组件上下文对象 | 否 |LivePlayerContext 的方法上下文对象提供以下方法每个方法均接受可选的LivePlayerOptions参数包含success、fail、complete三个回调所有方法在 Web / 微信小程序 / HarmonyOS 端均为x仅在 Android 4.81 / iOS 4.81 可用| 方法 | 说明 | 兼容性 | | :- | :- | :- | | play(options?: LivePlayerOptions) : void | 播放 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | | pause(options?: LivePlayerOptions) : void | 暂停 | 同上 | | stop(options?: LivePlayerOptions) : void | 停止 | 同上 | | resume(options?: LivePlayerOptions) : void | 恢复 | 同上 | | mute(options?: LivePlayerOptions): void | 静音 | 同上 | | requestFullScreen(options?: LivePlayerOptions): void | 全屏 | 同上 | | exitFullScreen(options?: LivePlayerOptions): void | 退出全屏 | 同上 |LivePlayerOptions 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | success | (res: UTSJSONObject) void | 否 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 接口调用成功的回调函数 | | fail | (res: UTSJSONObject) void | 否 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 接口调用失败的回调函数 | | complete | (res: any) void | 否 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 接口调用结束的回调函数调用成功、失败都会执行 |在仓库示例 src/pages/component/live-player/live-player.uvue 中上下文对象在页面onReady生命周期中创建并保存onReady(() { context.value uni.createLivePlayerContext(live-player, getCurrentInstance()!.proxy); });注意livePlayerId参数需要与模板中live-player idlive-player的id保持一致。完整实战示例可复制运行以下示例完整取自组件文档并已在仓库 src/pages/component/live-player/live-player.uvue 中落地为 hello uni-app x 示例页面页面注册于 src/pages.json。该示例覆盖了属性配置src / autoplay / muted / object-fit / background-mute / sound-mode / orientation与上下文 APIplay / pause / resume / stop / mute / requestFullScreen / exitFullScreen的完整用法。该 API 不支持 Web请运行 hello uni-app x 到 App 平台体验。template view classuni-flex-item live-player idlive-player classlive-player :srcsrc :autoplayautoplay :mutedmuted :object-fitobjectFit :background-mutebackgroundMute :sound-modesoundMode :orientationorientation statechangestatechange fullscreenchangefullscreenchange errorerror /live-player scroll-view idlive-player-scroll-view classuni-padding-wrap uni-common-mt uni-flex-item view classuni-title text classuni-title-textAPI示例/text /view view classuni-btn-v button typeprimary clickplay :disabledplayState播放/button /view view classuni-btn-v button typeprimary clickpause :disabled!playState暂停/button /view view classuni-btn-v button typeprimary clickresume :disabledinitState || playState || stopState恢复/button /view view classuni-btn-v button typeprimary clickstop :disabled!playState停止/button /view view classuni-btn-v button typeprimary clickmute :disabled!playState静音/button /view view classuni-btn-v button typeprimary clickrequestFullScreen :disabled!playState进入全屏/button /view view classuni-btn-v button typeprimary clickexitFullScreen :disabled!playState退出全屏/button /view view classuni-title text classuni-title-text属性示例/text /view input classinput margin-10 typestring placeholder设置播放地址 confirmonSrcComfirm/input boolean-data title设置是否自动播放 :defaultValueautoplay changeonAutoplayChange/boolean-data boolean-data title设置是否静音 :defaultValuemuted changeonMutedChange/boolean-data boolean-data title设置进入后台时是否静音 :defaultValuebackgroundMute changeonBackgroundMuteChange/boolean-data enum-data title设置填充模式 :itemsobjectFitItemTypes changeonObjectFitChange/enum-data enum-data title设置声音输出方式 :itemssoundModeItemTypes changeonSoundModeChange/enum-data enum-data title设置画面方向 :itemsorientationItemTypes changeonOrientationChange/enum-data /scroll-view /view /template script setup import { ItemType } from /components/enum-data/enum-data-types; const context ref(null as LivePlayerContext | null); const src ref(); const autoplay ref(false); const muted ref(false); const objectFit ref(contain); const backgroundMute ref(false); const soundMode ref(speaker); const orientation ref(vertical); const initState ref(true); const playState ref(false); const stopState ref(false); onReady(() { context.value uni.createLivePlayerContext(live-player, getCurrentInstance()!.proxy); }); const statechange (e : UniLivePlayerStatechangeEvent) { console.log(statechange, e); switch (e.detail.code) { case 10004: initState.value false; playState.value true; stopState.value false; break; case 10009: stopState.value true; case 10006: case 10007: case 10010: case 10011: playState.value false; break; } }; const fullscreenchange (e : UniLivePlayerFullscreenchangeEvent) { console.log(fullscreenchange, e); }; const error (e : UniLivePlayerErrorEvent) { console.log(error, e); }; const isSrcValid () : boolean { const length src.value.length; if (length 0) { uni.showToast({ title: 请输入播放地址, icon: none }); } return length 0; }; const play () { if (!isSrcValid()) return; context.value?.play({ success: (res) { console.log(play, JSON.stringify(res)); }, fail: (err) { console.log(play, JSON.stringify(err)); }, complete: (res) { console.log(play, JSON.stringify(res)); } }); }; const pause () { if (!isSrcValid()) return; context.value?.pause({ success: (res) { console.log(pause, JSON.stringify(res)); }, fail: (err) { console.log(pause, JSON.stringify(err)); }, complete: (res) { console.log(pause, JSON.stringify(res)); } }); }; const resume () { if (!isSrcValid()) return; context.value?.resume({ success: (res) { console.log(resume, JSON.stringify(res)); }, fail: (err) { console.log(resume, JSON.stringify(err)); }, complete: (res) { console.log(resume, JSON.stringify(res)); } }); }; const stop () { if (!isSrcValid()) return; context.value?.stop({ success: (res) { console.log(stop, JSON.stringify(res)); }, fail: (err) { console.log(stop, JSON.stringify(err)); }, complete: (res) { console.log(stop, JSON.stringify(res)); } }); }; const mute () { if (!isSrcValid()) return; context.value?.mute({ success: (res) { console.log(mute, JSON.stringify(res)); }, fail: (err) { console.log(mute, JSON.stringify(err)); }, complete: (res) { console.log(mute, JSON.stringify(res)); } }); }; const requestFullScreen () { if (!isSrcValid()) return; context.value?.requestFullScreen({ success: (res) { console.log(requestFullScreen, JSON.stringify(res)); }, fail: (err) { console.log(requestFullScreen, JSON.stringify(err)); }, complete: (res) { console.log(requestFullScreen, JSON.stringify(res)); } }); }; const exitFullScreen () { if (!isSrcValid()) return; context.value?.exitFullScreen({ success: (res) { console.log(exitFullScreen, JSON.stringify(res)); }, fail: (err) { console.log(exitFullScreen, JSON.stringify(err)); }, complete: (res) { console.log(exitFullScreen, JSON.stringify(res)); } }); }; const objectFitItemTypes [{ value: 0, name: contain }, { value: 1, name: fillCrop }] as ItemType[]; const objectFitItems [contain, fillCrop]; const soundModeItemTypes [{ value: 0, name: speaker }, { value: 1, name: ear }] as ItemType[]; const soundModeItems [speaker, ear]; const orientationItemTypes [{ value: 0, name: vertical }, { value: 1, name: horizontal }] as ItemType[]; const orientationItems [vertical, horizontal]; const onSrcComfirm (event : UniInputConfirmEvent) { let value event.detail.value; if (value ) return; src.value value; console.log(src -, value); }; const onAutoplayChange (value : boolean) { autoplay.value value; console.log(autoplay -, autoplay.value); }; const onMutedChange (value : boolean) { muted.value value; console.log(muted -, muted.value); }; const onBackgroundMuteChange (value : boolean) { backgroundMute.value value; console.log(background-mute -, backgroundMute.value); }; const onObjectFitChange (value : number) { objectFit.value objectFitItems[value]; console.log(object-fit -, objectFit.value); }; const onSoundModeChange (value : number) { soundMode.value soundModeItems[value]; console.log(sound-mode -, soundMode.value); }; const onOrientationChange (value : number) { orientation.value orientationItems[value]; console.log(orientation -, orientation.value); }; const getScrollViewRectForTest () : DOMRect | null { return uni.getElementById(live-player-scroll-view)?.getBoundingClientRect() ?? null; }; defineExpose({ getScrollViewRectForTest }); /script style .live-player { width: 100%; height: 40%; } .input { height: 40px; background: #FFF; padding: 8px 13px; } /style示例代码要点解析上下文获取时机必须在组件渲染完成后onReady生命周期调用uni.createLivePlayerContext并传入组件的id与组件实例否则拿不到有效的LivePlayerContext。按钮状态与播放状态机联动initState/playState/stopState三个 ref 与statechange中的状态码10004 播放中、10006 停止渲染、10007 播放完成、10009 播放停止、10010 播放错误、10011 播放结束联动保证播放 / 暂停 / 恢复 / 停止等按钮在正确的时机可用。地址合法性校验isSrcValid()在每次调用上下文方法前校验src是否为空为空时通过uni.showToast提示请输入播放地址避免无效调用。枚举数据驱动 UIobjectFitItemTypes、soundModeItemTypes、orientationItemTypes以ItemType[]数组形式驱动enum-data组件渲染可选项选择后映射为对应的字符串值写入组件属性清晰展示了枚举型属性的动态切换方式。使用注意事项与排查建议平台限制明确组件在 Web / HarmonyOS 端不可用微信小程序 4.41、App 端 4.81 可用createLivePlayerContext上下文 API 仅 App 端4.81可用。开发时建议按平台做好条件编译或降级提示。App 端需先申请绑定Android / iOS 平台使用live-player需申请绑定包名 / Bundle IDAppID未绑定时可能导致组件无法正常工作。协议匹配平台微信小程序使用 flv / rtmp 格式App 平台使用 rtmp / hls 协议请确保推流端产出的流地址协议与目标平台匹配。错误码对照播放异常时监听error事件依据 errCode30013005区分格式不支持、解码失败、重连失败、网络或资源异常等场景结合 errMsg 与cause字段定位根因。状态机驱动 UI推荐像示例工程一样以statechange的 code 为准维护播放状态避免 UI 按钮状态与播放器真实状态脱节。参见createLivePlayerContext 上下文 API 文档string.VideoURIString 类型说明UniElement 通用元素接口UniEvent 通用事件说明UniError 统一错误规范仓库示例源码src/pages/component/live-player/live-player.uvue示例页面注册src/pages.json【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app x live-player 组件完全指南实时音视频拉流播放与 LivePlayerContext 控制【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读live-player是 uni-app xuni-app 下一代跨平台框架在 Android / iOS / 微信小程序等平台上提供的实时音视频拉流播放组件与 DCloud 与七牛云合作的「uni直播」服务配套使用。本文将以 docs/component/live-player.md 为主线完整覆盖该组件的全部属性、枚举值、事件对象、状态码与错误码并结合 docs/api/create-live-player-context.md 与仓库内示例 src/pages/component/live-player/live-player.uvue 的源码实现给出可直接复制运行的完整实战代码帮助读者在 uni-app x 中快速接入 rtmp / hls 直播流并实现播放控制、全屏切换、静音等能力。live-player 组件定位与使用前提live-player组件是 uni直播服务DCloud 与七牛云合作推出的直播服务依托云边一体化架构和海量节点资源构建流媒体服务中的拉流播放组件用于在应用中实时播放音视频直播流。需要注意两点使用前提App 端申请绑定在 Android / iOS 平台使用该组件需要申请绑定包名 / Bundle IDAppID详情可咨询 DCloud 官方渠道。Web / HarmonyOS 暂不支持根据组件兼容性表live-player在 Web 端与 HarmonyOS 端均为不支持状态兼容性表格中标记为x微信小程序自4.41版本起支持Android / iOS 自4.81版本起支持。在仓库示例工程的页面注册文件 src/pages.json 中可以看到该示例页面正是通过条件编译限定平台范围注册的// #ifdef APP-ANDROID || APP-IOS || MP-WEIXIN { path: pages/component/live-player/live-player, group: 0,5,4, style: { navigationBarTitleText: live-player | 实时音视频播放 } }, // #endif这一注册方式与文档兼容性表完全一致组件只在 AppAndroid / iOS与微信小程序平台可用。平台兼容性总览| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | 4.81 | 4.81 | x |表格中的数字代表对应平台最低支持版本号x表示不支持。组件属性详解live-player组件的核心属性如下表所示其中兼容性列沿用文档原始标注x表示不支持| 名称 | 类型 | 默认值 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | src | string(string.VideoURIString) | | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 音视频地址。微信小程序支持 flv, rtmp 格式app平台支持 rtmp, hls 协议 | | mode | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x | live直播RTC实时通话 | | autoplay | boolean | false | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 自动播放 | | muted | boolean | false | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 是否静音 | | orientation | string | vertical | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 画面方向可选值有 verticalhorizontal | | object-fit | string | contain | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 填充模式可选值有 containfillCrop | | background-mute | boolean | false | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 进入后台时是否静音 | | min-cache | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x | 最小缓冲区单位s | | max-cache | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x | 最大缓冲区单位s | | sound-mode | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 声音输出方式 | | auto-pause-if-navigate | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 当跳转到本小程序的其他页面时是否自动暂停本页面的实时音视频播放 | | auto-pause-if-open-native | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 当跳转到其它微信原生页面时是否自动暂停本页面的实时音视频播放 | | picture-in-picture-mode | string/Array | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 设置小窗模式 push, pop空字符串或通过数组形式设置多种模式如 [push, pop] | | picture-in-picture-init-position | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 小窗模式下小窗的初始显示位置格式为 (alignment, y)其中 alignment 表示小窗吸附屏幕左侧还是右侧可选值为 left、righty 代表小窗最顶部所在的屏幕高度百分比 | | enable-auto-rotation | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 是否开启手机横屏时自动全屏当系统设置开启自动旋转时生效 | | referrer-policy | string | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 格式固定为https://servicewechat.com/{appid}/{version}/page-frame.html其中 {appid} 为小程序的 appid{version} 为小程序的版本号版本号为 0 表示为开发版、体验版以及审核版本版本号为 devtools 表示为开发者工具其余为正式版本 | | enable-casting | boolean | | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 是否支持投屏。开启后可以通过 LivePlayerContext 上相关方法进行操作 | | duration | number | 0 | | | | initial-time | number | 0 | | | | loop | boolean | false | | | | codec | string | auto | | | | show-play-btn | boolean | true | | | | show-mute-btn | boolean | true | | | | show-fullscreen-btn | boolean | true | | | | show-progress | boolean | false | | | | enable-progress-gesture | boolean | true | | | | poster | string | | | | | controls | boolean | true | | | | show-center-play-btn | boolean | true | | | | show-loading | boolean | true | | |属性使用要点src是唯一必填的业务属性直接决定播放哪个流地址。在仓库示例 src/pages/component/live-player/live-player.uvue 中通过:srcsrc双向绑定到 ref 变量用户可在输入框动态填入播放地址。autoplay、muted、background-mute是 App 端Android 4.81 / iOS 4.81均支持的基础播放控制属性而min-cache、max-cache、sound-mode、picture-in-picture-mode等属性目前仅在微信小程序端4.41生效Android / iOS 端标注为x。orientation、object-fit、sound-mode等枚举型属性的合法值见下文枚举值小节。mode 的属性描述| 合法值 | 兼容性 | | :- | :-: | | RTC | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | | live | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x |live表示普通直播场景RTC表示实时音视频通话场景注意当前仅在微信小程序端支持。orientation 的属性描述| 合法值 | 兼容性 | | :- | :-: | | vertical | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x | | horizontal | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x |vertical为竖屏方向horizontal为横屏方向App 端Android / iOS与微信小程序均支持。object-fit 的属性描述| 合法值 | 兼容性 | | :- | :-: | | contain | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x | | fillCrop | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81; HarmonyOS: x |contain表示画面完整包含在组件内可能留黑边fillCrop表示以填充并裁剪的方式铺满组件区域。sound-mode 的属性描述| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | speaker | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 扬声器 | | ear | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 听筒 |picture-in-picture-mode 的属性描述| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | [] | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 取消小窗 | | push | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 路由 push 时触发小窗 | | pop | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 路由 pop 时触发小窗 |小窗模式支持通过数组形式设置多种模式例如[push, pop]即路由 push 与 pop 时均触发小窗播放置为空数组[]可取消小窗。referrer-policy 的属性描述| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | origin | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 发送完整的referrer | | no-referrer | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 不发送 |事件与事件对象live-player支持以下事件| 事件名 | 类型 | 兼容性 | 说明 | | :- | :- | :-: | :- | | statechange | (event: UniLivePlayerStatechangeEvent) void | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 播放状态变化事件event.detail {code} | | fullscreenchange | (event: UniLivePlayerFullscreenchangeEvent) void | Web: x; 微信小程序: 4.41; Android: 4.81; iOS: 4.81 | 全屏变化事件event.detail {direction, fullScreen} | | error | (event: UniLivePlayerErrorEvent) void | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81 | 错误事件event.detail {errCode, errMsg} | | netstatus | (event: UniEvent) void | Web: x; 微信小程序: 4.41; Android: x; iOS: x | 网络状态通知detail {info} | | audiovolumenotify | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 播放音量大小通知detail {} | | enterpictureinpicture | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 播放器进入小窗 | | leavepictureinpicture | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 播放器退出小窗 | | castinguserselect | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 用户选择投屏设备时触发 detail { state: success/fail } | | castingstatechange | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 投屏成功/失败时触发 detail { type, state: success/fail } | | castinginterrupt | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 投屏被中断时触发 |注意error事件在微信小程序端标注为x错误处理在 App 端Android 4.81 / iOS 4.81可用。UniLivePlayerStatechangeEvent 播放状态变化事件属性值| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniLivePlayerStatechangeEventDetail| 是 | | bubbles | boolean | 是 | | cancelable | boolean | 是 | | type | string | 是 | | target | UniElement | 否 | | currentTarget | UniElement | 否 | | timeStamp | Long | 是 |detail 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | code | number | 是 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 状态码 |code 状态码合法值| 合法值 | 描述 | | :- | :- | | 10000 | 空 | | 10001 | 初始化 | | 10002 | 准备播放 | | 10004 | 播放中 | | 10006 | 停止渲染 | | 10007 | 播放完成 | | 10008 | 播放进度跳转中 | | 10009 | 播放停止 | | 10010 | 播放错误 | | 10011 | 播放结束 | | 10012 | 空 | | 10013 | 资源释放 |在仓库示例 src/pages/component/live-player/live-player.uvue 中正是依据e.detail.code维护了按钮的可用状态当收到10004播放中时置playState为true当收到10006停止渲染、10007播放完成、10009播放停止、10010播放错误、10011播放结束时置playState为false。const statechange (e : UniLivePlayerStatechangeEvent) { console.log(statechange, e); switch (e.detail.code) { case 10004: initState.value false; playState.value true; stopState.value false; break; case 10009: stopState.value true; case 10006: case 10007: case 10010: case 10011: playState.value false; break; } };方法| 名称 | 类型 | 必填 | | :- | :- | :- | | stopPropagation | () void | 是 | | preventDefault | () void | 是 |UniLivePlayerFullscreenchangeEvent 全屏事件属性值| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniLivePlayerFullscreenchangeEventDetail| 是 | | bubbles | boolean | 是 | | cancelable | boolean | 是 | | type | string | 是 | | target | UniElement | 否 | | currentTarget | UniElement | 否 | | timeStamp | Long | 是 |detail 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | direction | string | 是 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 屏幕方向 | | fullScreen | boolean | 是 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 是否全屏 |方法| 名称 | 类型 | 必填 | | :- | :- | :- | | stopPropagation | () void | 是 | | preventDefault | () void | 是 |UniLivePlayerErrorEvent 错误事件属性值| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniLivePlayerError| 是 | | bubbles | boolean | 是 | | cancelable | boolean | 是 | | type | string | 是 | | target | UniElement | 否 | | currentTarget | UniElement | 否 | | timeStamp | Long | 是 |detail 的属性描述| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errCode | number | 是 | 错误码 | | errSubject | string | 是 | 统一错误主题模块名称 | | data | any | 否 | 错误信息中包含的数据 | | cause | Error | 否 | 源错误信息可以包含多个错误详见SourceError | | errMsg | string | 是 | 错误信息描述 |errCode 错误码合法值| 合法值 | 描述 | | :- | :- | | 3001 | 当前视频格式不支持视频无法播放 | | 3002 | 视频解码失败 | | 3003 | 不支持的解码格式 | | 3004 | 重连失败请检查网络情况 | | 3005 | 视频播放失败请检查网络或视频资源 |方法| 名称 | 类型 | 必填 | | :- | :- | :- | | stopPropagation | () void | 是 | | preventDefault | () void | 是 |排查提示遇到播放失败时优先核对src协议是否在平台支持范围内微信小程序支持 flv / rtmpApp 支持 rtmp / hls、网络是否可达、以及直播流源是否正常推流错误码 3004 / 3005 均与网络或资源可达性相关。音视频协议支持支持rtmp、hls协议格式。结合src属性说明各平台可用的协议/格式汇总如下| 平台 | 支持的协议 / 格式 | | :- | :- | | 微信小程序 | flv、rtmp | | AppAndroid / iOS | rtmp、hls |因此在实际项目中应根据目标平台选择拉流地址协议例如需要覆盖 App 与微信小程序两端时可优先准备 rtmp 流仅面向微信小程序时亦可使用 flv 流。LivePlayerContext 上下文对象 API通过uni.createLivePlayerContext(livePlayerId, component?)可创建并返回 live-player 组件的上下文对象LivePlayerContext用于以命令式方式控制播放。完整 API 文档见 docs/api/create-live-player-context.md。createLivePlayerContext 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | x | 4.81 | 4.81 | x |与组件本身的差异createLivePlayerContext在微信小程序端标注为x仅 App 端Android 4.81 / iOS 4.81可用。参数| 名称 | 类型 | 必填 | 兼容性 | | :- | :- | :- | :-: | | livePlayerId | string | 是 | Web: x; 微信小程序: x; HarmonyOS: x | | component | ComponentPublicInstance | 否 | |返回值| 类型 | 描述 | 必备 | | :- | :- | :- | | LivePlayerContext | live-player 组件上下文对象 | 否 |LivePlayerContext 的方法上下文对象提供以下方法每个方法均接受可选的LivePlayerOptions参数包含success、fail、complete三个回调所有方法在 Web / 微信小程序 / HarmonyOS 端均为x仅在 Android 4.81 / iOS 4.81 可用| 方法 | 说明 | 兼容性 | | :- | :- | :- | | play(options?: LivePlayerOptions) : void | 播放 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | | pause(options?: LivePlayerOptions) : void | 暂停 | 同上 | | stop(options?: LivePlayerOptions) : void | 停止 | 同上 | | resume(options?: LivePlayerOptions) : void | 恢复 | 同上 | | mute(options?: LivePlayerOptions): void | 静音 | 同上 | | requestFullScreen(options?: LivePlayerOptions): void | 全屏 | 同上 | | exitFullScreen(options?: LivePlayerOptions): void | 退出全屏 | 同上 |LivePlayerOptions 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | success | (res: UTSJSONObject) void | 否 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 接口调用成功的回调函数 | | fail | (res: UTSJSONObject) void | 否 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 接口调用失败的回调函数 | | complete | (res: any) void | 否 | Web: x; 微信小程序: x; Android: 4.81; iOS: 4.81; HarmonyOS: x | 接口调用结束的回调函数调用成功、失败都会执行 |在仓库示例 src/pages/component/live-player/live-player.uvue 中上下文对象在页面onReady生命周期中创建并保存onReady(() { context.value uni.createLivePlayerContext(live-player, getCurrentInstance()!.proxy); });注意livePlayerId参数需要与模板中live-player idlive-player的id保持一致。完整实战示例可复制运行以下示例完整取自组件文档并已在仓库 src/pages/component/live-player/live-player.uvue 中落地为 hello uni-app x 示例页面页面注册于 src/pages.json。该示例覆盖了属性配置src / autoplay / muted / object-fit / background-mute / sound-mode / orientation与上下文 APIplay / pause / resume / stop / mute / requestFullScreen / exitFullScreen的完整用法。该 API 不支持 Web请运行 hello uni-app x 到 App 平台体验。template view classuni-flex-item live-player idlive-player classlive-player :srcsrc :autoplayautoplay :mutedmuted :object-fitobjectFit :background-mutebackgroundMute :sound-modesoundMode :orientationorientation statechangestatechange fullscreenchangefullscreenchange errorerror /live-player scroll-view idlive-player-scroll-view classuni-padding-wrap uni-common-mt uni-flex-item view classuni-title text classuni-title-textAPI示例/text /view view classuni-btn-v button typeprimary clickplay :disabledplayState播放/button /view view classuni-btn-v button typeprimary clickpause :disabled!playState暂停/button /view view classuni-btn-v button typeprimary clickresume :disabledinitState || playState || stopState恢复/button /view view classuni-btn-v button typeprimary clickstop :disabled!playState停止/button /view view classuni-btn-v button typeprimary clickmute :disabled!playState静音/button /view view classuni-btn-v button typeprimary clickrequestFullScreen :disabled!playState进入全屏/button /view view classuni-btn-v button typeprimary clickexitFullScreen :disabled!playState退出全屏/button /view view classuni-title text classuni-title-text属性示例/text /view input classinput margin-10 typestring placeholder设置播放地址 confirmonSrcComfirm/input boolean-data title设置是否自动播放 :defaultValueautoplay changeonAutoplayChange/boolean-data boolean-data title设置是否静音 :defaultValuemuted changeonMutedChange/boolean-data boolean-data title设置进入后台时是否静音 :defaultValuebackgroundMute changeonBackgroundMuteChange/boolean-data enum-data title设置填充模式 :itemsobjectFitItemTypes changeonObjectFitChange/enum-data enum-data title设置声音输出方式 :itemssoundModeItemTypes changeonSoundModeChange/enum-data enum-data title设置画面方向 :itemsorientationItemTypes changeonOrientationChange/enum-data /scroll-view /view /template script setup import { ItemType } from /components/enum-data/enum-data-types; const context ref(null as LivePlayerContext | null); const src ref(); const autoplay ref(false); const muted ref(false); const objectFit ref(contain); const backgroundMute ref(false); const soundMode ref(speaker); const orientation ref(vertical); const initState ref(true); const playState ref(false); const stopState ref(false); onReady(() { context.value uni.createLivePlayerContext(live-player, getCurrentInstance()!.proxy); }); const statechange (e : UniLivePlayerStatechangeEvent) { console.log(statechange, e); switch (e.detail.code) { case 10004: initState.value false; playState.value true; stopState.value false; break; case 10009: stopState.value true; case 10006: case 10007: case 10010: case 10011: playState.value false; break; } }; const fullscreenchange (e : UniLivePlayerFullscreenchangeEvent) { console.log(fullscreenchange, e); }; const error (e : UniLivePlayerErrorEvent) { console.log(error, e); }; const isSrcValid () : boolean { const length src.value.length; if (length 0) { uni.showToast({ title: 请输入播放地址, icon: none }); } return length 0; }; const play () { if (!isSrcValid()) return; context.value?.play({ success: (res) { console.log(play, JSON.stringify(res)); }, fail: (err) { console.log(play, JSON.stringify(err)); }, complete: (res) { console.log(play, JSON.stringify(res)); } }); }; const pause () { if (!isSrcValid()) return; context.value?.pause({ success: (res) { console.log(pause, JSON.stringify(res)); }, fail: (err) { console.log(pause, JSON.stringify(err)); }, complete: (res) { console.log(pause, JSON.stringify(res)); } }); }; const resume () { if (!isSrcValid()) return; context.value?.resume({ success: (res) { console.log(resume, JSON.stringify(res)); }, fail: (err) { console.log(resume, JSON.stringify(err)); }, complete: (res) { console.log(resume, JSON.stringify(res)); } }); }; const stop () { if (!isSrcValid()) return; context.value?.stop({ success: (res) { console.log(stop, JSON.stringify(res)); }, fail: (err) { console.log(stop, JSON.stringify(err)); }, complete: (res) { console.log(stop, JSON.stringify(res)); } }); }; const mute () { if (!isSrcValid()) return; context.value?.mute({ success: (res) { console.log(mute, JSON.stringify(res)); }, fail: (err) { console.log(mute, JSON.stringify(err)); }, complete: (res) { console.log(mute, JSON.stringify(res)); } }); }; const requestFullScreen () { if (!isSrcValid()) return; context.value?.requestFullScreen({ success: (res) { console.log(requestFullScreen, JSON.stringify(res)); }, fail: (err) { console.log(requestFullScreen, JSON.stringify(err)); }, complete: (res) { console.log(requestFullScreen, JSON.stringify(res)); } }); }; const exitFullScreen () { if (!isSrcValid()) return; context.value?.exitFullScreen({ success: (res) { console.log(exitFullScreen, JSON.stringify(res)); }, fail: (err) { console.log(exitFullScreen, JSON.stringify(err)); }, complete: (res) { console.log(exitFullScreen, JSON.stringify(res)); } }); }; const objectFitItemTypes [{ value: 0, name: contain }, { value: 1, name: fillCrop }] as ItemType[]; const objectFitItems [contain, fillCrop]; const soundModeItemTypes [{ value: 0, name: speaker }, { value: 1, name: ear }] as ItemType[]; const soundModeItems [speaker, ear]; const orientationItemTypes [{ value: 0, name: vertical }, { value: 1, name: horizontal }] as ItemType[]; const orientationItems [vertical, horizontal]; const onSrcComfirm (event : UniInputConfirmEvent) { let value event.detail.value; if (value ) return; src.value value; console.log(src -, value); }; const onAutoplayChange (value : boolean) { autoplay.value value; console.log(autoplay -, autoplay.value); }; const onMutedChange (value : boolean) { muted.value value; console.log(muted -, muted.value); }; const onBackgroundMuteChange (value : boolean) { backgroundMute.value value; console.log(background-mute -, backgroundMute.value); }; const onObjectFitChange (value : number) { objectFit.value objectFitItems[value]; console.log(object-fit -, objectFit.value); }; const onSoundModeChange (value : number) { soundMode.value soundModeItems[value]; console.log(sound-mode -, soundMode.value); }; const onOrientationChange (value : number) { orientation.value orientationItems[value]; console.log(orientation -, orientation.value); }; const getScrollViewRectForTest () : DOMRect | null { return uni.getElementById(live-player-scroll-view)?.getBoundingClientRect() ?? null; }; defineExpose({ getScrollViewRectForTest }); /script style .live-player { width: 100%; height: 40%; } .input { height: 40px; background: #FFF; padding: 8px 13px; } /style示例代码要点解析上下文获取时机必须在组件渲染完成后onReady生命周期调用uni.createLivePlayerContext并传入组件的id与组件实例否则拿不到有效的LivePlayerContext。按钮状态与播放状态机联动initState/playState/stopState三个 ref 与statechange中的状态码10004 播放中、10006 停止渲染、10007 播放完成、10009 播放停止、10010 播放错误、10011 播放结束联动保证播放 / 暂停 / 恢复 / 停止等按钮在正确的时机可用。地址合法性校验isSrcValid()在每次调用上下文方法前校验src是否为空为空时通过uni.showToast提示请输入播放地址避免无效调用。枚举数据驱动 UIobjectFitItemTypes、soundModeItemTypes、orientationItemTypes以ItemType[]数组形式驱动enum-data组件渲染可选项选择后映射为对应的字符串值写入组件属性清晰展示了枚举型属性的动态切换方式。使用注意事项与排查建议平台限制明确组件在 Web / HarmonyOS 端不可用微信小程序 4.41、App 端 4.81 可用createLivePlayerContext上下文 API 仅 App 端4.81可用。开发时建议按平台做好条件编译或降级提示。App 端需先申请绑定Android / iOS 平台使用live-player需申请绑定包名 / Bundle IDAppID未绑定时可能导致组件无法正常工作。协议匹配平台微信小程序使用 flv / rtmp 格式App 平台使用 rtmp / hls 协议请确保推流端产出的流地址协议与目标平台匹配。错误码对照播放异常时监听error事件依据 errCode30013005区分格式不支持、解码失败、重连失败、网络或资源异常等场景结合 errMsg 与cause字段定位根因。状态机驱动 UI推荐像示例工程一样以statechange的 code 为准维护播放状态避免 UI 按钮状态与播放器真实状态脱节。参见createLivePlayerContext 上下文 API 文档string.VideoURIString 类型说明UniElement 通用元素接口UniEvent 通用事件说明UniError 统一错误规范仓库示例源码src/pages/component/live-player/live-player.uvue示例页面注册src/pages.json【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
