更新记录

1.0.6（2026-06-06）

• 优化 iOS 内置投屏面板：新增 DLNA 设备 / AirPlay 路由 分段切换，默认进入 DLNA 设备页，避免系统路由入口和 DLNA 设备列表混在同一屏。
• iOS DLNA 页保留真实设备列表、扫描入口、投屏当前媒体、暂停/恢复、停止和断开控制；AirPlay 页只保留系统 AVRoutePickerView 路由入口。
• 面板底部主按钮会随分段模式切换：DLNA 页为“扫描 DLNA 设备”，AirPlay 页为“打开系统路由”。
• UTS 层新增 panelMode 状态同步和 switchPanelMode 动作处理，关闭面板后恢复 DLNA 默认页，防止重开时沿用旧路由页状态。
• 同步发布版本口径：package.json、README 当前版本、Android/iOS/Harmony/API 诊断版本、商业 readiness、结构守卫、商业守卫、readiness 报告、运行证据脚本和证据包策略统一到 1.0.6。

1.0.4（2026-06-06）

• 修复 Android 内置投屏面板重复选集：移除投屏中媒体卡下方额外的顶部数字选集预览，只保留下方“选集”横向控制，避免同一组选集控件重复展示。
• 修复业务点击“停止”后再次打开内置面板沿用旧投屏状态的问题：Android 原生层和 UTS 层都会清空当前设备、当前媒体、播放进度和会话状态，重新打开内置面板时从扫描设备初始页开始。
• 优化 stopCast 幂等状态判断：无设备、无媒体或已停止时返回成功并标记 alreadyIdle，不再把“已经停止”误报成找不到设备，同时向业务派发 disconnected 事件同步状态。
• 新增 Android 内置面板 UI 守卫并接入预检、结构守卫和商业就绪守卫，防止重复选集控件和停止态回退在后续修改中再次出现。
• 同步发布版本口径：package.json、README 当前版本、Android/iOS/Harmony/API 诊断版本、商业 readiness、结构守卫、商业守卫、readiness 报告、运行证据脚本和证据包策略统一到 1.0.4。

1.0.3（2026-06-05）

• 升级 Harmony 内置面板体验：showCastPanel({ useBuiltinUI:true }) 优先使用 ArkUI openBindSheet 近全屏底部面板，承接搜索设备、选择设备、投屏当前媒体、暂停、恢复、停止、断开、音量、快退快进、选集和清晰度控制；UIContext 不可用时降级到系统 ActionSheet。
• 对齐 Android 内置面板视觉：Harmony 面板改为暗黑科技风控制台，补齐顶部发光把手、状态卡、媒体进度、音量状态、设备区、遥控控制台、中心发光控制盘和胶囊控制项。
• 精修 Harmony 主题切换图标：内置 Heroicons（MIT）太阳、月亮、跟随系统显示器三态线性 path，主题按钮与关闭按钮统一 50x38 胶囊尺寸、同类背景和圆角，真机检查不再出现粗糙图标、省略号或偏位显示。
• 修复 Harmony 内置面板设备列表不刷新：SSDP 已发现 Macast(yunxi) 等 DLNA 设备并触发 deviceFound / deviceListChange / discoveryStop 时，打开中的 ArkUI Sheet 会主动 update() 当前参数，不再停留在 0 台设备 / 暂未发现可用设备。
• 修复 Harmony 真机 SSDP 响应解码：@ohos.net.socket 返回的 UDP 响应为 ArrayBuffer 时，改用 @ohos.util.TextDecoder 解码后解析 LOCATION，并在诊断快照中输出响应数、LOCATION 数、解码错误数和消息预览。
• 修复 Harmony ArkTS 面板编译风险：调整主题按钮 ArkUI 组件链式调用位置，避免 .width/.height/.onClick 被挂到 if/else 语句块后导致 Declaration or statement expected / Cannot find name 'width'。
• 同步发布版本口径：package.json、README 当前版本、Android/iOS/Harmony/API 诊断版本、商业 readiness、结构守卫、商业守卫、readiness 报告、运行证据脚本和证据包策略统一到 1.0.3。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-cast-screen

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

当前版本：1.0.6

