tmui4x 2.0(Vapor)

主题

TMUI4x2026-09-21
1610
6.4m

x-screenshot-s 截图与防截屏 ​

窗口截图、节点截图、系统截屏监测并回传当前页截图、防截屏 / 录屏检测。函数与类型均加 x 前缀，避免与官方同名冲突。一次性 API 使用 DCloud success / fail / complete。

兼容性 ​

HarmonyiOSAndroidWEB微信小程序
窗口支持，节点截图不建议支持支持节点截图部分支持监测 / 防截屏部分支持

Web 端窗口截图、防截屏返回 fail 1005 / 1008。微信端主动截图返回 fail 1005，xOnUserCaptureScreen 可监听但不回传图片。鸿蒙节点截图见注意事项。

调用 ​

ts
import {
  xTakeSnapshot,
  xTakeElementSnapshot,
  xOnUserCaptureScreen,
  xOffUserCaptureScreen,
  xSetUserCaptureScreen,
  xGetUserCaptureScreen,
  xOnScreenCapturedChange,
  xOffScreenCapturedChange,
  xIsScreenCaptured,
  xIsCaptureScreenEnabled,
  XTakeSnapshotOptions,
  XTakeElementSnapshotOptions
} from "@/uni_modules/x-screenshot-s"

xTakeSnapshot({
  format: "png",
  success: (res) => {
    console.log(res.path, res.width, res.height)
  }
} as XTakeSnapshotOptions)

const ele = uni.getElementById("shotBox")
xTakeElementSnapshot({
  ele: ele,
  format: "png",
  success: (res) => {
    uni.previewImage({
      current: res.path,
      urls: [res.path] as string[]
    })
  }
} as XTakeElementSnapshotOptions)

const listenId = xOnUserCaptureScreen((res) => {
  // res.path 为监测到系统截屏后，插件即时截取的当前窗口图，便于反馈上传
  console.log(res.path, res.systemPath)
})

xSetUserCaptureScreen({
  enable: false
})

const recordId = xOnScreenCapturedChange((res) => {
  console.log(res.captured)
})

xOffUserCaptureScreen(listenId)
xOffScreenCapturedChange(recordId)

方法 ​

名称说明
xTakeSnapshot截取当前窗口
xTakeElementSnapshot截取指定节点
xOnUserCaptureScreen监听用户系统截屏，返回监听 id；回调带当前窗口即时截图路径
xOffUserCaptureScreen移除截屏监听；不传 id 则移除本插件全部截屏监听
xSetUserCaptureScreenenable: true 允许截屏，false 禁止截屏 / 录屏
xGetUserCaptureScreen查询当前是否允许系统截屏
xOnScreenCapturedChange监听录屏 / 投屏 / 镜像变化，返回监听 id
xOffScreenCapturedChange移除录屏监听；不传 id 则全部移除
xIsScreenCaptured同步查询是否正在被录屏 / 投屏
xIsCaptureScreenEnabled同步查询是否允许系统截屏

旧 API getRootShotImage / getElementShotImage 已移除，请改用 xTakeSnapshot / xTakeElementSnapshot。

参数 ​

format：png（默认）或 jpg。节点 PNG 仅绘制目标 View，并临时去掉目标自身 background 以保留透明底；JPG 会合成父级背景。

quality：仅 JPG，范围 1-100，默认 90。

xSetUserCaptureScreen.enable：true 允许用户截屏，false 开启隐私保护。插件主动截图在 Android / iOS 上仍可用，方便应用内反馈。

错误码 ​

1001 截图失败，1002 未知错误，1003 元素无效，1004 宽高为 0，1005 当前平台不支持截图，1006 系统版本过低，1007 format 非法，1008 当前平台不支持该能力，1009 参数错误，1010 防截屏设置失败，1011 权限被拒绝。

平台差异 ​

Android

  • 窗口截图：Android 7.0+ 优先 PixelCopy，失败或已防截屏时回退 Canvas，并叠加 TextureView 画面。
  • 系统截屏监测：Android 14+ 使用 registerScreenCaptureCallback（需 DETECT_SCREEN_CAPTURE）。更低版本用 MediaStore / 截屏目录监听，建议授予 READ_MEDIA_IMAGES 或 READ_EXTERNAL_STORAGE。
  • 防截屏：FLAG_SECURE。
  • 录屏检测：Android 15+ addScreenRecordingCallback。

iOS

  • 截图：drawHierarchy(afterScreenUpdates: true)。
  • 系统截屏监测：userDidTakeScreenshotNotification，系统不提供原图，插件会即时截取当前页。
  • 防截屏：iOS 13+ 安全图层（iOS 15.1 不支持，fail 1010）。
  • 录屏 / 投屏：UIScreen.isCaptured + capturedDidChangeNotification。

