Flutter使用widget_screenshot截取长截图时触发断言错误

问题根源 #

报错核心是RenderRepaintBoundary.toImage()方法在控件仍处于待绘制状态（debugNeedsPaint为true）时被调用，Flutter渲染机制禁止这种操作。仅长屏幕设备触发的原因：

• 长屏幕下EMSensors中的ListView包含更多内容，控件完整绘制的耗时更长；
• 截图触发时机（点击事件）与界面重绘（滚动、数据更新）的时机重叠，导致截图时控件未完成绘制。

解决方案 #

1. 等待帧绘制完成后执行截图 #

在触发截图的点击回调中，先等待当前帧绘制完成，确保控件处于稳定状态：

// 替换HomePageTopAppBar中触发截图的代码逻辑
onTap: () async {
  // 等待当前帧绘制结束
  await WidgetsBinding.instance.endOfFrame;
  // 执行截图操作
  final image = await WidgetShotController.of(headerEMKey).capture();
  // 后续图片处理逻辑
}

2. 避免滚动状态下触发截图 #

如果截图目标是可滚动控件（如EMSensors里的ListView），先将滚动控件定位到固定位置，等待滚动动画结束后再截图：

// 截图前先滚动到顶部并等待动画完成
await scrollController.animateTo(
  0,
  duration: const Duration(milliseconds: 300),
  curve: Curves.easeInOut,
);
// 再次等待绘制完成
await WidgetsBinding.instance.endOfFrame;
// 执行截图
final image = await WidgetShotController.of(sensorsEMKey).capture();

3. 手动兼容绘制状态检查 #

如果上述方法无效，可手动获取渲染对象并添加绘制状态校验，确保截图时机合法：

Future<Uint8List?> captureWidget(GlobalKey key, BuildContext context) async {
  await WidgetsBinding.instance.endOfFrame;
  final renderObject = key.currentContext?.findRenderObject() as RenderRepaintBoundary?;
  
  if (renderObject == null || renderObject.debugNeedsPaint) {
    // 若仍需绘制，延迟后重试
    await Future.delayed(const Duration(milliseconds: 50));
    return captureWidget(key, context);
  }

  final image = await renderObject.toImage(pixelRatio: MediaQuery.of(context).devicePixelRatio);
  final byteData = await image.toByteData(format: ImageByteFormat.png);
  return byteData?.buffer.asUint8List();
}

额外注意事项 #

• 避免在setState执行过程中触发截图，确保界面状态稳定后再执行截图操作；
• 检查RefreshIndicator的刷新逻辑，不要在数据刷新过程中触发截图，防止重绘冲突。

内容的提问来源于stack exchange，提问作者Lean966