更新记录

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

隐私、权限声明

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

Android:网络、网络状态、Wi-Fi 状态、Wi-Fi 组播。iOS:本地网络、Bonjour(_airplay._tcp);组播需向 Apple 申请,描述文件具备后再写入插件。鸿蒙:网络、网络信息、Wi-Fi 信息。

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

插件不采集任何数据,不向外部服务器上传。仅在局域网内发现和控制投屏设备。

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

无

暂无用户评论。