更新记录

1.0.0（2026-05-29）

1、基础录制视频功能

平台兼容性

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。

平台支持

说明：四端 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\"/>"

建议 targetSdkVersion 设为 34，minSdkVersion 不低于 31（与插件 minSdkVersion 一致）。

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']
  },
})

3. 开始 / 停止录屏

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

function handleStart() {
  startScreenCast({
    audio: true,
    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. 录制开始

参数：

success 回调参数：

stopScreenCast(options)

停止录屏并保存文件。

success 回调参数 StopScreenCastResult：

cancelScreenCast(options)

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

getScreenCastStatusSync()

同步获取当前录制状态（无回调）。

返回值 ScreenCastStatus：

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 录屏启动失败？
A：确认已声明 FOREGROUND_SERVICE_MEDIA_PROJECTION，并查看 logcat 是否有 SecurityException。

Q：iOS 只能录当前 App？
A：ReplayKit 系统限制，无法录制其他 App 或桌面。

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

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

隐私与合规

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

相关文档

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

链接

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