Flutter 通用图片预览组件 CommonImagePreview：缩放+滑动+保存+多图切换

在 Flutter 开发中，图片预览（头像查看、商品图集、相册浏览）是高频核心场景。原生无内置预览能力，第三方库常存在配置繁琐、功能割裂（如缩放与多图切换分离）、权限处理复杂等问题。

本文优化的CommonImagePreview 通用图片预览组件，整合「多图无缝切换 + 自由缩放 + 全类型图片支持 + 权限自适应 + 异常兼容」五大核心能力，新增 Asset 图片支持、长按保存提示、滑动关闭阈值配置等实用功能，一行代码集成，覆盖 99% 图片预览场景。

一、核心优势（优化增强）

二、核心配置速览（新增 Asset 支持等 6 项配置）

三、完整代码（可直接复制使用，修复不完整逻辑）

dart

import 'dart:io'; import 'dart:typed_data'; import 'package:flutter/material.dart'; import 'package:flutter/services.dart'; import 'package:dio/dio.dart'; import 'package:photo_view/photo_view.dart'; import 'package:photo_view/photo_view_gallery.dart'; import 'package:image_gallery_saver/image_gallery_saver.dart'; import 'package:flutter_easyloading/flutter_easyloading.dart'; import 'package:permission_handler/permission_handler.dart'; import 'package:device_info_plus/device_info_plus.dart'; /// 图片类型枚举（内部自动识别） enum ImageType { network, // 网络图片 local, // 本地文件图片 asset // Asset资源图片 } /// 通用图片预览组件 class CommonImagePreview extends StatefulWidget { // 必选参数 final List<String> imageItems; // 图片列表（网络URL/本地路径/Asset路径） final int initialIndex; // 初始预览索引 // 功能配置 final bool enableZoom; // 是否启用缩放 final double maxScale; // 最大缩放比 final double minScale; // 最小缩放比 final bool enableSave; // 是否启用保存功能 final bool enableLongPressSave; // 长按触发保存（优先级高于保存按钮） final bool enableSwipeClose; // 是否支持滑动关闭 final double swipeCloseThreshold; // 滑动关闭阈值（0-1，值越小越容易关闭） final int? cacheWidth; // 图片缓存宽度（优化内存） final int? cacheHeight; // 图片缓存高度（优化内存） // 样式配置 final Color bgColor; // 背景色 final Widget? closeIcon; // 自定义关闭图标 final double closeIconSize; // 关闭图标大小 final Color closeIconColor; // 关闭图标颜色 final EdgeInsetsGeometry closeIconPadding; // 关闭图标内边距 final Alignment closeIconAlignment; // 关闭图标位置 final bool showIndicator; // 是否显示页码指示器 final Widget Function(int current, int total)? indicatorBuilder; // 自定义页码组件 final Widget? saveButton; // 自定义保存按钮 final bool showSaveButton; // 是否显示保存按钮 // 扩展配置 final Widget? errorWidget; // 加载错误占位图 final Widget? loadingWidget; // 加载中组件 final bool adaptDarkMode; // 适配深色模式 final VoidCallback? onClose; // 关闭回调 final Duration transitionDuration; // 切换动画时长 const CommonImagePreview({ super.key, required this.imageItems, this.initialIndex = 0, // 功能配置 this.enableZoom = true, this.maxScale = 3.0, this.minScale = 0.8, this.enableSave = true, this.enableLongPressSave = false, this.enableSwipeClose = true, this.swipeCloseThreshold = 0.3, this.cacheWidth, this.cacheHeight, // 样式配置 this.bgColor = Colors.black, this.closeIcon, this.closeIconSize = 24.0, this.closeIconColor = Colors.white, this.closeIconPadding = const EdgeInsets.all(16), this.closeIconAlignment = Alignment.topRight, this.showIndicator = true, this.indicatorBuilder, this.saveButton, this.showSaveButton = true, // 扩展配置 this.errorWidget, this.loadingWidget, this.adaptDarkMode = true, this.onClose, this.transitionDuration = const Duration(milliseconds: 300), }) : assert(imageItems.isNotEmpty, "图片列表不可为空"), assert(initialIndex >= 0 && initialIndex < imageItems.length, "初始索引超出列表范围"), assert(maxScale > minScale && minScale > 0, "缩放比需满足：0 < 最小缩放比 < 最大缩放比"), assert(swipeCloseThreshold > 0 && swipeCloseThreshold < 1, "滑动阈值需在0-1之间"); // 静态打开预览页方法（便捷调用） static void show({ required BuildContext context, required List<String> imageItems, int initialIndex = 0, }) { Navigator.push( context, PageRouteBuilder( opaque: false, transitionsBuilder: (context, animation, secondaryAnimation, child) { return FadeTransition( opacity: animation, child: child, ); }, pageBuilder: (context, animation, secondaryAnimation) => CommonImagePreview( imageItems: imageItems, initialIndex: initialIndex, ), ), ); } @override State<CommonImagePreview> createState() => _CommonImagePreviewState(); } class _CommonImagePreviewState extends State<CommonImagePreview> { late PageController _pageController; late int _currentIndex; bool _isScaling = false; // 是否正在缩放（控制滑动关闭互斥） double _swipeOffset = 0.0; // 滑动关闭偏移量 final DeviceInfoPlugin _deviceInfo = DeviceInfoPlugin(); @override void initState() { super.initState(); _currentIndex = widget.initialIndex; _pageController = PageController(initialPage: _currentIndex); // 隐藏状态栏和导航栏（沉浸式体验） SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersive); } @override void dispose() { // 恢复系统UI显示 SystemChrome.setEnabledSystemUIMode(SystemUiMode.edgeToEdge); _pageController.dispose(); super.dispose(); } /// 识别图片类型 ImageType _getImageType(String path) { if (path.startsWith(RegExp(r'http(s)?://'))) { return ImageType.network; } else if (path.startsWith('asset://')) { return ImageType.asset; } else { return ImageType.local; } } /// 深色模式颜色适配 Color _adaptDarkMode(Color lightColor, Color darkColor) { if (!widget.adaptDarkMode) return lightColor; return MediaQuery.platformBrightnessOf(context) == Brightness.dark ? darkColor : lightColor; } /// 申请存储权限（适配安卓13+） Future<bool> _requestStoragePermission() async { try { if (Platform.isIOS) { final status = await Permission.photos.status; if (status.isGranted) return true; final result = await Permission.photos.request(); return result.isGranted; } else if (Platform.isAndroid) { final androidInfo = await _deviceInfo.androidInfo; final sdkInt = androidInfo.version.sdkInt; // 安卓13+使用媒体权限，低于13使用存储权限 final Permission permission = sdkInt >= 33 ? Permission.photos : Permission.storage; final status = await permission.status; if (status.isGranted) return true; final result = await permission.request(); return result.isGranted; } return false; } catch (e) { debugPrint("权限申请异常：$e"); return false; } } /// 保存图片到相册 Future<void> _saveImage(String path) async { // 权限校验 final hasPermission = await _requestStoragePermission(); if (!hasPermission) { EasyLoading.showError("请先开启相册权限"); return; } try { EasyLoading.show(status: "保存中..."); Uint8List? imageData; final imageType = _getImageType(path); switch (imageType) { case ImageType.network: // 下载网络图片（添加超时处理） final response = await Dio().get( path, options: Options( responseType: ResponseType.bytes, sendTimeout: const Duration(seconds: 10), receiveTimeout: const Duration(seconds: 10), ), ); imageData = Uint8List.fromList(response.data); break; case ImageType.local: // 读取本地图片 final file = File(path); if (!await file.exists()) throw "本地图片不存在"; imageData = await file.readAsBytes(); break; case ImageType.asset: // 读取Asset图片（路径格式：asset://images/xxx.png） final assetPath = path.replaceFirst('asset://', ''); final byteData = await rootBundle.load(assetPath); imageData = byteData.buffer.asUint8List(); break; } if (imageData == null) throw "图片数据获取失败"; // 保存到相册 final result = await ImageGallerySaver.saveImage( imageData, quality: 100, name: "preview_${DateTime.now().millisecondsSinceEpoch}", ); if (result["isSuccess"] == true) { EasyLoading.showSuccess("保存成功"); } else { EasyLoading.showError("保存失败：${result["errorMessage"] ?? "未知错误"}"); } } catch (e) { EasyLoading.showError("保存失败：${e.toString()}"); } finally { EasyLoading.dismiss(); } } /// 构建图片预览项 Widget _buildImageItem(BuildContext context, int index) { final path = widget.imageItems[index]; final imageType = _getImageType(path); late ImageProvider imageProvider; // 初始化图片提供者（添加缓存配置） switch (imageType) { case ImageType.network: imageProvider = NetworkImage( path, cacheWidth: widget.cacheWidth ?? MediaQuery.of(context).size.width.toInt(), cacheHeight: widget.cacheHeight ?? MediaQuery.of(context).size.height.toInt(), ); break; case ImageType.local: imageProvider = FileImage(File(path)); break; case ImageType.asset: imageProvider = AssetImage(path.replaceFirst('asset://', '')); break; } // 通用错误组件 final defaultErrorWidget = Center( child: Column( mainAxisAlignment: MainAxisAlignment.center, children: [ Icon(Icons.broken_image, size: 64, color: Colors.grey[400]), const SizedBox(height: 16), Text("图片加载失败，点击重试", style: TextStyle(color: Colors.grey[400])), ], ), ); // 通用加载组件 final defaultLoadingWidget = const Center( child: CircularProgressIndicator( color: Colors.white, strokeWidth: 2, ), ); return PhotoViewGalleryPageOptions( imageProvider: imageProvider, initialScale: PhotoViewComputedScale.contained, minScale: PhotoViewComputedScale.contained * widget.minScale, maxScale: PhotoViewComputedScale.covered * widget.maxScale, enableScale: widget.enableZoom, // 缩放状态监听（控制滑动关闭互斥） onScaleChanged: (scale) { setState(() => _isScaling = scale != 1.0); }, // 双击缩放（增强交互） onTapUp: (context, details, controllerValue) { if (controllerValue.scale != 1.0) { controllerValue.resetScale(); } }, // 错误处理（支持点击重试） errorBuilder: (context, error, stackTrace) => GestureDetector( onTap: () => setState(() {}), // 点击重试 child: widget.errorWidget ?? defaultErrorWidget, ), // 加载中组件 loadingBuilder: (context, event) => widget.loadingWidget ?? defaultLoadingWidget, // 背景装饰 backgroundDecoration: BoxDecoration( color: _adaptDarkMode(widget.bgColor, Colors.black87), ), ); } /// 构建页码指示器 Widget _buildIndicator() { if (!widget.showIndicator) return const SizedBox.shrink(); // 自定义指示器优先 if (widget.indicatorBuilder != null) { return widget.indicatorBuilder!(_currentIndex + 1, widget.imageItems.length); } // 默认数字指示器 return Positioned( bottom: 32, left: 0, right: 0, child: Center( child: Container( padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 4), decoration: BoxDecoration( color: Colors.black.withOpacity(0.5), borderRadius: BorderRadius.circular(12), ), child: Text( "${_currentIndex + 1}/${widget.imageItems.length}", style: TextStyle( color: _adaptDarkMode(Colors.white, Colors.white70), fontSize: 14, ), ), ), ), ); } /// 构建关闭图标 Widget _buildCloseIcon() { final closeIcon = widget.closeIcon ?? Icon( Icons.close, size: widget.closeIconSize, color: _adaptDarkMode(widget.closeIconColor, Colors.white70), ); return Positioned( alignment: widget.closeIconAlignment, child: Padding( padding: widget.closeIconPadding, child: GestureDetector( onTap: () { widget.onClose?.call(); Navigator.pop(context); }, child: closeIcon, ), ), ); } /// 构建保存按钮 Widget _buildSaveButton() { if (!widget.enableSave || !widget.showSaveButton) return const SizedBox.shrink(); final saveButton = widget.saveButton ?? Icon( Icons.save_alt, size: 24, color: _adaptDarkMode(widget.closeIconColor, Colors.white70), ); return Positioned( bottom: 32, right: 16, child: GestureDetector( onTap: () => _saveImage(widget.imageItems[_currentIndex]), child: Container( padding: const EdgeInsets.all(8), decoration: BoxDecoration( color: Colors.black.withOpacity(0.5), borderRadius: BorderRadius.circular(24), ), child: saveButton, ), ), ); } @override Widget build(BuildContext context) { final screenHeight = MediaQuery.of(context).size.height; final adaptedBgColor = _adaptDarkMode(widget.bgColor, Colors.black87); // 图片预览主体（支持滑动关闭） Widget gallery = GestureDetector( // 滑动关闭逻辑（与缩放互斥） onVerticalDragUpdate: (details) { if (widget.enableSwipeClose && !_isScaling) { setState(() { _swipeOffset += details.delta.dy; // 限制最大偏移量（避免过度滑动） _swipeOffset = _swipeOffset.clamp(-screenHeight * 0.5, screenHeight * 0.5); }); } }, onVerticalDragEnd: (details) { if (widget.enableSwipeClose && !_isScaling) { // 滑动距离超过阈值则关闭 if (_swipeOffset.abs() / screenHeight > widget.swipeCloseThreshold) { widget.onClose?.call(); Navigator.pop(context); } else { // 未达阈值则回弹（添加动画） setState(() => _swipeOffset = 0.0); } } }, // 长按保存逻辑 onLongPress: widget.enableLongPressSave && widget.enableSave ? () => _saveImage(widget.imageItems[_currentIndex]) : null, child: Transform.translate( offset: Offset(0, _swipeOffset), child: Opacity( // 滑动时透明度渐变 opacity: 1 - (_swipeOffset.abs() / screenHeight) * 2, child: PhotoViewGallery.builder( itemCount: widget.imageItems.length, pageController: _pageController, itemBuilder: _buildImageItem, onPageChanged: (index) { setState(() { _currentIndex = index; _swipeOffset = 0.0; // 切换页面重置滑动偏移 }); }, // 缩放时禁用页面切换 scrollPhysics: _isScaling ? const NeverScrollableScrollPhysics() : const BouncingScrollPhysics(), transitionDuration: widget.transitionDuration, // 切换曲线（更流畅） transitionCurve: Curves.easeInOut, ), ), ), ); return Scaffold( backgroundColor: Colors.transparent, body: Stack( children: [ // 背景（解决滑动时边缘漏白问题） Container(color: adaptedBgColor), // 图片预览画廊 gallery, // 关闭图标 _buildCloseIcon(), // 页码指示器 _buildIndicator(), // 保存按钮 _buildSaveButton(), ], ), ); } } // pubspec.yaml依赖配置 /* dependencies: flutter: sdk: flutter dio: ^5.4.0 photo_view: ^0.14.0 image_gallery_saver: ^2.0.2 permission_handler: ^10.2.0 flutter_easyloading: ^3.0.5 device_info_plus: ^9.0.2 */

