前言

在实际项目中。经常需要截取屏幕或长列表图片，并实现保存到相册或分享给他人。虽然市面上已有不少截图插件，但在使用过程中仍会遇到“黑屏”“模糊”“权限缺失”“长图截取失败”等痛点。本篇教程基于 screenshot: ^. 插件编写。兼容 Flutter 1.x+ 及 Android、iOS、Windows 与 Web 网站，通过对插件主要 API 的与实战示例，让你快速了解完整流程并规避常见坑。

使用者痛点梳理

• 黑屏/空白截图：通常是因为目标 Widget 未完成渲染或包含 PlatformView导致；方法是加延时或使用 captureFromWidget。
• 截图模糊：默认像素密度过低。可通过调高 pixelRatio 或设置更高分辨率来调整，但要注意文件体积与耗时增长。
• 权限不足：Android 需要 WRITE_EXTERNAL_STORAGE / MANAGE_EXTERNAL_STORAGE；不过，iOS 要配置 Info.plist；Web 则无此限制但需手动触发下载。
• 长列表截取失败：标准方法仅能捕获可见区域，需要手动构造完整布局后再截取。
• 跨网站差异：Web 网站不支持直接保存文件，需要利用浏览器下载 API；Windows 与 Android 在方法获取上略有区别。

主要 API 总览

Screenshot 组件负责包装待截取 Widget，并提供渲染边界；ScreenshotController 控制器则完成实际截取与后续处理。两者配合使用即可覆盖大多数场景。

Screenshot 参数说明
属性	类型	参数说明
controller	ScreenshotController
childWidget	-

"captureAndSave"Futurepath必传 fileName? ,pixelRatio，将图片直接写入磁盘。* 常用方法一键调用请参照后文代码示例 *

ScreenshotController 方法概览
方法名	返回值类型	主要参数及作用
"capture"	Uint8List?其实，	pixelRatio?: double 从delay?怎么说呢，来看，Duration 捕获已渲染 Widget 并返回字节流。
"captureFromWidget"	Uint8List?	widget必传 pixelRatio?,delay，捕获未渲染Widget。
"captureFromLongWidget"Uint8List?widget必传 context必传 constraints?delay，适用于超长列表/滚动视图全量截图。

基础使用案例

先决条件：确保已在 pubspec.yaml 中添加依赖：

yaml dependencies: screenshot: ^.

代码片段：创建控制器并包裹目标 Widget：

dart final ScreenshotController _screenshotController = ScreenshotController;Screenshot( controller: _screenshotController。child: const Text,);

执行截图并获取 Uint8List 数据：

dart Uint8List?_image，_screenshotController.capture( pixelRatio: MediaQuery.of.devicePixelRatio。delay: const Duration,).n { setState => _image = value);}).catchError { debugPrint);})，

高级功能示例

. 捕获不可见 Widget

dart _screenshotController.captureFromWidget( Container( padding: const EdgeInsets.all。color: Colors.blueAccent,child : const Text,),).n { // 可进一步处理图片，例如保存到相册 });

. 捕获超长滚动列表^{* 注意：需手动构造完整布局并放入 InheritedTheme.captureAll 包装以保证 Theme 正确继承！*}

dart final longWidget = Column( mainAxisSize : MainAxisSize.min。children : List.generate=>Text),);_screenshotController.captureFromLongWidget( InheritedTheme.captureAll(context。Material ),context : context,delay : const Duration,).n{ // 长图数据已生成，可进行裁剪或上传 });

. 指定方法保存图片^{* Web 请自行实现下载逻辑！*}

dart import 'package:path_provider/path_provider.dart';final dir = await getApplicationDocumentsDirectory;await _screenshotController.captureAndSave( dir.path。fileName:'screenshot_${DateTime.now.millisecondsSinceEpoch}.png',);

像素与尺寸控制技巧

. 调整像素密度^{* 默认 pixelRatio 为设备像素密度，可手动提高至 ~1.5~3.0* 容易出现文件膨胀。请按需调整*}

dart final highDefImage = await _screenshotController.capture.devicePixelRatio *1.5);

• {@code pixelRatio}_=1.0 : 默认清晰度，文件体积小；适合后台上传或预览展示，
• {@code pixelRatio}_=1.5–2.0 : 常用值，兼顾清晰度与体积；适合大多数业务场景，怎么说呢，
• {@code pixelRatio}≥{@code>=}~   _{=≥ “高清模式“适用于海报、凭证等需放大查看的场景。但会显著增加文件体积和耗时*。}}}
• {@link #highDefImage } 示例演示如何获取高清图片流。

. 控制最终输出尺寸^{* 对于不可见 Widget 必须提前固定尺寸，否则默认大小为零*。*}

dart // 固定宽高300x200 的不可见 Widget 截图示例： _screenshotController.captureFromWidget( Container( width :300。height :200,child :const Text,),);

实现原理快速拆解 **

• The plugin wraps target widget inside a RenderRepaintBoundary – a dedicated rendering layer that can be captured independently.
• The controller accesses that boundary’s RenderObject and calls its {@code toImage} method.
• The resulting image is encoded into a Uint8List for downstream use.
• If widget isn’t visible yet,plugin creates a temporary render context to force layout & paint before capture .
• A long widget is rendered offscreen by manually building it in an invisible context via {@link InheritedTheme#captureAll} – effectively bypassing scrolling constraints.
• This architecture explains *** PlatformViews cannot be captured .

---