更新记录

1.0.40（2026-10-17）

• 新增 exportCastDebugLog() 脱敏诊断 API；客户开启 initCast({ debug: true }) 后复现音量、快进/快退或自动下一集问题，即可导出动作、阶段、耗时、HTTP 状态和自动下一集门禁结果。
• Android Kotlin 与 iOS Swift 原生 SOAP/HTTP 控制链路加入诊断回调，日志不记录媒体地址、请求正文、设备主机或鉴权字段。
• Android 与 iOS 的音量读取/设置、Seek、起播、进度轮询和隐藏面板后的自动下一集均补充 UTS 阶段日志；插件版本统一为 1.0.40。
• 本版修改 Android Kotlin、iOS Swift 及对应 UTS，升级后需要重新构建匹配的 Android 自定义基座与 iOS 自定义基座/IPA；仅热更新页面资源不能替换已编译的原生逻辑。

1.0.38（2026-10-16）

• 新增 HarmonyOS 控制诊断，可记录系统音量按键、控制请求耗时与失败、进度变化，并通过诊断快照和完整报告导出。
• 修复 HarmonyOS 音量调节恢复正常后仍显示旧错误，以及过期音量回调影响当前会话的问题。
• 修复 HarmonyOS 多集投屏关闭面板后无法自动播放下一集的问题，最后一集播放结束后停止。
• 修复 Android、iOS 与 HarmonyOS 暂停状态可能被误判为自然结束、触发自动下一集的问题。
• 修复 Android、iOS 与 HarmonyOS 播至片尾后重新投屏仍定位到结束位置的问题，保留正常中途续播。
• 修复 HarmonyOS 重新选择同一已连接设备时无法再次起播的问题。
• 修复 HarmonyOS 停止或断开后显示旧进度，以及过期请求回写新会话状态的问题。
• 修复 HarmonyOS 网络失败信息不完整、面板仅显示通用错误或对象文本的问题。
• 修复 uni-app 与 uni-app x 示例断开后仍保留旧连接标记的问题。

1.0.37（2026-10-09）

• 修复 Android 接收端已播放但手机可能提示“接收端起播确认已超过总时限”的问题：先读取播放位置与媒体地址，地址精确匹配时省去冗余媒体信息回读，保留原起播身份、状态、断点、取消与回滚确认。
• Android、iOS 与 HarmonyOS 面板 2 在接收端已确认音量为零时显示与现有按钮一致的静音矢量图标，恢复音量后继续显示百分比；默认及自定义音量快捷项同步支持，未知音量与 iOS 系统管理提示保持不变。
• 保留原有点击静音、恢复最近一次确认非零音量、物理音量键、经典面板和公开 API 的行为，无需修改业务调用。
• 本版包含 Android Kotlin、iOS Swift 与 HarmonyOS 原生面板及资源变更，升级后需要重新构建并安装匹配的 Android 自定义基座、iOS 自定义基座/IPA 与 Harmony HAP；仅热更新页面资源不能替换原生实现。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

其他

lizhao-cast-screen

lizhao-cast-screen 是面向 uni-app / uni-app x 的媒体投屏插件。它可以把远程视频、MP3 音频或图片地址发送给同一局域网内的电视、盒子或其他 DLNA 接收设备，并在手机上完成播放控制。

这个插件能解决什么问题

• 自动搜索同一局域网内可投屏的电视或盒子。
• 投屏远程视频、MP3 音频和图片。
• 控制播放、暂停、进度、音量、倍速和停止。
• 为短剧、课程和连续剧提供选集、上下集、自动连播和断点续播。
• App 端自带两套投屏面板，不想自己写界面时可以直接使用面板 2。
• 已有播放器界面时，也可以只使用 API 和事件完成自己的投屏流程。
• 提供媒体地址检查和诊断信息，帮助排查“搜不到电视”“电视打不开视频”等问题。

适合在线视频、短剧、在线课程、图片相册、会议资料和家庭媒体等场景。

本插件用于“把媒体地址交给电视播放”，不是手机屏幕镜像或录屏推流。媒体地址必须能被电视直接访问；本地临时文件、需要登录或鉴权的私有地址、DRM 加密媒体不能直接投屏。

支持平台

Android、iOS 和 Harmony 的界面细节会随系统能力略有差异，但 App 端可以使用同一套公开 API。插件市场的跨端标记只表示对应端可以安装和调用统一入口，是否支持真实投屏应以本表和 getCastCapabilities() 返回结果为准。

先选择接入方式

