更新记录
1.0.2(2026-10-16)
- 改为付费插件:普通授权版 9.90 元,源码授权版 49.90 元。源码授权价低于 100 元,买家无需签署电子协议。
- 构建要求提高到 HBuilderX 4.81:付费(加密)插件在鸿蒙端需 4.81 及以上。
- 三端引擎改为编译产物交付:Android 引擎 jar、iOS
DlnaCast.framework(带.swiftinterface,跨 Xcode 版本可用)、鸿蒙字节码dlna_cast.har。插件内不再包含引擎源码,普通授权版也读不到引擎实现。
1.0.1(2026-10-05)
文档更新
1.0.0(2026-10-02)
1.0.0(2026-10-02)
- Android、iOS、鸿蒙三端统一的投屏接口。
- DLNA 设备搜索、连接、推流播放与全套控制。
- iOS 支持 AirPlay 接收端。
- 支持网络地址与手机本地文件投屏。
- 统一回调结构与错误码。
平台兼容性
uni-app(4.81)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | Android插件版本 | iOS | iOS插件版本 | 鸿蒙 | 鸿蒙插件版本 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | √ | × | × | √ | × | √ | 1.0.1 | √ | 1.0.1 | 5.0.0 | 1.0.1 |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | - | × | × |
msh-dlna-cast
把手机上的媒体推送到同一局域网内的电视、盒子播放。Android、iOS、鸿蒙共用一套接口,iOS 额外支持 AirPlay。
画面和声音在接收端输出。手机负责发现设备、下发播放地址和控制指令。
- 协议:DLNA(UPnP AV);iOS 同时支持 AirPlay
- 媒体:
http/https地址、手机本地文件 - 控制:播放、暂停、继续、从头播放、停止、进度、快进快退、音量、静音
- 适用:uni-app 的 App-vue(Vue3)。不含小程序、H5、nvue、uni-app x
插件带原生配置,必须制作自定义调试基座。标准基座里这些配置不会生效。请用真机,模拟器收不到局域网组播。
引入
将 uni_modules/msh-dlna-cast 放入工程。uni_modules 会自动识别,不必在 manifest.json 里勾选本地插件。
import * as dlna from '@/uni_modules/msh-dlna-cast'
dlna.onDeviceFound((res) => {
if (res.code !== 0) return
console.log(res.data.name, res.data.protocol)
})
dlna.onStateChange((res) => {
if (res.code !== 0) return
console.log(res.data.state, res.data.position, res.data.duration)
})
dlna.startSearch({ timeout: 8000 }, (res) => {
if (res.code === 1001) console.log('未发现设备')
})
dlna.selectDevice({ id: deviceId }, (res) => {
if (res.code !== 0) return
dlna.play({
url: 'https://player.alicdn.com/video/aliyunmedia.mp4',
title: '示例视频',
mimeType: 'video/mp4'
}, (playRes) => {
console.log(playRes.code, playRes.data.url)
})
})
手机与电视必须在同一个 Wi-Fi,路由器未开启 AP 隔离,电视已开启 DLNA / 媒体渲染。
接口
回调统一为 { code, message, data }。成功时 code === 0,message 为 "";无数据时 data 为 {}。
普通方法为 method(options, callback);无参数时为 method(callback)。onDeviceFound、onDeviceLost、onStateChange 为 method(callback),后一次注册覆盖前一次。
除搜索、getLocalIp 和事件注册外,未连接设备时返回 1003。
| 方法 | 作用 | 参数 | 成功时 data |
|---|---|---|---|
startSearch |
开始搜索。设备只从 onDeviceFound 上报 |
{ timeout } 可空,毫秒,默认 8000 |
{} |
stopSearch |
停止搜索 | 无 | {} |
onDeviceFound |
发现一台渲染设备 | 回调 | 设备对象 |
onDeviceLost |
设备离线 | 回调 | { id } |
selectDevice |
连接指定设备,替换当前连接 | { id } 必填 |
设备对象 |
play |
开始播放。已在播放时替换当前媒体 | { url } 必填,{ title, mimeType } 可空 |
{ url } |
pause |
暂停,保留进度 | 无 | {} |
resume |
从当前进度继续 | 无 | {} |
replay |
从头播放 | 无 | {} |
stop |
结束播放,设备选择保留 | 无 | {} |
getState |
播放状态 | 无 | { state } |
getDuration |
总时长 | 无 | { duration } 毫秒 |
getPosition |
当前进度 | 无 | { position, duration } 毫秒 |
getVolume |
当前音量。静音时 volume 仍是静音前的音量 |
无 | { volume, mute } |
setVolume |
音量,绝对值 | { volume } 必填,0–100 的整数 |
{ volume } |
setMute |
静音开关。静音不改音量数值 | { mute } 必填,布尔 |
{ mute, volume } |
seek |
跳到指定位置。大于总时长时停在结尾 | { position } 必填,毫秒,大于等于 0 |
{ position } |
fastForward |
快进 10 秒 | 无 | { position } |
rewind |
快退 10 秒 | 无 | { position } |
getLocalIp |
本机 Wi-Fi IPv4 | 无 | { ip } |
onStateChange |
状态、进度、音量变化 | 回调 | { state, position, duration, volume, mute } |
startSearch 的回调保持不释放,最多两次:启动成功立刻返回 code === 0;本次搜索在 timeout 内一台设备都没有时,再返回 1001。已经发现过至少一台,超时不再返回 1001。搜索进行中再次调用会重新计时。
state 取值:PLAYING、PAUSED、STOPPED、TRANSITIONING、NO_MEDIA、ERROR。
直播或终端不提供时长时 duration 为 0,快进、快退返回 1009。volume 不是 0–100 的整数,或 position 小于 0,返回 1009。
设备对象
{
"id": "设备 UUID",
"name": "客厅电视",
"protocol": "DLNA",
"location": "设备描述地址",
"manufacturer": "厂商",
"model": "型号"
}
protocol 为 DLNA 或 AIRPLAY。Android 与鸿蒙只有 DLNA。字符串没有值时为 ""。
错误码
| code | 含义 |
|---|---|
| 0 | 成功 |
| 1001 | 搜索超时,未发现设备 |
| 1002 | 设备离线或无响应 |
| 1003 | 尚未选择设备 |
| 1004 | 播放失败 |
| 1005 | 缺少必填字段、地址无效,或本地文件不存在 |
| 1007 | 未连接 Wi-Fi,无法取得 IPv4 |
| 1008 | 缺少本地网络或组播权限 |
| 1009 | 当前媒体不支持该操作 |
| 1010 | 网络已切换,连接失效 |
本地文件
url 传以 / 开头的绝对路径,不要带 file://。插件在手机上启动临时 HTTP 服务,成功时 data.url 改为终端能访问的 http 地址。content:// 和其他相对路径返回 1005。
uni.chooseVideo({
sourceType: ['album'],
compressed: false,
success: (res) => {
let path = res.tempFilePath || ''
if (typeof plus !== 'undefined' && plus.io && plus.io.convertLocalFileSystemURL) {
path = plus.io.convertLocalFileSystemURL(path)
}
if (path.indexOf('file://') === 0) path = path.substring(7)
dlna.play({ url: path, title: '本地视频' }, () => {})
}
})
平台
| 平台 | 最低版本 | 协议 |
|---|---|---|
| Android | Android 5.0(API 21) | DLNA |
| iOS | iOS 15 | DLNA、AirPlay |
| 鸿蒙 NEXT | API 12 | DLNA |
搜索只在应用前台进行。页面销毁或 App 退出时停止搜索、停止本地 HTTP 服务,并释放设备连接。
iOS:DLNA 与 AirPlay
| DLNA | AirPlay | |
|---|---|---|
| 选中后 | 插件直接连接 | 先点系统投屏按钮,在系统列表里选定接收端 |
| 音量 | setVolume |
走系统音量。接收端不跟随时,非 0 音量返回 1009,请用接收端音量;0 仍会静音 |
AirPlay 是把视频推到接收端,不是屏幕镜像。
插件已在 utssdk/app-ios/Info.plist 写入本地网络用途说明、Bonjour(_airplay._tcp)和 ATS。云打包时合并进 App,不必在 manifest.json 里再写一遍。
组播权限 com.apple.developer.networking.multicast 当前没有写进 UTS.entitlements。需先向 Apple 申请,描述文件包含该能力后,再写入插件并重新制作基座。描述文件还没有这项时写进 entitlements,签名会失败。
iOS 16 及以上搜不到设备,常见原因是未允许本地网络,或描述文件没有组播权限。
权限与隐私
Android:INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE、CHANGE_WIFI_MULTICAST_STATE。投屏地址为明文 HTTP 时,需开启 usesCleartextTraffic。
iOS:本地网络、组播、Bonjour。不读取 SSID / BSSID。
鸿蒙:ohos.permission.INTERNET、ohos.permission.GET_NETWORK_INFO、ohos.permission.GET_WIFI_INFO。
插件不包含广告,不采集、不上传个人数据。网络行为只发生在局域网:SSDP 搜索、读取设备描述、下发播放与控制。本地文件的临时 HTTP 服务只监听局域网,页面销毁时停止。
常见问题
| 现象 | 处理 |
|---|---|
返回 1001,一台都没有 |
确认同一 Wi-Fi,路由器未开 AP 隔离,电视已开 DLNA |
| 提示插件在标准基座不能生效 | 制作自定义调试基座后再运行 |
返回 1008 |
iOS 允许本地网络并配置组播;Android 确认有组播权限 |
返回 1007 |
手机未连接 Wi-Fi |
返回 1010 |
网络已切换,重新搜索并选择设备 |
部分电视静音返回 1009 |
该电视不支持静音指令 |
AirPlay 调节中间音量返回 1009 |
用接收端自身音量 |
| 本地文件电视打不开 | 电视访问不到手机上的临时 HTTP 服务,确认同一 Wi-Fi |

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