更新记录

1.0.8（2026-07-08）

1、修复 Android 14+ MediaProjection 前台服务流程：先启动 ScreenCastForegroundService 并 startForeground(FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION)，再调用 getMediaProjection，解决 SecurityException 2、合并 ScreenCastForegroundService 至 index.uts 单文件，修复运行时缺少 Service 类的问题 3、新增 captureScope 参数，支持 Android 14+ 选择整屏（fullScreen）或单应用（singleApp）录屏 4、checkScreenCastSupport 返回 captureScopes 字段，便于业务层判断当前设备支持的录屏范围

1.0.7（2026-06-23）

1、降低minSdkVersion版本到28

1.0.6（2026-06-17）

1、新增录屏状态查询与变化监听（getScreenCastStatusSync、onScreenCastStatusChange），支持 Android / iOS / Harmony

平台兼容性

uni-app(4.0)

uni-app x(4.0)

m-screen-cast

跨端全屏录屏 UTS 插件，面向 uni-app Vue3 App 端（Android / iOS / Harmony）。

基于各平台原生录屏能力封装统一 API：Android MediaProjection、iOS ReplayKit、Harmony AVScreenCaptureRecorder。

⚠️ 录制范围说明（集成前必读）

平台	录制范围
Android	整屏或单应用（Android 14+，通过 captureScope 配置）
Harmony	整屏
iOS	仅当前 App 画面（ReplayKit 系统限制）

iOS 不能录制系统桌面、通知栏、控制中心，也不能录制切换到其他 App 后的画面。若业务需要「整屏录 iOS」，需用户自行使用系统控制中心录屏，或另行开发 ReplayKit Broadcast Upload Extension（本插件未实现）。

⚠️ 防录屏 App 黑屏说明（使用前必读）

部分 App 开启了防录屏 / 防截屏（如银行、支付、视频 DRM、企业安全类应用），系统会阻止其画面被采集。整屏录制时，这些 App 在录屏文件中通常显示为黑屏，真机上可能仍正常显示。

• 这是系统与应用的安全策略，不是本插件故障，插件无法绕过。
• 集成方应在用户说明中提前告知：录屏无法保证捕获所有 App 的画面内容。
• 详见 使用规范 3.1.2。

平台支持

说明：四端 API 语义一致，但系统授权弹窗、录制范围、指示条样式由各平台决定，无法完全统一。

环境要求

• HBuilderX 4.24+（UTS 插件）
• uni-app Vue3（不支持 Vue2）
• 必须使用自定义基座或云打包，标准基座不包含 UTS 插件
• 修改插件原生代码后需 重新制作自定义基座 或 重新云打包

安装

方式一：插件市场（推荐）

在 DCloud 插件市场 搜索 m-screen-cast，导入到项目的 uni_modules 目录。

方式二：手动复制

将 m-screen-cast 文件夹复制到项目的 src/uni_modules/（或 uni_modules/）下，然后在 HBuilderX 中重新编译。

权限配置

安装插件后，还需在 宿主项目 的 manifest.json 中声明以下权限。

Android

在 app-plus.distribute.android.permissions 中添加：

"<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>",
"<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE\"/>",
"<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION\"/>",
"<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>"

建议 minSdkVersion 不低于 31（与插件一致）。targetSdkVersion 建议逐步升级至 34 以完整适配 Android 14 前台服务规范；targetSdkVersion 较低时在 Android 14 设备上仍可录屏，插件会按设备 API 自动适配。

iOS

在 app-plus.distribute.ios.privacyDescription 中添加：

{
  "NSMicrophoneUsageDescription": "录屏功能需要访问麦克风以录制环境声音",
  "NSPhotoLibraryAddUsageDescription": "需要将录屏视频保存到您的相册"
}

保存到相册时使用 uni.saveVideoToPhotosAlbum，需相册写入描述。

Harmony

插件已内置 ohos.permission.MICROPHONE 声明（utssdk/app-harmony/module.json5），安装后会自动合并到鸿蒙工程。

宿主项目无需重复声明麦克风权限，但需确保 manifest.json → app-harmony.distribute.bundleName 与签名证书一致。

快速开始

1. 引入 API

import {
  checkScreenCastSupport,
  startScreenCast,
  stopScreenCast,
  cancelScreenCast,
  getScreenCastStatusSync,
  getScreenCastFileUriSync,
  deleteScreenCastFile,
  openScreenCastFile,
} from '@/uni_modules/m-screen-cast'

2. 检查支持

checkScreenCastSupport({
  success(res) {
    if (!res.supported) {
      uni.showToast({ title: res.reason || '不支持录屏', icon: 'none' })
      return
    }
    console.log('支持格式', res.formats) // ['video/mp4']
    console.log('支持范围', res.captureScopes) // ['fullScreen'] 或 ['fullScreen', 'singleApp']
  },
})

3. 开始 / 停止录屏

// ⚠️ 必须由用户点击触发（button @click），否则系统授权弹窗不会出现

function handleStart() {
  startScreenCast({
    audio: true,
    captureScope: 'fullScreen', // 'fullScreen' | 'singleApp'（Android 14+）
    videoBitsPerSecond: 6000000,
    success() {
      uni.showToast({ title: '录制中', icon: 'none' })
    },
    fail(err) {
      uni.showToast({ title: err.errMsg, icon: 'none' })
    },
  })
}

function handleStop() {
  stopScreenCast({
    success(res) {
      console.log('文件路径', res.filePath)   // _doc/Movies/screen_xxx.mp4
      console.log('时长(ms)', res.durationMs)
      console.log('大小(bytes)', res.fileSize)
    },
    fail(err) {
      uni.showToast({ title: err.errMsg, icon: 'none' })
    },
  })
}