如果不想自己写界面，推荐直接使用面板 2。调用时请显式传入 panelStyle: 'minimal'。为了兼容已经上线的项目，未传 panelStyle 时仍会显示经典面板。

下载与导入

1. 从插件市场将插件导入项目。
2. 请严格使用下面的插件根目录导入方式，不要在路径后追加其他目录。

各平台运行前提见上方“支持平台”表；App 端的安装包要求也会在文末“注意事项”中再次说明。

uni-app 导入

// 普通 uni-app 页面从插件根目录导入。
import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

uni-app x 导入

// <script setup lang="uts"> 中同样只从插件根目录导入。
import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

下面的业务示例以普通 uni-app JavaScript/TypeScript 写法为主；uni-app x 使用同名 API，强类型写法请参考文末完整 UTS 示例。插件通常只需要初始化一次。

按业务模块使用

除特别说明外，后续模块都假设已经按模块一完成 initCast()。

模块一：不写界面，直接投一个视频

适合第一次接入，或项目不想自己开发设备列表和遥控界面。

// 下面是普通 uni-app 写法；uni-app x 可使用同名 API 和参数。
import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

// 初始化成功后直接打开面板 2。
CastScreen.initCast({
  success() {
    CastScreen.showCastPanel({
      useBuiltinUI: true,
      panelStyle: 'minimal',
      theme: 'auto',
      media: {
        url: 'https://media.w3.org/2010/05/video/movie_300.mp4',
        title: '示例视频',
        mediaKind: 'video',
        mimeType: 'video/mp4'
      },
      success() {
        console.log('投屏面板已打开')
      },
      fail(err) {
        console.log('投屏面板打开失败', err)
      }
    })
  },
  fail(err) {
    console.log('投屏插件初始化失败', err)
  }
})

首次打开面板 2 且尚未连接电视时，会先显示设备搜索页。选择设备并确认媒体成功投屏后，再进入播放控制页；如果当前已经连接设备，再次打开时会直接显示控制页。进入播放控制页后，换设备、断开及其他控制逻辑仍保持原有行为，不会重新返回搜索页。

面板 2 会负责搜索设备、连接、投屏、播放、暂停、进度、音量和停止，不需要业务页面重复实现这些界面。

如果需要使用经典面板，将 panelStyle 改为 classic；省略该字段时也会使用经典面板。

模块二：短剧、课程选集与断点续播

适合短剧、课程、连续剧等需要上一集、下一集、选集和继续播放的场景。

// 每集都提供稳定 ID、可访问地址和独立断点键。
const episodes = [
  {
    id: 'episode-1',
    title: '第 1 集',
    url: 'https://media.w3.org/2010/05/video/movie_300.mp4',
    duration: 300,
    resumeKey: 'course-1001-episode-1'
  },
  {
    id: 'episode-2',
    title: '第 2 集',
    url: 'https://media.w3.org/2010/05/sintel/trailer.mp4',
    duration: 52,
    resumeKey: 'course-1001-episode-2'
  }
]

CastScreen.showCastPanel({
  useBuiltinUI: true,
  panelStyle: 'minimal',
  media: {
    url: 'https://media.w3.org/2010/05/video/movie_300.mp4',
    title: '第 1 集',
    mediaKind: 'video',
    mimeType: 'video/mp4',
    duration: 300,
    resumeKey: 'course-1001-episode-1'
  },
  episodes,
  currentEpisodeIndex: 0,
  rememberProgress: true
})

resumeKey 应使用稳定的课程 ID 或剧集 ID，不要使用可能过期或包含鉴权参数的媒体地址。插件会分别记录每一集的投屏进度，切换回来后可以继续播放。希望使用插件保存的断点时可以省略 currentTime；只有需要从页面播放器当前位置接着投时，才传入页面的真实进度。

当 episodes 至少有两项时，面板 2 会提供“选集”和“下一集”。选择新剧集时，只有接收端真实接受播放后才会更新当前选集；失败时保留原来的播放状态。最后一集播放结束后不会自动回到第一集。

Android、iOS 和 HarmonyOS 的 App 多集面板支持自然播完后自动播放下一集；暂停、主动停止、切集中或未到片尾时不会因为接收端回报 STOPPED 而跳集。HarmonyOS 在多集已稳定播放后关闭面板，也会保留当前列表继续检测片尾；停止、断开、最后一集结束或另投其它媒体时释放隐藏列表。关闭正在切集/恢复的面板仍取消该次面板事务。Web 与小程序的业务自定义界面需由业务管理播放列表，不能按 App 原生多集面板推定自动切集能力。

