更新记录

1.0.0（2026-02-28）

• 首次发布。
• 支持 Android / iOS 的 DLNA 基础能力：初始化、设备发现、设备选择、播放控制（播放/暂停/停止）。
• 提供设备发现与错误事件监听能力：onDlnaDeviceFound、onDlnaError、offDlnaListener。
• 提供插件日志开关：setDlnaLogEnabled、isDlnaLogEnabled。

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-dlna

hans-dlna 是一个 uni-app x UTS 插件，用于在局域网内发现 DLNA 设备并执行媒体投放控制。

使用前提

1. 手机与目标 DLNA 设备在同一局域网。
2. 媒体 url 必须能被目标设备直接访问（设备侧可拉取）。
3. 建议先注册监听并初始化，再开始扫描设备。

引入方式

import {
  dlnaInit,
  dlnaDestroy,
  dlnaStartDiscovery,
  dlnaStopDiscovery,
  dlnaGetDevices,
  dlnaSelectDevice,
  dlnaPlay,
  dlnaPause,
  dlnaStop,
  onDlnaDeviceFound,
  onDlnaError,
  offDlnaListener,
  setDlnaLogEnabled,
  isDlnaLogEnabled,
  DlnaDevice,
  DlnaFail,
  DlnaListenerId
} from '@/uni_modules/hans-dlna'

快速开始

import {
  dlnaInit,
  dlnaDestroy,
  dlnaStartDiscovery,
  dlnaStopDiscovery,
  dlnaSelectDevice,
  dlnaPlay,
  onDlnaDeviceFound,
  onDlnaError,
  offDlnaListener,
  DlnaDevice,
  DlnaFail,
  DlnaListenerId
} from '@/uni_modules/hans-dlna'

var deviceFoundListenerId : DlnaListenerId | null = null
var errorListenerId : DlnaListenerId | null = null
const devices = ref<Array<DlnaDevice>>([])
const selectedDeviceId = ref('')

onLoad(() => {
  deviceFoundListenerId = onDlnaDeviceFound((device : DlnaDevice) => {
    const idx = devices.value.findIndex((item : DlnaDevice) : boolean => item.id == device.id)
    if (idx >= 0) {
      devices.value[idx] = device
    } else {
      devices.value.push(device)
    }
  })

  errorListenerId = onDlnaError((err : DlnaFail) => {
    console.error('dlna error', err.errCode, err.errMsg)
  })

  dlnaInit({
    success: () => {
      dlnaStartDiscovery({ timeoutMs: 8000 })
    }
  })
})

function chooseDevice(deviceId : string) {
  dlnaSelectDevice({
    deviceId: deviceId,
    success: (device) => {
      selectedDeviceId.value = device.id
    }
  })
}

function play(url : string) {
  if (selectedDeviceId.value.length == 0) {
    return
  }
  dlnaPlay({
    media: {
      url: url,
      title: 'demo',
      mimeType: 'video/mp4'
    }
  })
}

onUnload(() => {
  dlnaStopDiscovery({})

  if (deviceFoundListenerId != null) {
    offDlnaListener(deviceFoundListenerId!)
    deviceFoundListenerId = null
  }
  if (errorListenerId != null) {
    offDlnaListener(errorListenerId!)
    errorListenerId = null
  }

  dlnaDestroy({})
})

API 说明

所有 API 都是回调风格：

• success(res)：成功回调
• fail(err)：失败回调（DlnaFail）
• complete(result)：完成回调（成功或失败都会触发）

生命周期

• dlnaInit(options)：初始化插件。
• dlnaDestroy(options)：销毁插件并清理内部状态。

发现与设备管理

• dlnaStartDiscovery({ timeoutMs? })：开始扫描，默认 5000ms。
• dlnaStopDiscovery(options)：停止扫描。
• dlnaGetDevices(options)：获取当前设备列表，返回 { devices: DlnaDevice[] }。
• dlnaSelectDevice({ deviceId })：选择目标设备，成功回调返回 DlnaDevice。

播放控制

• dlnaPlay({ media })：播放媒体。
• dlnaPause(options)：暂停播放。
• dlnaStop(options)：停止播放。

media 字段：

• url: string（必填）
• title?: string
• mimeType?: string（默认 video/mp4）

事件监听

• onDlnaDeviceFound(callback)：监听发现到的设备，返回 listenerId。
• onDlnaError(callback)：监听插件内部错误，返回 listenerId。
• offDlnaListener(listenerId)：按 listenerId 解绑监听。

日志控制

• setDlnaLogEnabled(enabled: boolean)：设置插件日志开关。
• isDlnaLogEnabled()：读取当前插件日志开关状态。

示例：

setDlnaLogEnabled(true)
console.log('plugin log enabled:', isDlnaLogEnabled())

错误码

• 90010001：参数错误（如 deviceId 或 media.url 为空）
• 90010002：未初始化
• 90010003：未选择设备
• 90010004：设备发现失败
• 90010005：SOAP 调用失败
• 90010006：网络不可用 / 初始化失败
• 90010007：请求超时
• 90010008：平台不支持

权限说明

Android

插件已声明以下权限：

• android.permission.INTERNET
• android.permission.ACCESS_NETWORK_STATE
• android.permission.ACCESS_WIFI_STATE
• android.permission.CHANGE_WIFI_MULTICAST_STATE

iOS

宿主工程需要补充：

• NSLocalNetworkUsageDescription（本地网络权限用途说明）