4. Promise 封装（可选）

插件原生 API 为 callback 风格。如需 async/await，可自行封装：

function callScreenCast(api, options = {}) {
  return new Promise((resolve, reject) => {
    api({
      ...options,
      success: resolve,
      fail: reject,
    })
  })
}

async function recordDemo() {
  const support = await callScreenCast(checkScreenCastSupport)
  if (!support.supported) return

  await callScreenCast(startScreenCast, { audio: true })
  await new Promise((r) => setTimeout(r, 5000))
  const result = await callScreenCast(stopScreenCast)
  console.log(result.filePath)
}

API 文档

checkScreenCastSupport(options)

检查当前环境是否支持录屏。

success 回调参数 ScreenCastSupportResult：

startScreenCast(options)

开始录屏。调用后会依次触发：

1. 麦克风权限申请（audio !== false 时）
2. 系统录屏授权弹窗（Android / Harmony）
3. Android 14+：启动 ScreenCastForegroundService 并 startForeground，再创建 MediaProjection
4. 录制开始

参数：

captureScope 说明（Android）：

iOS / Harmony 忽略 captureScope。

success 回调参数：

stopScreenCast(options)

停止录屏并保存文件。

success 回调参数 StopScreenCastResult：

cancelScreenCast(options)

取消录制，不保存文件。适用于用户主动放弃录制的场景。

getScreenCastStatusSync()

同步获取当前录制状态（无回调）。推荐配合 @/utils/screen-cast 的 createScreenCast() 使用 refreshStatus() / statusChange 事件。

返回值 ScreenCastStatus：

onScreenCastStatusChange(options) / offScreenCastStatusChange(options)

注册 / 取消录屏状态变化监听（Android 已实现；业务层推荐直接用 createScreenCast().on('statusChange')）。

参数： { callback: (res) => void }

回调 ScreenCastStatusChangeResult：

getScreenCastFileUriSync(filePath)

将 _doc/... 沙盒路径转为平台可播放 / 分享的 URI。

• Android：content:// FileProvider URI
• iOS / Harmony：file:// 绝对路径

用于 <video> 组件、uni.previewMedia 或分享。

deleteScreenCastFile(options)

删除指定录制文件。

参数： { filePath: string }

success 回调： { deleted: boolean }

openScreenCastFile(options)

使用系统能力打开 / 预览录制视频。

参数： { filePath: string }

错误码

输出文件

各端统一保存在应用沙盒：

_doc/Movies/screen_<timestamp>.mp4

平台差异

打包说明

1. 在 HBuilderX 中 制作自定义调试基座（含 UTS 插件）
2. 真机调试确认功能正常
3. 使用 云打包 或 本地打包 生成正式包
4. 鸿蒙 release 包若白屏，请关闭 ArkTS 混淆（参见 使用规范）

常见问题

Q：标准基座调用报错或找不到插件？
A：UTS 插件必须打入自定义基座，标准基座不包含本插件。

Q：Android 14+ 可以只录单个 App 吗？
A：可以。设置 captureScope: 'singleApp'，系统会弹出应用选择器，由用户选定要录制的应用。Android 未提供「完全隐藏整屏选项」的 API，单应用模式仍依赖系统 UI。Android 12～13 仅支持整屏。

Q：Android 14 录屏启动失败，报 SecurityException: MediaProjections require a foreground service？
A：确认已声明 FOREGROUND_SERVICE、FOREGROUND_SERVICE_MEDIA_PROJECTION，且已 重新制作自定义基座（1.0.8+ 已修复前台服务启动顺序）。插件会在 getMediaProjection 之前自动启动 ScreenCastForegroundService。

Q：iOS 只能录当前 App？
A：是。Apple ReplayKit 的系统限制，普通 App 内 API 只能录制本 App 窗口内容，无法录制其他 App、系统桌面或切出 App 后的画面。本插件使用 RPScreenRecorder，与 Android / Harmony 的整屏能力不同，集成前请确认产品预期。整屏方案需 Broadcast Upload Extension，不在本插件范围内。

Q：鸿蒙 release 白屏？
A：多为 ArkTS 混淆与 Vue3 组合式 API 冲突，参见 使用规范。

Q：真机上 Toast/弹窗正常，录屏文件里却是黑块或看不到提示？
A：Android 整屏录制由 MediaProjection 采集系统合成画面，系统原生 Toast、返回键过渡黑场等与肉眼所见不一致是常见平台现象，非插件可改范围。若成片必须包含提示，请让宿主 App 使用 App 内 UI 而非依赖系统 Toast。详见 使用规范 3.1.1。

Q：录屏时某些 App（银行、支付、视频）画面是黑屏？
A：目标 App 启用了防录屏 / 防截屏（Android FLAG_SECURE、iOS 屏幕捕获保护、DRM 等），系统会主动屏蔽其画面，录屏文件中显示黑屏属正常现象，插件无法绕过。请在产品说明中提前告知用户。详见 使用规范 3.1.2。

Q：stop 返回 fileSize 为 0？
A：录制时间过短，建议至少录制 1 秒后再停止。

隐私与合规

• 录屏涉及用户屏幕内容和可能的音频，必须在 UI 明确告知并获得用户主动授权
• 不得在用户不知情的情况下后台录屏
• 录制文件存储在应用沙盒，上传或分享需另行获得用户同意
• 上架 App Store / 华为应用市场时，需在隐私政策中说明录屏功能用途

相关文档

• 使用规范 — 集成约束、最佳实践、审核建议
• 更新日志

链接

• uni-app UTS 插件文档
• Android MediaProjection
• Harmony AVScreenCaptureRecorder