Android 与 iOS 在重新投屏同一媒体时优先采用接收端已确认的真实时长；起播位置已到或超出片尾时从头播放并清理过期断点，正常中途续播不受影响。

HarmonyOS 持续使用诊断

示例初始化已开启 debug: true。使用当前源码重新构建并安装 Harmony HAP 后，getCastDiagnostics() 的 harmonyControlDiagnostics 会返回带 harmony-control-log-20261015-v1 标记的 JSON 字符串，售后诊断包的 diagnostics 也包含它。内容包括系统按键接收次数、SOAP 请求/失败/在途数量与耗时、进度采样、最近16条关键记录和独立4条错误；只记录控制元数据，不收集媒体地址、设备身份或SOAP正文。累计计数限本次 App 进程，重启会重置，最近记录有上限，不能代替完整运行日志。

在原示例的“面板2·多集”中，让首集自然播完，分别检查面板保持打开、关闭面板两种情况，第二集应实际起播；最后一集结束应停止。随后按实际使用方式持续测试至少30分钟，期间可暂停/恢复、拖动、切集及关闭/重开面板。物理加减键每次按压仍沿用1%的步长；现有 isRepeat=false 策略不把长按重复事件累加为多次调节。

出现异常时先关闭投屏面板，展开“更多投屏操作”点“诊断快照”，再点示例底部“复制完整报告”；报告分段时按提示继续复制下一段，所有段一起提供，并说明大约测试时长和最后一次操作。请在复制前保留现场、不要先重启 App；闪退时另保留 HBuilderX 控制台日志。日志仅用于定位，不会自动认定长期稳定或真机验收通过。本次涉及三种 App 平台 UTS，交付前分别使用当前源码匹配的 Android 基座、iOS 基座/IPA、Harmony HAP；页面热更新不能加入新的原生日志或判据。

模块三：配置清晰度、倍速和面板外观

适合一个视频提供多个真实清晰度地址，或希望面板颜色与项目风格保持一致的场景。

// 请把示例地址替换为项目自己的真实媒体地址。
CastScreen.showCastPanel({
  useBuiltinUI: true,
  panelStyle: 'minimal',
  media: {
    url: 'https://media.example.com/video-auto.mp4',
    title: '示例课程',
    mediaKind: 'video',
    mimeType: 'video/mp4'
  },
  currentQuality: 'auto',
  qualities: [
    {
      id: 'auto',
      label: '自动',
      url: 'https://media.example.com/video-auto.mp4',
      selected: true
    },
    {
      id: '720p',
      label: '720P',
      url: 'https://media.example.com/video-720p.mp4'
    },
    {
      id: '1080p',
      label: '1080P',
      url: 'https://media.example.com/video-1080p.mp4'
    }
  ],
  playbackRates: [0.5, 1.0, 1.5, 2.0],
  theme: 'auto',
  appearance: {
    progressColor: '#E87B9A',
    progressTrackColor: '#4D4B50',
    episodeSelectedColor: '#E87B9A',
    progressThumbIcon: {
      type: 'tv'
    }
  }
})

每个清晰度都应提供接收设备能够直接访问的真实媒体地址。没有配置 qualities 时，插件不会伪造 720P 或 1080P。

倍速是接收端的真实能力。Android、iOS、Harmony 只有在接收端确认目标倍率后才会更新状态；接收端拒绝时会保留原倍速并返回失败。appearance 只用于面板 2，可以配置进度颜色、选集颜色和进度滑块图标。

点击音量区域可在静音与最近一次确认的非零音量之间切换。面板 2 在已确认音量为零时显示静音图标，恢复后显示百分比；默认与自定义音量快捷项保持一致。接收端音量未知时显示 --%，iOS AirPlay 未取得系统音量时保留“系统管理”。接收端不支持该倍速时会保留原倍率；未配置清晰度资源时不会伪造可切换选项。

面板 2 会在匹配投屏设备后读取其公开的倍速声明。读取完成前显示 playbackRateDetectingText 并保持灰色不可点击；确认没有可选倍率时显示 playbackRateUnsupportedText，不会发送倍速命令。默认显示倍速，可用 showPlaybackRate: false 隐藏；playbackRateLabel 可修改快捷项标题。若接收端没有公开能力声明，界面会保留“检测中”，业务仍可直接调用倍速 API 并根据真实失败回调处理。

需要自行决定面板 2 快捷项时，可用 minimalQuickActions 替换默认快捷行，最多显示三个项目；visible: false 隐藏项目，disabled: true 保留灰色不可点击状态。内置类型包括 volume、playbackRate、quality、danmaku，custom 会通过 customAction 事件把 id、kind 和 value 回传给业务。该配置只影响 panelStyle: 'minimal'，classic 面板不受影响。