功能特色

• Android 使用 DLNA/UPnP 实现媒体投屏：支持 SSDP 搜索、设备去重、连接、播放普通 http MP4 / https 远程媒体 URL、暂停、恢复、seek、音量、停止和断开。
• iOS 新增 DLNA/UPnP DMR 媒体投屏：支持 SSDP 搜索、手动 device.xml 发现、AVTransport / RenderingControl SOAP 控制、播放、暂停、恢复、seek、音量、停止和进度快照；同时保留系统 AirPlay 路由入口，不做私有 AirPlay 反射。
• Harmony 新增 DLNA/UPnP DMR 媒体投屏：支持 SSDP 搜索、手动 device.xml 发现、AVTransport / RenderingControl SOAP 控制、播放、暂停、恢复、seek、音量、停止、进度快照、诊断包和媒体源预检；内置面板优先使用 Android 风格 ArkUI 近全屏底部 Sheet，承接搜索、选设备、投屏、3D 遥控控制台、音量加减、快退/快进和胶囊选集/清晰度，UIContext 不可用时降级到系统 ActionSheet。
• iOS 内置底部近全屏面板新增 DLNA 设备 / AirPlay 路由 分段切换：DLNA 页提供设备列表、扫描入口、投屏当前媒体、暂停/恢复、停止和断开控制；AirPlay 页保留 AVRoutePickerView 系统路由入口，AirPlay 设备选择仍交给系统完成。
• 内置面板状态覆盖搜索中、设备列表、连接中、已连接、投屏中、已暂停、无设备、失败可重试，面板只展示真实状态，不伪造设备发现、连接或投屏成功。
• 连接设备后自动切换为紧凑产品级控制台和暗黑科技风微光媒体控制台，提供玻璃卡片、发光控制盘、选集、清晰度、顶部单图标主题按钮、快退 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/castScreen.vue

使用方式：

1. 将 uni_modules/lizhao-cast-screen/example/castScreen.vue 复制到项目页面目录，例如 pages/castScreen/castScreen.vue。
2. 在 pages.json 中增加页面路由。
3. App 端重新运行到自定义基座；如果本轮只复制页面、不改插件原生代码，可以直接运行页面验证 UI 与 API 调用。

{
  "pages": [
    {
      "path": "pages/castScreen/castScreen",
      "style": {
        "navigationBarTitleText": "投屏控制演示"
      }
    }
  ]
}

示例页包含：内置面板、业务自定义面板、扫描设备、连接设备、开始投屏、暂停/恢复、seek、音量、停止、诊断包和媒体源预检。它是项目中 pages/castScreen/castScreen.vue 的插件内置副本，便于用户安装插件后直接参考。

快速开始

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://media.w3.org/2010/05/sintel/trailer.mp4',
    title: 'Sintel Trailer',
    mimeType: 'video/mp4'
  },
  episodes: [
    {
      id: 'ep-1',
      title: '第 1 集 Sintel 预告',
      url: 'http://media.w3.org/2010/05/sintel/trailer.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://media.w3.org/2010/05/sintel/trailer.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.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 触发业务自定义入口。

参数

startCast(options)

说明 开始投屏远程媒体 URL。首版仅支持电视/盒子可访问的 http/https 媒体地址。

参数

seekCast(options)

setCastVolume(options)

getCastDiagnostics(options?)

Harmony SSDP 诊断字段

exportCastSupportBundle(options?)

inspectCastMediaSource(options)

返回值说明

CastCapabilities

CastSessionState

会话进度快照来源：Android、iOS DLNA 和 Harmony 优先通过 GetPositionInfo 获取 RelTime / TrackDuration；iOS AirPlay 路径通过 AVPlayer.currentTime 与媒体时长同步。

CastMediaInspection

错误码

权限说明

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

iOS 使用 DLNA/UPnP 局域网发现与 SOAP 控制，同时保留 AirPlay 系统路由和 AVPlayer 外部播放能力；不做私有 AirPlay 扫描。本地网络和 ATS 例外见下方原生配置文件说明。

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 配置，不建议在业务中无差别放开所有网络访问。

自定义基座说明

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。

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 导出诊断信息给售后或开发排查。