更新记录

1.0.2（2026-06-03）

• 修复 Harmony 真机 ArkTS 编译失败：规避 arkts-no-structural-typing，不再把具体 options 或对象字面量结构化传给公共接口。
• 修复 Harmony implements 类型限制：CastEvent / CastCallbacks / CastCapabilities / CastSessionState 调整为真正的 interface，避免 arkts-implements-only-iface。
• 修复 Harmony 回调适配器可选字段类型：success / fail / complete 保持 optional/undefined 语义，不再把 null 赋给 CastCallbacks 可选回调。
• 同步发布版本口径：package.json、README、运行诊断版本、商业 readiness、结构守卫、商业守卫、readiness 报告和证据包版本统一到 1.0.2。

1.0.1（2026-06-03）

• 修复平台标记检查：兼容当前 package.json 的 uni-app / uni-app x 嵌套平台声明，同时保留 Harmony、Web/H5、小程序、快应用只提供降级入口的说明。
• 修复 readiness 版本口径：交付状态文件和 readiness 报告脚本同步到 1.0.1，避免状态报告仍检查旧版本。
• 修复 iOS UTS 类型导入：补充 CastCallbacks 导入，并保持 iOS 回调 helper 集中收口，已通过 iOS LSP lint。

1.0.0（2026-06-02）

• 首发版本：lizhao-cast-screen 定位为暗黑科技风媒体投屏 UTS 插件，面向 uni-app / uni-app x 提供 Android DLNA/UPnP 与 iOS AirPlay 的跨端投屏能力。
• Android 真实实现 DLNA/UPnP 媒体投屏：支持 SSDP 多网卡搜索、设备去重、连接、播放远程 http/https 媒体 URL、暂停、恢复、seek、音量、停止和断开。
• iOS 真实接入系统 AirPlay 路由入口：内置面板承载 AVRoutePickerView，使用 AVPlayer 外部播放能力承接远程媒体 URL，不做私有 AirPlay 反射。
• 内置暗黑科技风投屏面板：底部近全屏、深色基底、高对比青绿色交互、科技玻璃卡片、横向媒体胶囊和环形发光控制盘；同时支持 dark / light / auto 主题。
• 连接设备后自动切换为投屏控制台：支持选集、上一集、下一集、清晰度、进度、时长、音量、投屏当前媒体、暂停/恢复、快退 15 秒、快进 15 秒、停止投屏和断开设备。
• 暴露完整业务事件：支持 onCastEvent/offCastEvent、showCastPanel({ useBuiltinUI:false }) 和 customAction，业务可完全自定义投屏界面。
• 新增诊断与售后能力：getCastDiagnostics、exportCastSupportBundle、inspectCastMediaSource 可输出能力矩阵、会话状态、设备列表、媒体源风险和建议动作。
• 明确商业边界：首版只支持电视/盒子可访问的远程媒体 URL；本地文件、DRM、需登录鉴权的私有视频、屏幕镜像和录屏推流不伪造成功。
• 降级端保持统一 API：Harmony/Web/微信小程序/支付宝小程序返回明确不支持或 supported:false，只保留业务自定义入口，不声明真实投屏成功。
• 配套发布资料：README、错误码、权限说明、自定义基座说明、Android/iOS 验收脚本、插件市场封面和示例图已同步首发版本。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-cast-screen

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

当前版本：1.0.2

功能特色

• Android 使用 DLNA/UPnP 实现媒体投屏：支持 SSDP 搜索、设备去重、连接、播放普通 http MP4 / https 远程媒体 URL、暂停、恢复、seek、音量、停止和断开。
• iOS 接入系统 AirPlay 路由入口：内置底部近全屏面板承载 AVRoutePickerView，通过 AVPlayer.currentTime 同步会话进度快照，不做私有 AirPlay 反射。
• 内置面板状态覆盖搜索中、设备列表、连接中、已连接、投屏中、已暂停、无设备、失败可重试，面板只展示真实状态，不伪造设备发现、连接或投屏成功。
• 连接设备后自动切换为紧凑产品级控制台和暗黑科技风微光媒体控制台，提供选集、清晰度、顶部单图标主题按钮、快退 15 秒、快进 15 秒、音量加减、投屏当前媒体和原地刷新。
• 标题右侧扫描设备入口默认可用，不再展示“使用业务自定义界面”按钮；业务自定义入口请使用 showCastPanel({ useBuiltinUI: false }) 与事件回调。
• 支持 dark / light / auto 主题。auto 跟随系统，dark 适合影音投屏场景，light 适合浅色业务页面。
• 提供 getCastDiagnostics、exportCastSupportBundle、inspectCastMediaSource，方便线上诊断设备、媒体源和投屏状态。

支持平台

插件市场平台标记说明

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

安装说明

1. 将插件放入项目的 uni_modules/lizhao-cast-screen 目录。
2. 页面中只从插件根目录导入，不要导入 utssdk 子路径。
3. App Android / App iOS 使用真实原生能力时，需要重新制作并安装自定义基座。
4. H5、小程序、Harmony 可以调用同名 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 会搜索 DLNA DMR；模拟器、企业网络或组播受限时，可传 manualDeviceDescriptionUrl 指向已知 device.xml。

参数

showCastPanel(options)

说明 展示插件内置投屏面板。Android/iOS 是原生底部近全屏面板；降级端建议用 useBuiltinUI:false 触发业务自定义入口。

参数

startCast(options)

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

参数

seekCast(options)

setCastVolume(options)

getCastDiagnostics(options?)

exportCastSupportBundle(options?)

inspectCastMediaSource(options)

返回值说明

CastCapabilities

CastSessionState

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

CastMediaInspection

错误码

权限说明

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

iOS 使用 AirPlay 系统路由与 AVPlayer 外部播放能力，不做私有扫描；本地网络和 ATS 例外见下方原生配置文件说明。

原生配置文件

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

iOS 的 App Transport Security 只针对 AirPlay/本地网络接入做边界说明，包含 NSAllowsLocalNetworking 与局部 NSAllowsArbitraryLoads 配置，不建议在业务中无差别放开所有网络访问。

自定义基座说明

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

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

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

• 使用电视可直接访问的普通 http MP4 做验证。
• 避免登录态、Cookie、Authorization、临时签名过短或 DRM 资源。
• 对 HTTPS 地址留意 https-dlna-risk，部分老电视不支持 HTTPS 媒体播放。
• 手机能播放不代表电视能访问，电视端必须能直接请求该 URL。

iOS 路由事件说明

iOS 使用系统 AirPlay 路由，不做私有 AirPlay 反射，也不会在初始化且未选择路由时伪造一次断开事件。只有系统路由变化、外部播放状态变化或用户操作导致状态变化时，才会通过 stateChange / connected / disconnected / error 等事件回传。

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 必须通过系统 AirPlay 路由选择，不绕过系统能力。
• 降级端允许展示业务自定义入口，但不得伪造设备发现、连接或投屏成功。
• 媒体投屏失败时，先用 inspectCastMediaSource 检查 URL，再用 exportCastSupportBundle 导出诊断信息给售后或开发排查。