CastScreen.showCastPanel({
  useBuiltinUI: true,
  panelStyle: 'minimal',
  showPlaybackRate: true,
  playbackRateLabel: '速度',
  playbackRateDetectingText: '读取中',
  playbackRateUnsupportedText: '设备不支持',
  minimalQuickActions: [
    { id: 'volume', kind: 'volume', title: '音量' },
    { id: 'rate', kind: 'playbackRate', title: '速度' },
    { id: 'quality', kind: 'quality', title: '画质' }
  ]
})

模块四：投屏 MP3、图片或带字幕的视频

适合音乐、听书、图片相册以及带字幕或歌词的媒体。

// 示例投屏带歌词描述的 MP3；请将歌词占位地址替换为真实可访问地址。
CastScreen.showCastPanel({
  useBuiltinUI: true,
  panelStyle: 'minimal',
  media: {
    url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3',
    title: '示例音频',
    mediaKind: 'audio',
    mimeType: 'audio/mpeg',
    textTracks: [
      {
        id: 'lyrics-zh',
        kind: 'lyrics',
        format: 'lrc',
        label: '中文歌词',
        language: 'zh-CN',
        url: 'https://media.example.com/demo.lrc',
        isDefault: true
      }
    ],
    preferredTextTrackId: 'lyrics-zh',
    textTrackFailurePolicy: 'continue-media'
  }
})

外挂字幕和歌词能否真正显示，取决于目标电视或盒子的能力。插件会传递兼容信息，但不会把“媒体开始播放”误报为“字幕已经显示”。面板参数 subtitle 只是面板提示文案，不是媒体字幕。

模块五：使用自己的投屏界面

适合项目已经有设备弹窗、播放器控制栏或统一设计规范，只需要插件提供搜索、连接和投屏能力的场景。

// 自定义界面只负责展示；设备搜索、连接和投屏仍由插件完成。
const media = {
  url: 'https://media.w3.org/2010/05/video/movie_300.mp4',
  title: '示例视频',
  mediaKind: 'video',
  mimeType: 'video/mp4'
}

// 保存同一个函数引用，页面卸载时才能正确移除监听。
const handleDeviceListChange = (event) => {
  console.log('请在业务界面展示这些设备', event.payload)
}

CastScreen.onCastEvent('deviceListChange', handleDeviceListChange)

CastScreen.initCast({
  success() {
    CastScreen.startDiscovery({
      timeoutMs: 12000,
      clearBeforeStart: true,
      fail(err) {
        console.log('搜索设备失败', err)
      }
    })
  }
})

function castToDevice(deviceId) {
  CastScreen.connectDevice({
    deviceId,
    success() {
      CastScreen.startCast({
        media,
        fail(err) {
          console.log('投屏失败', err)
        }
      })
    },
    fail(err) {
      console.log('连接设备失败', err)
    }
  })
}

function leavePage() {
  CastScreen.offCastEvent('deviceListChange', handleDeviceListChange)
}

业务界面应根据成功回调和 connected、stateChange、error 等事件更新状态，不要在点击按钮后直接显示“投屏成功”。

如需让同一个投屏按钮只触发业务界面，可以调用 showCastPanel({ useBuiltinUI: false })。该调用会派发面板事件，但不会替项目绘制界面。

模块六：控制播放并读取真实状态

适合自定义控制栏，或需要把接收端进度、音量和倍率同步回业务页面的场景。

// 所有控制都应处理失败；部分电视可能不支持其中某个动作。
CastScreen.pauseCast({ fail: (err) => console.log('暂停失败', err) })
CastScreen.resumeCast({ fail: (err) => console.log('恢复失败', err) })
CastScreen.seekCast({ position: 60, fail: (err) => console.log('进度跳转失败', err) })
CastScreen.setCastVolume({ volume: 0.5, fail: (err) => console.log('音量设置失败', err) })
CastScreen.setCastPlaybackRate({ rate: 1.5, fail: (err) => console.log('倍速设置失败', err) })

const state = CastScreen.getCastSessionState()
console.log('接收端状态', state.state, state.currentTime, state.duration)

// volumeKnown 为 false 时，界面应显示“同步中”或“未知”。
console.log('音量是否已确认', state.volumeKnown)

stopCast() 只停止当前媒体，方便继续向同一设备投屏其他内容；需要停止并断开时使用 disconnectDevice({ stopRemote: true })。

模块七：微信小程序搜索并投屏

微信小程序没有插件内置面板，需要把发现的设备展示在自己的弹窗或列表中。

