App端截图不能直接用canvas导出,因web-view与原生渲染层隔离,canvas仅能捕获自身绘制内容,无法抓取DOM或原生组件;必须调用原生API(Android用View截图、iOS用keyWindow截图),推荐使用uni-plugin-screenshot等原生插件实现。

uni-app App端截图为什么不能直接用 canvas 导出?
因为 App 端(尤其是 iOS)的 web-view 和原生渲染层隔离,canvas 只能捕获自身绘制内容,无法抓取页面真实 DOM 或原生组件(如 map、video、camera、自定义导航栏等)。直接调用 uni.canvasToTempFilePath 会返回空白图或黑图。
真正可行的方案是调用原生能力:Android 走 View 截图,iOS 走 UIApplication.shared.keyWindow 截图。uni-app 官方未封装该能力,需通过原生插件或条件编译调用。
- 纯 H5 或小程序端可用
dom-to-image或html2canvas,但 App 端无效 - App 端必须走原生 API,否则截不到状态栏、软键盘、原生弹窗、系统控件
- uni-app 的
uni.getScreenCapture仅支持微信小程序,App 端不存在该 API
使用 uni-app 原生插件实现真机截图(推荐方案)
目前最稳定的方式是接入已封装好的原生插件,例如:uni-plugin-screenshot(GitHub 开源,支持 Android/iOS,更新活跃)。
安装后在 pages.json 中配置插件权限(iOS 需加 NSPhotoLibraryUsageDescription),然后在页面中调用:
const screenshot = uni.requireNativePlugin('Screenshot');
screenshot.capture({
quality: 100,
format: 'png'
}, (res) => {
if (res.tempFilePath) {
uni.saveImageToPhotosAlbum({
filePath: res.tempFilePath,
success: () => uni.showToast({ title: '已保存到相册' })
});
}
});
- 插件内部自动处理了 iOS 的 window 层级问题(如避开状态栏遮挡)
- Android 上注意 targetSdkVersion ≥ 30 时需申请
android.permission.READ_MEDIA_IMAGES - 截图结果为本地临时路径(
file://协议),不能直接传给uni.uploadFile,需先用uni.getFileInfo获取 size 后再上传
条件编译 + 原生代码扩展(进阶可控方案)
若需自定义截图区域、忽略某些元素或添加水印,建议用条件编译 + 原生扩展:
在 platforms/app-plus/nativePlugins/ 下新建插件目录,Android 写 ScreenCapture.java,iOS 写 ScreenCapture.m,暴露 capture 方法供 JS 调用。
- Android 示例关键点:用
activity.getWindow().getDecorView().getRootView()获取根视图,再setDrawingCacheEnabled(true)+getDrawingCache() - iOS 示例关键点:用
[UIScreen mainScreen].snapshotImage(iOS 7+),避免截到黑屏需确保调用时机在viewDidAppear:之后 - JS 层统一调用:
uni.requireNativePlugin('custom-screenshot').capture({...}),保持跨平台接口一致 - 不建议在
onLoad或onShow立即截图——页面可能尚未完成渲染,应加setTimeout(() => {...}, 100)或监听uni.$on('page-ready')
截图后保存图片失败的常见原因
即使截图成功,uni.saveImageToPhotosAlbum 仍可能报错,典型错误包括:
-
errCode: -1, errMsg: "saveImageToPhotosAlbum:fail no permission"→ 检查manifest.json中是否勾选「相册」权限,iOS 还需在Info.plist添加NSPhotoLibraryUsageDescription -
errCode: -2, errMsg: "saveImageToPhotosAlbum:fail invalid file path"→ 路径不是file://开头,或文件已被释放(插件未持久化保存) - 安卓部分厂商(如华为 EMUI)限制后台截图,需引导用户手动授权「显示在其他应用上方」和「无障碍服务」
- 截图尺寸过大(如全面屏 1440×3200)导致内存溢出,建议压缩:插件层加
maxWidth/maxHeight参数,或 JS 层用uni.compressImage二次处理
真机调试时务必在 App.vue 的 onLaunch 中初始化权限检查,而不是等到点击截图按钮才申请——iOS 弹窗拒绝一次后,再次调用不会再次提示。