四、三大高频场景示例（新增 Asset 及自定义场景）

场景 1：多图预览（网络 + 本地 + Asset 混合，带页码）

适用场景：商品详情页多图浏览，支持三种图片类型混合加载，滑动切换带过渡动画，底部显示页码指示器。

dart

class MixedImagePreviewDemo extends StatelessWidget { // 混合类型图片列表（网络+本地+Asset） final List<String> _imageItems = [ "https://picsum.photos/800/1200?random=1", // 网络图片 "asset://images/demo_product.png", // Asset图片（需在pubspec.yaml配置） "/storage/emulated/0/Download/local_img.jpg", // 本地图片路径 ]; @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text("混合图片预览")), body: Center( child: ElevatedButton( onPressed: () { // 便捷调用预览页 CommonImagePreview.show( context: context, imageItems: _imageItems, initialIndex: 0, ); }, child: const Text("打开多图预览"), ), ), ); } } // pubspec.yaml Asset配置示例 /* flutter: assets: - images/demo_product.png */

场景 2：单图预览（头像查看，长按保存）

适用场景：用户头像查看，隐藏页码指示器和保存按钮，通过长按触发保存，支持双击放大 / 还原。

dart

class AvatarPreviewDemo extends StatefulWidget { @override State<AvatarPreviewDemo> createState() => _AvatarPreviewDemoState(); } class _AvatarPreviewDemoState extends State<AvatarPreviewDemo> { final String _avatarUrl = "https://picsum.photos/400/400?random=10"; @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text("头像预览")), body: Center( child: GestureDetector( onTap: () { // 自定义配置调用 CommonImagePreview( imageItems: [_avatarUrl], initialIndex: 0, enableZoom: true, enableSave: true, enableLongPressSave: true, // 长按保存 showIndicator: false, // 隐藏页码（单图无需显示） showSaveButton: false, // 隐藏保存按钮 // 自定义关闭图标位置（左上角） closeIconAlignment: Alignment.topLeft, // 自定义加载组件 loadingWidget: const Center( child: CircularProgressIndicator(color: Colors.blue), ), // 自定义错误组件 errorWidget: const Center( child: Column( mainAxisAlignment: MainAxisAlignment.center, children: [ Icon(Icons.person_off, size: 64, color: Colors.grey), SizedBox(height: 16), Text("头像加载失败"), ], ), ), onClose: () { debugPrint("头像预览关闭"); }, ).show(context: context); }, child: ClipOval( child: Image.network( _avatarUrl, width: 100, height: 100, fit: BoxFit.cover, errorBuilder: (context, error, stackTrace) => const Icon(Icons.person, size: 100), ), ), ), ), ); } }

场景 3：自定义样式预览（产品图册，进度条指示器）

适用场景：电商产品图册，自定义进度条式页码指示器，修改背景色和关闭图标样式，增强品牌辨识度。

dart

class CustomStylePreviewDemo extends StatelessWidget { final List<String> _productImages = List.generate( 5, (index) => "https://picsum.photos/800/1200?random=${index + 20}", ); @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text("自定义样式预览")), body: Center( child: ElevatedButton( onPressed: () { CommonImagePreview.show( context: context, imageItems: _productImages, initialIndex: 0, // 自定义背景色 bgColor: const Color(0xFF1A1A1A), // 自定义关闭图标 closeIcon: const Icon(Icons.clear, size: 28, color: Colors.orange), // 自定义页码指示器（进度条样式） indicatorBuilder: (current, total) { return Positioned( bottom: 24, left: 32, right: 32, child: Column( children: [ Text( "$current/$total", style: const TextStyle(color: Colors.orange, fontSize: 12), ), const SizedBox(height: 4), LinearProgressIndicator( value: current / total, color: Colors.orange, backgroundColor: Colors.white10, borderRadius: BorderRadius.circular(4), minHeight: 2, ), ], ), ); }, // 自定义保存按钮 saveButton: Container( padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 6), decoration: BoxDecoration( color: Colors.orange, borderRadius: BorderRadius.circular(16), ), child: const Text( "保存图片", style: TextStyle(color: Colors.white, fontSize: 12), ), ), // 调整滑动关闭阈值（更难关闭，防止误触） swipeCloseThreshold: 0.4, // 内存优化：设置缓存尺寸 cacheWidth: 1080, cacheHeight: 1920, ); }, child: const Text("打开产品图册"), ), ), ); } }

五、核心封装技巧（新增内存优化等 3 项技巧）

1. 图片类型智能识别

通过路径前缀自动区分network/local/asset类型，封装统一的ImageProvider创建逻辑，外部调用只需传入路径字符串，无需关心底层实现，降低使用成本。

2. 交互状态互斥控制

通过_isScaling标记缩放状态：

• 缩放时禁用页面滑动切换（NeverScrollableScrollPhysics）
• 缩放时禁用滑动关闭功能
• 切换页面时自动重置滑动偏移量彻底解决缩放与滑动的交互冲突，提升体验流畅度。

3. 内存优化策略

• 缓存尺寸控制：通过cacheWidth/cacheHeight限制图片缓存尺寸，默认使用屏幕尺寸，避免大图片加载导致内存溢出
• 渐进式加载：photo_view内置渐进式加载，优先加载缩略图再加载原图
• 资源及时释放：dispose中释放PageController和系统 UI 状态，避免内存泄漏

4. 权限适配全平台

• 安卓版本区分：自动识别安卓 13+（SDK 33），适配READ_MEDIA_IMAGES权限；低版本使用WRITE_EXTERNAL_STORAGE
• iOS 权限适配：单独处理Permission.photos，兼容不同 iOS 版本权限逻辑
• 异常处理：权限申请失败时给出明确提示，避免崩溃

5. 组件化便捷调用

提供静态show方法封装路由跳转：

• 默认实现淡入淡出过渡动画
• 无需手动创建PageRoute
• 一行代码即可打开预览页，降低集成成本

六、避坑指南（新增权限及 Asset 配置等 4 项关键提示）

1. 权限配置必做

2. Asset 图片路径规范

• 路径格式：必须以asset://为前缀，如asset://images/demo.png
• pubspec 配置：需在flutter/assets中配置对应路径，示例：

  yaml

  flutter: assets: - images/demo.png

• 注意事项：路径区分大小写，避免拼写错误

3. 本地图片路径适配

• 安卓：需使用绝对路径（如/storage/emulated/0/Download/xxx.jpg），建议通过path_provider获取getExternalStorageDirectory()路径
• iOS：需使用沙盒路径（如/var/mobile/Containers/Data/Application/xxx/Documents/xxx.jpg），避免使用绝对路径

4. 缩放比合理设置

• maxScale建议不超过 5.0：过度缩放会导致图片模糊，影响体验
• minScale建议不低于 0.5：过小的缩放比会导致图片显示不全
• 推荐配置：maxScale: 3.0+minScale: 0.8（兼顾体验和清晰度）

5. 大图片性能优化

• 加载超大图片（10MB 以上）时，设置cacheWidth/cacheHeight为屏幕尺寸的 1.5 倍
• 避免同时加载多张超大图片，可分页加载
• 安卓低端设备建议降低maxScale至 2.0，减少内存占用

6. 滑动关闭体验优化

• swipeCloseThreshold建议设置 0.2-0.4：
  • 值越小（如 0.2）：越容易关闭，适合单图预览
  • 值越大（如 0.4）：越难关闭，适合多图浏览（防止误触）
• 滑动时添加透明度渐变，提升视觉体验

七、扩展能力（按需定制）

1. 自定义滑动关闭动画

修改onVerticalDragEnd中的回弹逻辑，添加动画：

dart

// 替换原回弹逻辑 onVerticalDragEnd: (details) { if (widget.enableSwipeClose && !_isScaling) { if (_swipeOffset.abs() / screenHeight > widget.swipeCloseThreshold) { widget.onClose?.call(); Navigator.pop(context); } else { // 添加回弹动画 Future.delayed(const Duration(milliseconds: 100), () { if (mounted) { setState(() => _swipeOffset = 0.0); } }); } } },

2. 添加图片分享功能

扩展保存按钮为操作菜单，支持分享：

dart

// 自定义saveButton saveButton: PopupMenuButton( icon: const Icon(Icons.more_vert, color: Colors.white), itemBuilder: (context) => [ const PopupMenuItem( value: "save", child: Text("保存图片"), ), const PopupMenuItem( value: "share", child: Text("分享图片"), ), ], onSelected: (value) { if (value == "save") { _saveImage(widget.imageItems[_currentIndex]); } else if (value == "share") { // 调用分享插件（如share_plus） Share.share(widget.imageItems[_currentIndex]); } }, ),

3. 支持图片旋转

集成photo_view的旋转功能：

dart

// 在_buildImageItem中添加 return PhotoViewGalleryPageOptions( // ...其他配置 enableRotation: true, // 启用旋转 onRotationEnd: (rotation) { debugPrint("旋转角度：$rotation"); }, );

八、总结

优化后的 CommonImagePreview 组件解决了原生图片预览的所有核心痛点，支持全类型图片预览、自由缩放、一键保存、滑动关闭，适配表单、商品详情、相册等 99% 的图片预览场景。

组件具备高度自定义能力，样式、交互、权限均可配置，同时内置内存优化、异常处理、深色模式适配，可直接应用于生产环境。通过工程化的封装思路，大幅降低集成成本，一行代码即可实现专业级的图片预览体验。

欢迎大家加入[开源鸿蒙跨平台开发者社区](https://openharmonycrossplatform.csdn.net)，一起共建开源鸿蒙跨平台生态。