// 微信小程序使用同一套公开 API，但需要项目自己展示设备列表。
import * as CastScreen from '@/uni_modules/lizhao-cast-screen'

let selectedDeviceId = ''
const discoveredDevices = []

const handleDeviceFound = (event) => {
  const device = event.payload
  if (device == null || device.id == null) return

  // 把设备加入业务列表，等待用户点击选择，不要自动覆盖选择结果。
  const index = discoveredDevices.findIndex((item) => item.id === device.id)
  if (index >= 0) discoveredDevices[index] = device
  else discoveredDevices.push(device)
  console.log('当前投屏设备列表', discoveredDevices)
}

CastScreen.onCastEvent('deviceFound', handleDeviceFound)

CastScreen.initCast({
  success() {
    CastScreen.startDiscovery({
      timeoutMs: 5000,
      clearBeforeStart: true,
      fail(err) {
        console.log('搜索设备失败', err)
      }
    })
  }
})

function selectDevice(deviceId) {
  // 用户点击设备列表项时保存目标设备 ID。
  selectedDeviceId = String(deviceId)
}

function castSelectedDevice() {
  if (selectedDeviceId.length === 0) {
    console.log('请先选择投屏设备')
    return
  }

  CastScreen.connectDevice({
    deviceId: selectedDeviceId,
    success() {
      CastScreen.startCast({
        media: {
          url: 'https://media.w3.org/2010/05/video/movie_300.mp4',
          title: '示例视频',
          mediaKind: 'video',
          mimeType: 'video/mp4'
        },
        fail(err) {
          console.log('投屏失败', err)
        }
      })
    },
    fail(err) {
      console.log('连接设备失败', err)
    }
  })
}

function leavePage() {
  CastScreen.offCastEvent('deviceFound', handleDeviceFound)
}

手机和电视必须处于同一可互访局域网。实际项目应展示完整设备列表，让用户确认目标设备，不建议自动选择搜索到的第一台设备。

微信小程序的真实投屏能力取决于当前基础库是否提供所需的局域网 Socket API。具体网络排查方法见后文“常见问题”。

模块八：上线前检查媒体地址并收集诊断信息

适合排查手机能播放、电视却打不开媒体，或需要把运行信息提供给技术支持的场景。

// 预检只分析媒体配置，不会代替真实电视访问测试。
const inspection = CastScreen.inspectCastMediaSource({
  media: {
    url: 'https://media.example.com/video.mp4',
    mediaKind: 'video',
    mimeType: 'video/mp4'
  }
})

console.log('是否适合进入投屏流程', inspection.castable)
console.log('风险提示', inspection.riskFlags)
console.log('处理建议', inspection.suggestions)

// 出现问题时导出当前能力、会话和最近事件。
const supportBundle = CastScreen.exportCastSupportBundle({
  includeDevices: true,
  includeRecentEvents: true,
  maxEvents: 20
})

console.log('投屏诊断信息', JSON.stringify(supportBundle))

媒体检查可以提前发现本地路径、疑似鉴权地址、DRM 和格式不明确等常见风险。诊断信息可以帮助区分设备搜索、网络、媒体地址和接收端能力问题，但不能代替真实电视或 AirPlay 接收器验收。

客户反馈问题时导出详细运行日志

当需要定位“电视不能调音量”“快进/快退卡顿”或“片尾没有自动下一集”时，请让客户在同一次 App 会话中先开启调试，再复现一次问题，最后导出 JSON：

CastScreen.initCast({ debug: true })

// 客户继续按正常流程搜索、连接、投屏并复现问题。

const debugLog = CastScreen.exportCastDebugLog({
  maxEntries: 200,
  printToConsole: true
})
console.log('[CAST_DEBUG_LOG]', JSON.stringify(debugLog))

debugLog.logs[i].payload 包含 action、phase、source、durationMs、错误码和自动下一集门禁状态，可用于判断请求是否发出、接收端是否返回、音量是否被确认、Seek 是否超时，以及隐藏面板后为何没有进入下一集。printToConsole: true 会再输出一份完整 JSON，客户可复制控制台中 [CAST_DEBUG_LOG] 后面的内容发回。日志默认不带最近业务事件，避免把媒体地址或设备地址带出；只有确认可以分享时才传 includeRecentEvents: true，并先检查其中的 URL、设备信息和业务标题。

该 API 只在当前 App 会话内保留最多 200 条脱敏日志；调用 exportCastDebugLog({ clearAfterRead: true }) 可以在导出后清空日志。客户需要在升级到 1.0.40 对应的 Android 自定义基座或 iOS 自定义基座/IPA 后测试，否则原生诊断链路不会进入旧基座。