HarmonyOS

  • 窗口截图：window.snapshot。
  • 节点截图：鸿蒙不支持按节点查找，见下方注意事项。
  • 系统截屏监测：window.on('screenshot')，随后即时截取当前窗口。
  • 防截屏：setWindowPrivacyMode，需 ohos.permission.PRIVACY_WINDOW。
  • 录屏 / 投屏：display.on('captureStatusChange') / display.isCaptured。

Web

  • 节点截图尽量转发元素 takeSnapshot。
  • 窗口截图、防截屏、系统截屏监测不可用。

微信小程序

  • 监听转发 wx.onUserCaptureScreen，不回传图片。
  • 防截屏转发 wx.setVisualEffectOnCapture。
  • 主动截图不可用。

注意事项 ​

使用前请打自定义基座。Android 无论本机系统都要打基座；iOS 在配好原生环境时可免打基座。修改 config.json / 权限后需重新打基座。

大尺寸截图占用内存较高，反馈上传后可自行删除缓存文件。

鸿蒙 xTakeElementSnapshot（建议不使用）：uni-app-x 鸿蒙不支持按节点查找（Vue id 落不到 ArkUI .id()）。插件会回退为窗口局部截图（按节点矩形裁剪 window.snapshot），不是真正的节点绘制。结果会带上叠在该区域上的其它内容，也不会去掉节点自身背景。需要节点截图请用 Android / iOS；鸿蒙请改用 xTakeSnapshot 截整窗。

版本 ​

版权归 https://xui.tmui.design 你不得修改及二次开发，仅供 TMUI4 会员商用使用。不得转给非 VIP 会员使用，一经查实数倍赔偿，并追究法律责任。

更新日志 ​

2.0.1（2026-08-20） ​

  • 修复鸿蒙节点截图 1001：不再用全局 componentSnapshot.get。改为当前页 UIContext.getComponentSnapshot()，找不到 ArkUI id 时按节点矩形裁剪 window.snapshot。

2.0.0（2026-08-20） ​

  • 破坏性变更：改为 DCloud 风格 x 前缀 API。getRootShotImage / getElementShotImage 分别更名为 xTakeSnapshot / xTakeElementSnapshot。
  • 新增系统截屏监测 xOnUserCaptureScreen / xOffUserCaptureScreen：检测到用户截屏后即时截取当前窗口并回传路径，方便反馈上传。
  • 新增防截屏 xSetUserCaptureScreen / xGetUserCaptureScreen / xIsCaptureScreenEnabled。
  • 新增录屏 / 投屏检测 xOnScreenCapturedChange / xOffScreenCapturedChange / xIsScreenCaptured。
  • 截图结果增加 width / height，JPG 支持 quality。
  • 鸿蒙去掉缺失的 HAR 依赖，改为 ETS 实现窗口 / 节点截图与隐私模式。
  • 对齐 Android / iOS / HarmonyOS / Web / 微信导出。

1.0.5（2026-05-21） ​

  • 修复 Android 节点 PNG 透明背景被合成白底：png 仅绘制目标 View，不再使用 PixelCopy/根节点裁剪（jpg 仍保留屏幕合成以呈现父级背景）。
  • 进一步：PNG 节点截图绘制时临时清除目标节点自身 background（uni 容器常自带白底），绘制完即时恢复；子节点 background 不受影响。

1.0.4（2026-05-21） ​

  • 修复 PNG 截图白底：iOS 设置 opaque=false（jpg 仍为不透明）；节点/窗口均使用 drawHierarchy(in:bounds)，避免 window 坐标截取导致黑图。
  • Android Canvas 回退路径从根 View 裁剪绘制，保留父级背景色。

1.0.3（2026-05-21） ​

  • 新增 format 参数，支持 png、jpg 保存格式，默认 png。
  • 修复节点内含视频/TextureView 等组件时截图黑屏（Android）：优先 PixelCopy 窗口拷贝，失败时回退 Canvas 并叠加 TextureView 画面；iOS 保持 drawHierarchy(afterScreenUpdates:true) 以保障常规页面截图正常。
  • 新增错误码 1007：format 参数非法。

1.0.2（2026-05-21） ​

  • 破坏性变更：API 改为 uni 标准 opts 回调风格
  • 已使用的项目升级前请阅读 readme 示例，不可直接替换旧版回调写法。

1.0.1（2025-07-27） ​

  • 兼容鸿蒙

1.0.0（2024-12-18） ​

  • 对屏幕截图保存(不需要权限),对指定截图进行保存,安卓,ios支持,web不支持.
最近更新