更新记录

1.0.16（2026-07-08）

• 将 uni-app / uni-app x 示例默认视频源从会跳转到 HTTPS 的 media.w3.org 地址换成真机验证过的普通 HTTP MP4 http://vjs.zencdn.net/v/oceans.mp4，并补充 Macast(yunxi) 与 Windows 自带 yunxi 设备的 716 排查说明，避免把 Macast 接收器误选成 Windows Digital Media Renderer。
• 修复 iOS 不使用内置面板、直接点击设备或业务自定义面板选择设备时反馈不明显的问题：示例页新增 CONNECT_DEVICE_CLICK、CONNECT_DEVICE_BEFORE_NATIVE_CALL、CONNECT_DEVICE_AFTER_NATIVE_CALL 日志，并在连接成功后刷新诊断与设备状态。
• 加固 uni-app / uni-app x 示例设备列表刷新：getDiscoveredDevices() 短暂返回空数组时保留已发现设备，避免 deviceListChange 已发现设备后列表又被空查询清空。
• 加固 iOS 连接事件同步：DLNA 连接成功后额外派发包含 connected 状态的 deviceListChange，便于客户自定义 UI 只监听设备列表事件时也能更新“已连接”状态。
• 修复 iOS 点击“开始投屏”前执行媒体预检时，CastMediaInspection 强类型 success 回调被 Swift 桥接层误强转为 (Any) -> Void 导致 SIGABRT 闪退的问题。
• 强化 iOS 回调分发：CastFail、CastSupportBundle、CastMediaInspection 统一走强类型直接回调，避免 success / fail / complete 在不同 API 结果类型之间复用 any 回调桥引发原生崩溃。
• 加固 iOS 连接 Macast(yunxi) / Windows DMR 后开始投屏返回 HTTP 500 的兼容风险：DLNA DIDL-Lite 元数据改为与 Android 对齐的 parentID="-1" 与 protocolInfo="http-get:*:<mime>:*"，并增强 SOAP 错误日志输出真实 action 与 UPnP fault，便于区分接收端资源不可访问和协议元数据不兼容。
• 加固 iOS SetAVTransportURI 对 Macast 0.7 / CherryPy 旧接收端的兼容性：SOAP POST 使用 URLSession.uploadTask 显式发送 UTF-8 请求体，并补齐 Content-Length、Connection: close 和 Accept:*/*，避免接收端将 dataTask + httpBody 识别为空 body；在 SetAVTransportURI 收到 5xx 时短延迟重试一次；HTML 500 响应日志截断提高到 4096 字符，便于客户复制 Macast traceback。
• 继续加固 iOS SetAVTransportURI 对 Macast(yunxi) 与 Windows Digital Media Renderer 的控制请求兼容：解析 controlURL 时保留 ?control= 查询串，避免 Windows DMR 因 udhisapi.dll%3Fcontrol=... 返回 Invalid Header；普通 HTTP SOAP POST 改为原始 HTTP/1.1 POST 写入 header、空行和 UTF-8 body，避免 Macast 0.7 继续读到空 XML body。
• 加固 iOS 连接 Windows Digital Media Renderer 后点击“投屏当前媒体”返回 UPnP 716 Resource not found 的兼容性：主路径继续使用 protocolInfo="http-get:*:<mime>:*"，仅在 SetAVTransportURI 明确返回 716 时自动尝试 Windows DMR 备用元数据 DLNA.ORG_OP=01;DLNA.ORG_CI=0;DLNA.ORG_FLAGS=01700000000000000000000000000000 和空元数据，减少接收端把可访问普通 HTTP MP4 误判为资源不可用的概率。
• 补充 uni-app / uni-app x 示例日志：新增 START_CAST_CLICK、START_CAST_BEFORE_NATIVE_CALL、START_CAST_AFTER_NATIVE_CALL、CAST_MEDIA_INSPECTION_BEFORE_NATIVE_CALL、CAST_MEDIA_INSPECTION_AFTER_NATIVE_CALL，便于客户复现“连接后开始投屏”时定位按钮链路。
• 升级发布版本到 1.0.16，同步 package.json、商业就绪状态和 Android/iOS/Harmony/API 运行诊断版本；iOS 真机诊断 version 必须显示 1.0.16 才代表同时包含自定义 UI 连接反馈、列表保留和开始投屏闪退修复。

1.0.15（2026-07-06）

• 修复 iOS 自动 SSDP 已发现设备但示例页设备列表仍显示为空的问题：deviceListChange 事件 payload 会优先同步到 uni-app / uni-app x 示例页设备列表，不再被后续空查询覆盖。
• 加固 iOS 运行态设备快照：getDiscoveredDevices / getCastDiagnostics 从 native 快照同步到空数组时，会保留 UTS 层已通过 deviceListChange 写入的真实 DLNA 设备，避免诊断仍显示 deviceCount:0。
• 升级发布版本到 1.0.15，同步 package.json、商业就绪状态和 Android/iOS/Harmony/API 运行诊断版本，便于客户确认已包含本轮设备列表显示修复。
• 本版本仍属于 iOS 已授权 Multicast 自动 SSDP 构建，客户需要使用包含 com.apple.developer.networking.multicast 的 provisioning profile 重新打 iOS 自定义基座。

1.0.14（2026-07-06）

• 单独升级已获 Apple Multicast Networking 权限客户的 iOS 自动 SSDP 搜索版本：包版本、商业就绪状态和 Android/iOS/Harmony/API 运行诊断版本统一到 1.0.14。
• 开启 iOS 自动 SSDP 搜索：iosAutomaticSsdpEnabledByDefault 改为 true，在未传 manualDeviceDescriptionUrl 时会直接进入 CastScreenNative.startDiscovery，不再返回 ios-multicast-entitlement-required 保护提示。
• iOS UTS.entitlements 内置 com.apple.developer.networking.multicast，用于客户已开通 App ID、重新生成 provisioning profile 并重新打 iOS 自定义基座后的自动搜索验收。
• 更新 README 和发布守卫，明确 1.0.14 适用于描述文件已包含 Multicast Networking 的构建；未获批客户仍应使用手动 device.xml/description.xml 链路或不声明 multicast 的保护构建。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-cast-screen

lizhao-cast-screen 是一个面向 uni-app / uni-app x 的商业级 UTS 媒体投屏插件。插件最大特色是内置暗黑科技风投屏面板：底部近全屏呈现、深浅色主题、设备扫描、选集、清晰度、投屏成功后的进度控制、音量、快进快退和断开控制都在插件内部完成；业务也可以通过事件完全自定义界面。

功能特色

• Android 使用 DLNA/UPnP 实现媒体投屏：支持 SSDP 搜索、设备去重、连接、播放普通 http MP4 / https 远程视频 URL，也支持 image/jpeg 等远程图片 URL 投屏；视频保留暂停、恢复、seek、音量、停止和断开，图片不伪造视频控制。
• iOS 新增 DLNA/UPnP DMR 媒体投屏：支持 SSDP 搜索、手动 device.xml 发现、AVTransport / RenderingControl SOAP 控制、远程视频/图片投屏、视频暂停、恢复、seek、音量、停止和进度快照；同时保留系统 AirPlay 路由入口，不做私有 AirPlay 反射，图片请走 DLNA 设备。
• Harmony 新增 DLNA/UPnP DMR 媒体投屏：支持 SSDP 搜索、手动 device.xml 发现、AVTransport / RenderingControl SOAP 控制、远程视频/图片投屏、视频暂停、恢复、seek、音量、停止、进度快照、诊断包和媒体源预检；内置面板优先使用 Android 风格 ArkUI 近全屏底部 Sheet，承接搜索、选设备、投屏、3D 遥控控制台、音量加减、快退/快进和胶囊选集/清晰度，UIContext 不可用时降级到系统 ActionSheet。
• iOS 内置底部近全屏面板新增 DLNA 设备 / AirPlay 路由 分段切换：DLNA 页提供设备列表、扫描入口、投屏当前媒体、暂停/恢复、停止和断开控制；AirPlay 页保留 AVRoutePickerView 系统路由入口，AirPlay 设备选择仍交给系统完成。
• 内置面板状态基础矩阵覆盖搜索中、设备列表、连接中、已连接、投屏中、已暂停、已停止、无设备、失败可重试，并额外支持投屏请求中加载态；面板只展示真实状态，不伪造设备发现、连接或投屏成功；Android 点击“投屏”后会立即显示“投屏中...”并禁用重复点击，投屏成功后主按钮切换为“暂停”，暂停后显示“播放”，停止后显示“继续投屏”；进度条只在真实投屏媒体建立且有明确时长后显示，Android 投屏成功后通过 GetPositionInfo 异步轮询电视端真实进度，轮询期间只轻量刷新当前时间和进度条，暂停/播放/停止只轻量刷新状态文案和按钮，避免整面板重建造成界面闪动；Android/iOS 支持拖拽后触发真实 seekCast。
• 连接设备后自动切换为紧凑产品级控制台和暗黑科技风微光媒体控制台，提供玻璃卡片、发光控制盘、选集、清晰度、顶部单图标主题按钮、快退 15 秒、快进 15 秒、音量加减、投屏当前媒体和原地刷新。
• 标题右侧扫描设备入口默认可用，不再展示“使用业务自定义界面”按钮；业务自定义入口请使用 showCastPanel({ useBuiltinUI: false }) 与事件回调。
• 支持 dark / light / auto 主题。auto 跟随系统，dark 适合影音投屏场景，light 适合浅色业务页面。
• 提供 getCastDiagnostics、exportCastSupportBundle、inspectCastMediaSource，方便线上诊断设备、媒体源和投屏状态。

支持平台

插件市场平台标记说明

插件市场平台标记会按 uni-app / uni-app x 跨端可安装和可调用能力展示；真实投屏能力仍按“真实投屏能力”标记和说明：App Android / App iOS / App Harmony 支持原生 DLNA/UPnP（iOS 额外提供 AirPlay 系统路由入口），Web/H5、小程序和快应用只提供统一 API 与降级入口。源码中保留 app-harmony、web、mp-weixin、mp-alipay 平台目录，是为了让业务可以获得一致 API 和 useBuiltinUI:false 自定义入口；其中 Harmony 端具备真实 DLNA 投屏能力，Web/H5 与小程序端不代表可以真实发现设备或投屏成功。

安装说明

1. 将插件放入项目的 uni_modules/lizhao-cast-screen 目录。
2. 页面中只从插件根目录导入，不要导入 utssdk 子路径。
3. App Android / App iOS / App Harmony 使用真实原生能力时，需要重新制作并安装自定义基座。
4. H5、小程序可以调用同名 API 获取降级能力，但不要在 UI 中声明真实投屏成功。

import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

如只需要类型，也可以从根入口使用公开类型；插件内部 utssdk/api.uts 是 API 汇总实现文件，业务页面仍应从插件根目录导入。

示例代码位置

插件内部已内置完整演示页面：

uni_modules/lizhao-cast-screen/example/uniapp/castScreen.vue
uni_modules/lizhao-cast-screen/example/uniappx/index.uvue

使用方式：

1. uni-app 项目可参考 uni_modules/lizhao-cast-screen/example/uniapp/castScreen.vue，复制到项目页面目录，例如 uni_modules/lizhao-cast-screen/example/uniapp/castScreen.vue。
2. uni-app x 项目可参考 uni_modules/lizhao-cast-screen/example/uniappx/index.uvue，页面仍只从插件根目录导入 API 和类型。
3. 在 pages.json 中增加页面路由。
4. App 端真实投屏能力需要重新运行到自定义基座；如果本轮只复制页面、不改插件原生代码，可以先运行页面验证 UI 与 API 调用。

{
  "pages": [
    {
      "path": "uni_modules/lizhao-cast-screen/example/uniapp/castScreen",
      "style": {
        "navigationBarTitleText": "投屏控制演示"
      }
    }
  ]
}

示例页包含：内置面板、业务自定义面板、扫描设备、连接设备、开始投屏、投屏图片、暂停/恢复、seek、音量、停止、诊断包和媒体源预检。uni-app 示例位于 uni_modules/lizhao-cast-screen/example/uniapp/castScreen.vue，uni-app x 示例位于 uni_modules/lizhao-cast-screen/example/uniappx/index.uvue，便于用户安装插件后直接参考。

快速开始

import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

CastScreen.initCast({
  debug: true,
  autoStartDiscovery: false,
  success() {
    console.log('投屏插件初始化完成')
  },
  fail(err) {
    console.log('投屏插件初始化失败', err)
  }
})

const capabilities = CastScreen.getCastCapabilities()
console.log('投屏能力', capabilities)

展示内置投屏面板

CastScreen.showCastPanel({
  title: '投屏到电视',
  subtitle: '请选择同一 Wi-Fi 下的设备',
  theme: 'auto',
  media: {
    url: 'http://vjs.zencdn.net/v/oceans.mp4',
    title: 'Oceans HTTP MP4',
    mimeType: 'video/mp4'
  },
  episodes: [
    {
      id: 'ep-1',
      title: '第 1 集 Sintel 预告',
      url: 'http://vjs.zencdn.net/v/oceans.mp4',
      mimeType: 'video/mp4',
      episodeIndex: 1
    },
    {
      id: 'ep-2',
      title: '第 2 集 Big Buck Bunny',
      url: 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
      mimeType: 'video/mp4',
      episodeIndex: 2
    }
  ],
  qualities: [
    { id: 'auto', label: '自动', selected: true },
    { id: '720p', label: '720P', url: 'http://vjs.zencdn.net/v/oceans.mp4', mimeType: 'video/mp4' },
    { id: '1080p', label: '1080P' }
  ],
  showThemeToggle: true,
  success() {
    console.log('内置投屏面板已展示')
  }
})

浅色主题示例：

CastScreen.showCastPanel({
  theme: 'light',
  title: '投屏到会议屏',
  subtitle: '浅色业务页面推荐使用 light 主题'
})

选集或清晰度项带 url 时，用户点击对应项会触发真实 startCast 流程；如果不带 url，插件只派发 customAction 给业务层，不会伪造投屏成功。

投屏图片示例

CastScreen.startCast({
  media: {
    // 图片必须是电视/盒子可直接访问的远程 URL，本地相册路径需要先上传或转换为可访问地址。
    url: 'https://media.w3.org/2010/05/sintel/poster.png',
    title: '投屏图片示例',
    mediaKind: 'image',
    mimeType: 'image/jpeg'
  },
  success() {
    console.log('图片投屏已发送到 DLNA 设备')
  },
  fail(err) {
    console.log('图片投屏失败', err)
  }
})

图片投屏在 DLNA 元数据中使用 object.item.imageItem.photo；视频仍使用 object.item.videoItem。图片没有播放时长，不会触发视频进度、暂停、恢复或 seek 控制。

业务自定义界面示例

CastScreen.onCastEvent('*', (event) => {
  if (event.name == 'customAction') {
    console.log('业务自定义事件', event.payload)
  }
  if (event.name == 'deviceListChange') {
    console.log('设备列表变化', event.payload)
  }
})

CastScreen.showCastPanel({
  useBuiltinUI: false,
  title: '业务自定义入口',
  showCustomAction: true,
  customActionText: '打开业务投屏弹窗'
})

useBuiltinUI:false 在降级端也可以触发业务入口；但如果能力矩阵返回 supported:false，请在业务 UI 中提示“当前平台暂不支持真实投屏”，不要伪造设备发现或投屏成功。 iOS 真机建议业务自定义入口同时传入 showCustomAction:true 或 customActionText，避免可选布尔字段在桥接默认值中与内置面板调用混淆。

API 列表

完整 API 行为速查

事件说明

事件回调签名为 (event: CastEvent) => void，eventName 为字符串。推荐传入 CastEventName 中的事件名，或传入 * 监听全部事件。

initCast(options)

说明 初始化投屏运行时，可选自动启动搜索。

参数

startDiscovery(options)

说明 开始搜索投屏设备。Android/iOS/Harmony 会搜索 DLNA DMR；模拟器、企业网络或组播受限时，可传 manualDeviceDescriptionUrl 指向已知 device.xml。iOS 的 AirPlay 仍通过系统路由入口选择，不做私有协议扫描。

参数

showCastPanel(options)

说明 展示插件内置投屏面板。Android/iOS 是原生底部近全屏面板；Harmony 使用 ArkUI openBindSheet 底部近全屏面板承接搜索设备、选择设备、投屏当前媒体、状态卡、媒体进度、音量、3D 遥控控制台、选集、清晰度、暂停、恢复、停止、断开和状态查看；当窗口 UIContext 暂不可用时会降级到系统 ActionSheet，降级端建议用 useBuiltinUI:false 触发业务自定义入口。Android 点击“投屏”后先进入“投屏中...”加载态，成功后主按钮按播放状态显示“暂停/播放”；停止只停止远端播放，不断开设备，面板会切到“继续投屏”并可复用当前媒体继续投屏；进度条不会在未投屏或已停止时提前展示；Android 投屏成功后会按秒异步轮询 DLNA GetPositionInfo，只有电视端返回 positionSupported=true 时才推进面板进度；Android/iOS 在投屏成功且有时长后可拖拽进度条，松手后走真实 seekCast。

参数

选集或清晰度项带 url 时，点击对应按钮会派发 customAction，并尝试调用真实投屏流程；不带 url 时只派发业务事件，不会伪造投屏成功。业务可以把接口返回的播放历史通过 currentTime / duration 传给内置面板，作为投屏前展示和起播位置；真正进入投屏会话后，Android 面板优先使用电视端 GetPositionInfo 返回的真实播放进度，不再让业务起播点长时间冒充远端播放进度。

startCast(options)

说明 开始投屏远程媒体 URL。当前支持电视/盒子可访问的 http/https 视频和图片地址；图片建议显式传 mediaKind:'image'。

参数

seekCast(options)

setCastVolume(options)

getCastDiagnostics(options?)

Harmony SSDP 诊断字段

exportCastSupportBundle(options?)

inspectCastMediaSource(options)

返回值说明

CastCapabilities

CastSessionState

会话进度快照来源：Android、iOS DLNA 和 Harmony 优先通过 GetPositionInfo 获取 RelTime / TrackDuration；Android 内置面板投屏成功后会异步轮询该快照，暂停、停止和断开时停止轮询；iOS AirPlay 路径通过 AVPlayer.currentTime 与媒体时长同步。

CastMediaInspection

错误码

权限说明

Android 需要以下权限，插件已在 AndroidManifest.xml 声明：

iOS 使用 DLNA/UPnP 局域网发现与 SOAP 控制，同时保留 AirPlay 系统路由和 AVPlayer 外部播放能力；不做私有 AirPlay 扫描。1.0.16 面向已获 Apple Multicast Networking 授权的 iOS 构建，默认保留 NSLocalNetworkUsageDescription、ATS 本地网络例外，并在 UTS.entitlements 内置 com.apple.developer.networking.multicast，点击搜索会进入真实 SSDP 组播发现。业务必须确认 App ID 已启用 Multicast Networking、provisioning profile 已重新生成且云打包选择的是该新描述文件；未获批客户请继续使用 manualDeviceDescriptionUrl 指向已知 device.xml 验证 DLNA 解析与 SOAP 控制链路，或使用不声明 multicast 的保护构建。

Harmony 使用 DLNA/UPnP 局域网发现与 SOAP 控制，需要在 utssdk/app-harmony/module.json5 声明 ohos.permission.INTERNET，用于访问 DLNA device.xml、SSDP/UDP 搜索和 SOAP 控制地址。

原生配置文件

Android 9/API 28+ 默认限制明文 HTTP，而许多 DLNA DMR 设备描述和控制地址仍是局域网 HTTP，所以插件配置了 lizhao_cast_screen_network_security_config。这只用于 DLNA/UPnP 局域网能力，不建议业务把所有公网请求都放开为 cleartext。

iOS 的 App Transport Security 针对 DLNA/UPnP 本地网络与 AirPlay 接入做边界说明，包含 NSAllowsLocalNetworking，不建议在业务中无差别放开 NSAllowsArbitraryLoads。若 iOS 自动搜索只能看到 AirPlay 系统路由，请先确认当前基座运行诊断版本是否为 1.0.16，并确认实际安装包的 entitlements 包含 com.apple.developer.networking.multicast。如果仍在日志中看到 ios-multicast-entitlement-required，通常说明设备上运行的仍是旧保护构建或未重新安装最新 iOS 自定义基座；1.0.16 默认会进入自动 SSDP 搜索。

iOS 自动搜索与 Multicast 权限申请

同一 Wi-Fi 只是 DLNA/UPnP 设备可达的网络前提；iOS 真机自动搜索还依赖 SSDP 组播，目标地址通常是 239.255.255.250:1900。Apple 将本地网络 multicast/broadcast 归入受控能力，业务 App 必须获批 com.apple.developer.networking.multicast 后才能使用 1.0.16 的自动 SSDP 搜索；未获批时不要使用内置该 entitlement 的构建，否则云打包会因描述文件能力不匹配而失败。

客户要开启 iOS 自动 SSDP 搜索时，需要按下面顺序处理：

1. 使用 Apple Developer 的 Account Holder 或 Admin 账号登录。
2. 打开 Apple 官方申请页：Multicast Networking Entitlement Request。
3. 选择或填写业务 App 的 Bundle ID，例如自定义基座实际使用的 com.xxx.xxx。
4. 在用途说明中写清楚：App 提供 DLNA/UPnP 媒体投屏，需要在用户本地 Wi-Fi 内通过 SSDP UDP multicast 239.255.255.250:1900 发现电视、盒子或 Macast 等 DMR 接收端；部分 DLNA 设备不提供 Bonjour 服务，因此 Bonjour 不能完全替代 SSDP；插件仅用于本地网络设备发现，不采集个人信息。
5. Apple 审批通过后，到 Apple Developer 后台的 Certificates, Identifiers & Profiles，在对应 App ID 上启用 Multicast Networking managed capability。
6. 重新生成并下载包含该能力的 provisioning profile。
7. 确认 utssdk/app-ios/UTS.entitlements 已包含：

<key>com.apple.developer.networking.multicast</key>
<true/>

8. 使用新的 provisioning profile 重新打 iOS 自定义基座，然后再测试“搜索设备”自动发现；诊断日志中的 version 应显示 1.0.16。

未获批前，客户仍可使用示例页“手动设备地址”输入框或 API 的 manualDeviceDescriptionUrl，直接填写电视、盒子或 Macast 的 device.xml/description.xml 地址验证 DLNA 解析、连接、投屏、暂停、恢复、音量、进度和停止链路。这条链路不等于自动发现成功，但能证明同一 Wi-Fi 下 HTTP 访问与 SOAP 控制是否可用。

相关 Apple 文档：

• Multicast Networking Entitlement Request
• Multicast Networking entitlement
• Provisioning with managed capabilities

自定义基座说明

App Android / App iOS / App Harmony 使用真实原生投屏能力时必须重新制作自定义基座。未打自定义基座时的表现通常是：

如果 Android 系统通知栏的“屏幕投射”可以看到设备，但插件搜索不到设备，要先区分协议：系统入口通常是 Miracast 或系统投屏路由，插件首版搜索的是 DLNA DMR 媒体投屏设备。请确认电视/盒子开启了 DLNA 或媒体投屏接收能力。

Harmony 真实投屏同样要求电视/盒子支持 DLNA DMR，并与手机处于同一 Wi-Fi。若真机环境阻断 SSDP 组播，优先使用 manualDeviceDescriptionUrl 指向电视/盒子的 device.xml 验证 HTTP 拉取、设备解析和 SOAP 控制链路；Harmony 首版不提供屏幕镜像、Miracast 或系统投射能力。

如果投屏时出现 UPnP 716 Resource not found，说明电视端无法访问传入媒体地址。常见处理方式：

• 使用电视可直接访问的普通 http MP4 做验证。
• 避免登录态、Cookie、Authorization、临时签名过短或 DRM 资源。
• 对 HTTPS 地址留意 https-dlna-risk，部分老电视不支持 HTTPS 媒体播放。
• 手机能播放不代表电视能访问，电视端必须能直接请求该 URL。
• Windows 上同时出现 Macast(yunxi) 和 yunxi 时，Macast(yunxi) 是 Macast 接收器，yunxi 通常是 Windows 自带 Digital Media Renderer；后者对远程 HTTP/HTTPS URL 支持更严格，仍可能返回 716，测试 Macast 请优先选择 Macast(yunxi)。
• iOS 1.0.16 在 Windows Digital Media Renderer 返回 716 时会自动尝试备用 DIDL 元数据；如果备用后仍返回 716，继续按接收端无法访问或不支持该媒体 URL 处理。

iOS 路由事件说明

iOS 的 DLNA 设备发现和连接会返回真实 dlna 设备；AirPlay 仍使用系统路由，不做私有 AirPlay 反射，也不会在初始化且未选择路由时伪造一次断开事件。只有 DLNA 搜索/连接/控制、系统路由变化、外部播放状态变化或用户操作导致状态变化时，才会通过 deviceFound / deviceListChange / stateChange / connected / disconnected / error 等事件回传。

Harmony 搜索与控制说明

Harmony 的真实设备发现会返回 dlna 设备，控制链路使用 AVTransport / RenderingControl SOAP。SSDP 搜索受路由器、同网段隔离和系统网络策略影响较大；真机首测建议先传入 manualDeviceDescriptionUrl 验证 device.xml 与 SOAP，再验证同 Wi-Fi 自动搜索。showCastPanel 在 Harmony 会优先弹出 Android 风格 ArkUI 底部 Sheet 内置面板，业务仍可用 useBuiltinUI:false 自行展示设备列表和控制台；如果当前窗口 UIContext 获取失败，插件会降级到系统 ActionSheet 继续承接搜索和播控。

Harmony SSDP 响应由 @ohos.net.socket 返回 ArrayBuffer，插件会使用 @ohos.util.TextDecoder 解码后解析 LOCATION。如果同 Wi-Fi 下自动搜索仍为空，可先点“诊断快照”查看 ssdpResponseCount / ssdpLocationCount / ssdpDecodeErrorCount / lastSsdpMessagePreview：ssdpResponseCount=0 通常表示设备或路由未把 SSDP 响应回传到 Harmony 端；ssdpResponseCount>0 但 ssdpLocationCount=0 表示收到响应但没有解析到 LOCATION，建议把日志提供给开发侧继续适配。

uni-app 调用示例

<script>
import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

export default {
  data() {
    return {
      devices: []
    }
  },
  onLoad() {
    CastScreen.initCast({ debug: true })
    CastScreen.onCastEvent('*', this.handleCastEvent)
  },
  onUnload() {
    CastScreen.offCastEvent('*', this.handleCastEvent)
  },
  methods: {
    handleCastEvent(event) {
      console.log('投屏事件', event)
    },
    openPanel() {
      CastScreen.showCastPanel({ theme: 'auto' })
    },
    startSearch() {
      CastScreen.startDiscovery({
        timeoutMs: 8000,
        success: () => {
          this.devices = CastScreen.getDiscoveredDevices()
        }
      })
    }
  }
}
</script>

uni-app x 调用示例

import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

CastScreen.initCast({
  debug: true,
  success: () => {
    console.log('投屏运行时已初始化')
  }
})

const caps = CastScreen.getCastCapabilities(null)
if (caps.supported) {
  CastScreen.showCastPanel({
    theme: 'dark',
    title: '投屏到电视',
    subtitle: '请选择同一 Wi-Fi 下的设备'
  })
}

注意事项

• 首版定位为“远程媒体 URL 投屏”，不是屏幕镜像、录屏推流或 DRM 破解插件；本地文件、DRM、需登录鉴权的私有视频需要先转换为电视可访问的远程媒体 URL。
• Android 搜索不到设备时，先确认电视支持 DLNA DMR，而不只是支持 Miracast。
• iOS DLNA 投屏要求手机与电视/盒子在同一局域网，AirPlay 路径必须通过系统路由选择，不绕过系统能力。
• Harmony DLNA 投屏要求手机与电视/盒子在同一局域网；若 SSDP 受限，优先使用 manualDeviceDescriptionUrl 做真机链路验证。
• Web/H5 与小程序端允许展示业务自定义入口，但不得伪造设备发现、连接或投屏成功。
• 媒体投屏失败时，先用 inspectCastMediaSource 检查 URL，再用 exportCastSupportBundle 导出诊断信息给售后或开发排查。

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。