常用 API 与配置

API 用途总览

通用回调

大部分异步 API 都支持以下回调：

搜索任务启动、网络请求返回或接收端收到命令，不一定代表媒体已经正常播放。业务界面应结合 success、connected、stateChange 和 error 等事件更新最终状态。

初始化与设备搜索参数

startDiscovery.success 表示搜索任务已经启动，不表示已经找到电视。设备结果应通过 deviceFound、deviceListChange 事件或 getDiscoveredDevices() 获取。

面板参数

panelStyle: 'minimal' 支持 App Android、iOS 和 Harmony。微信小程序没有内置面板，应使用自己的设备列表和控制界面。

普通 uni-app 对象附带的其他键在 iOS 平台会被忽略。不要依赖未声明字段传递剧集或开关状态；请使用上表公开参数。

普通 DLNA/AirPlay 没有通用弹幕叠加协议，danmakuSupported 默认应保持 false。只有项目拥有配套电视画面层并能真实处理弹幕时，才应开启并处理 onDanmakuToggle。

minimalQuickActions 的 custom 项不会替电视执行控制命令，只会通过 customAction 事件通知业务；字幕、歌词、弹幕和清晰度是否真正生效，仍取决于接收端或项目自己的电视端能力，不能仅凭快捷项显示推断支持。

面板 2 外观配置

无效的颜色或图片只会回退对应字段，不影响其他外观配置。

媒体参数 CastMediaSource

当前正式音频格式为 MP3，建议同时设置 mediaKind: 'audio' 和 mimeType: 'audio/mpeg'。图片应传入正确的 image/* MIME 类型；图片没有时间轴，不支持暂停、恢复、Seek 和倍速。

选集参数 CastPanelMediaItem

多集场景应传入完整 episodes、正确的 currentEpisodeIndex，并确保每一集都有接收设备可访问的 URL。

清晰度参数 CastPanelQualityItem

没有配置真实清晰度 URL 时，插件不会伪造切换成功。

文本轨参数 CastTextTrack

外挂字幕和歌词是否真正显示，取决于接收设备是否支持对应文本轨能力。startCast.success 只表示媒体投屏流程成功，不能作为字幕已经显示的证明。

连接与播放控制参数

暂停、恢复、Seek、音量和倍速最终取决于接收设备是否实现对应控制能力。接收端拒绝时会触发 fail，不会只修改界面文字来伪造成功。

跨端自定义界面的稳定调用顺序是：先让用户选择设备，调用 connectDevice() 成功后，再调用 startCast()。

主要返回值

CastCapabilities

调用 getCastCapabilities() 获取：

即使能力入口存在，某台电视仍可能不支持暂停、Seek、音量或倍速，应继续处理各 API 的失败回调。

CastDevice

CastSessionState

调用 getCastSessionState() 获取：

volumeKnown 为 false 时，应显示“同步中”或“未知”，不要把 volume 当成接收端真实音量。

CastMediaInspection

调用 inspectCastMediaSource() 获取：

该方法不会联网测试电视是否真的能够访问媒体 URL，最终结果仍需在目标设备上确认。

事件

// 使用同一个函数引用注册和移除监听。
const handleCastEvent = (event) => {
  console.log(event.name, event.payload)
}

CastScreen.onCastEvent('*', handleCastEvent)

function leavePage() {
  CastScreen.offCastEvent('*', handleCastEvent)
}

事件名传 * 可以监听全部事件。移除单个监听时，必须向 offCastEvent 传入注册时的同一个回调函数。

错误码

常见问题

搜索不到电视

按以下顺序检查：

1. 确认电视开启的是 DLNA、媒体投屏或媒体接收功能，而不只是 Miracast。
2. 手机与电视连接同一个可互访 Wi-Fi。
3. 关闭访客网络、AP 隔离或会阻止局域网设备互访的设置。
4. App 确认使用了包含当前插件的自定义基座。
5. iOS 确认已经允许本地网络访问，并完成 Multicast Networking 权限配置。
6. 微信小程序确认当前基础库具备 UDP/TCP Socket 能力。

手机可以播放，电视却无法播放

媒体是由电视直接下载，不是手机把画面转发给电视。请检查：

• URL 是否为电视能够直接访问的 http/https 地址。
• 是否依赖 Cookie、Authorization、Referer、防盗链或短时签名。
• 是否为 DRM、加密 HLS/DASH 或需要登录的资源。
• 视频编码和封装是否被电视支持。
• 远程 MP4 是否支持 HTTP Range；拖动进度通常需要服务端正确返回分段内容。
• 部分旧电视不支持 HTTPS，可先用普通 HTTP 媒体排除兼容问题。

Harmony 已连接，但提示“新媒体时长未就绪”

连接成功表示接收端可以接受控制命令，不代表它已下载并解析视频。带断点起播时，插件会等待接收端报告有效时长，再定位并确认真实播放进度；仅收到 Play 成功响应或 PLAYING 状态不足以确认起播成功。

Harmony 重新起播时，如果传入的位置已达到或超过接收端报告的真实片尾，会从头播放并清除该媒体已失效的续播记录；尚未到片尾的正常断点仍然保留。面板 2 的设备搜索页选择同一台已连接设备时，也会等待本次媒体真实起播成功后进入控制页，失败后可以再次选择重试。

出现该提示时，请保留原媒体地址和失败回调，先在同一接收端用已验证可播放的媒体对照，检查接收端的网络访问、编码和媒体解析情况。不要把失败回调改成成功，也不要只凭手机能播放判断电视可以播放。

使用 Macast 等电脑接收器时，还应检查它实际调用的播放器日志。同一电脑的浏览器能播放，不代表接收器内置的 MPV 能加载；若 MPV 报 tls: handshake failed，说明 HTTPS 连接尚未成功，应修复接收器播放器的 HTTPS 兼容问题，再用原地址复测。单纯增加插件等待时间不能解决这种失败。

排查网络失败时，请同时记录失败对象的 errCode、errMsg 和 details。Harmony 网络错误的 details 会保留系统提供的错误码和原因，内置面板优先显示具体原因。更新 Harmony 原生实现后，需要重新构建并安装匹配的 HAP；页面热更新不能替换原生代码。

面板 2 没有显示选集或下一集

请确认：

• 使用了 panelStyle: 'minimal'。
• showEpisodeControls 没有设置为 false。
• episodes 至少包含两个有效项目。
• 每一项都有标题和接收设备可访问的 URL。
• currentEpisodeIndex 是正确的数组下标。
• App 已制作并安装包含当前插件代码的自定义基座或 IPA。

单集场景不会提供可用的下一集操作，这是正常表现。

倍速切换失败

倍速是电视或系统播放器的真实能力。插件只有在接收端确认目标倍率后才会更新状态。电视拒绝目标倍率时，应保留原倍率并提示当前设备不支持。

微信小程序、Web/H5 和支付宝小程序当前不支持 setCastPlaybackRate。

字幕或歌词没有显示

外挂字幕和歌词没有统一适用于所有电视的 DLNA 标准。插件可以发送兼容信息，但最终是否显示取决于接收设备。

如果必须保证显示，优先选择：

1. 已经烧录在视频画面中的硬字幕。
2. AirPlay 媒体自身包含的可选字幕轨。
3. 已验证支持对应外挂字幕格式的电视或盒子。

面板参数 subtitle 只是面板提示文案，不是媒体字幕。

图片为什么不能暂停或拖动进度

图片没有播放时间轴，因此不支持暂停、恢复、Seek、倍速和进度轮询。iOS 图片投屏应选择 DLNA 设备，不应把图片当成 AirPlay 视频播放。

停止播放后为什么设备仍然连接

stopCast() 只停止当前媒体，方便继续向同一设备投屏其他内容。需要同时停止并断开时使用 disconnectDevice({ stopRemote: true })。

Harmony 面板 2 在确认停止或断开后会清除已结束会话的进度，待投标题、选集和续播记录继续保留。业务再次显式调用 showCastPanel() 传入的预览进度仍会生效。

微信小程序为什么没有内置面板

微信小程序支持局域网 DLNA 搜索和控制，但不提供插件内置原生面板，需要使用自己的弹窗、设备列表和播放控制界面。

微信开发者工具提示 connect fail: invalid address

微信小程序投屏依赖 wx.createUDPSocket 和 wx.createTCPSocket，并受基础库、端口与网络策略限制。开发者工具本地调试时可以临时关闭合法域名校验来排除工具限制；真机仍必须满足局域网互访、端口和媒体地址要求。

Web/H5 或支付宝小程序为什么没有搜索结果

这两个平台当前只保留统一 API 和明确的降级结果，不支持真实 DLNA 搜索、连接或媒体投屏。应先查询能力：

// 不支持的平台使用 reason 显示业务提示。
const capabilities = CastScreen.getCastCapabilities()
if (!capabilities.supported) {
  console.log(capabilities.reason)
}

iOS AirPlay 有声音但没有画面

AirPlay 音频路由成功不等于视频已经进入外部播放。请检查媒体是否包含可播放的视频轨、编码是否被接收器支持，以及电视是否真正进入 AirPlay 视频播放状态。

完整示例

• uni-app 完整示例
• uni-app x 完整示例

完整示例包含两套内置面板、自定义设备列表、视频/MP3/图片投屏、选集、清晰度、播放控制、诊断和媒体预检。业务页面仍应只从插件根目录导入 API。

注意事项

• 手机与电视必须处于同一可互访局域网。
• 插件投送的是媒体 URL，不是手机屏幕镜像，也不提供 Miracast、录屏推流或 DRM 破解能力。
• 媒体地址必须能由电视直接访问。本地文件、临时文件、Blob、Data URL、Cookie、Authorization 和 DRM 媒体不能直接投屏。
• App Android、iOS、Harmony 使用真实原生能力时，需要制作并安装包含插件的自定义基座或对应安装包。
• Android 所需的网络、Wi-Fi 状态和组播权限由插件声明；电视仍需开启 DLNA/媒体接收能力。
• Harmony 需要网络访问能力；自动搜索仍会受到路由器和系统局域网策略影响。
• 微信小程序不需要 App 自定义基座，但受微信 Socket、端口和局域网策略限制。
• success 回调表示当前 API 已按平台规则确认成功，不应仅凭按钮点击更新为“投屏成功”。
• Seek、音量、倍速、暂停和恢复是否可用，最终取决于电视或盒子的实现。
• 图片没有时间轴，不支持暂停、恢复、Seek 和倍速。
• 外挂字幕、歌词和弹幕是三种不同能力，不能互相替代。
• volumeKnown: false 时不要把 volume 显示成接收端真实音量。
• 页面卸载时应调用 offCastEvent 释放持续事件监听。
• resumeKey 应使用课程 ID、剧集 ID 等稳定业务标识，不要使用包含鉴权参数的媒体 URL。
• 诊断包可能包含当前设备、会话和最近事件。提供给技术支持前，应先检查是否含有业务不希望对外提供的信息。

iOS 本地网络与自动搜索权限

本地网络说明

iOS 使用 DLNA 搜索和控制时，最终 App 的 Info.plist 需要包含本地网络用途说明：

<!-- 用于向用户解释为什么需要访问局域网投屏设备。 -->
<key>NSLocalNetworkUsageDescription</key>
<string>用于发现和连接局域网投屏设备。</string>

如需访问局域网中的普通 HTTP 设备描述或控制地址，应只放开本地网络：

<!-- 仅允许局域网请求，不要全局放开所有非 HTTPS 请求。 -->
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsLocalNetworking</key>
  <true/>
</dict>

不建议为了投屏功能全局开启 NSAllowsArbitraryLoads。首次访问本地网络时，iOS 会显示系统授权提示；如果用户拒绝，需要在系统设置中重新允许本地网络访问。

申请 Multicast Networking managed capability

DLNA 自动发现使用 SSDP 组播。iOS 正式构建需要 Apple 批准 Multicast Networking managed capability。

1. 登录 Apple Developer 账号。
2. 打开 Multicast Networking Entitlement Request。
3. 填写对应 App ID 和使用场景，说明 App 使用 SSDP 在同一局域网发现 DLNA 电视或盒子。
4. Apple 审批通过后，在对应 App ID 上启用 Multicast Networking 能力。
5. 重新生成并下载包含该能力的 provisioning profile。
6. 确认最终签名权限包含 com.apple.developer.networking.multicast。
7. 使用新的 provisioning profile 重新制作 iOS 自定义基座或 IPA。
8. 安装新构建；如设备仍运行旧签名能力，先卸载旧包再重新测试自动搜索。

签名权限应包含：

<!-- DLNA 自动 SSDP 搜索需要的组播权限。 -->
<key>com.apple.developer.networking.multicast</key>
<true/>

如果打包提示 Provisioning profile doesn't include the Multicast Networking capability，说明当前描述文件尚未包含该能力。应完成 Apple 审批、App ID 开通和 provisioning profile 更新后重新打包；删除该权限会导致 DLNA 自动搜索不可用。

尚未获得审批时，可以使用已知设备描述地址和 manualDeviceDescriptionUrl 调试局域网连接，但不能使用 DLNA 自动搜索。AirPlay 仍通过 iOS 系统路由选择器使用，不需要实现私有 AirPlay 协议。

Apple 参考文档：

• Multicast Networking entitlement
• Provisioning with managed capabilities

作者系列 UTS 插件

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