概述

Image组件在加载图片时会经历多个状态，包括加载中、加载成功和加载失败。合理管理这些状态是提升用户体验的关键。

加载状态分类

图片加载过程中主要有三种状态：

状态	说明	用户感知
loading	正在加载图片	显示加载指示器
success	图片加载成功	显示完整图片
error	图片加载失败	显示错误提示

加载状态管理流程

状态管理实现

1. 定义状态枚举

使用枚举类型明确定义三种状态，可以让代码更加清晰和易于维护。

enum ImageLoadState { loading, success, error }

2. 创建状态管理组件

class ImageLoader extends StatefulWidget {
  final String imageUrl;
  
  const ImageLoader({super.key, required this.imageUrl});

  @override
  State<ImageLoader> createState() => _ImageLoaderState();
}

class _ImageLoaderState extends State<ImageLoader> {
  ImageLoadState _loadState = ImageLoadState.loading;
  
  @override
  void initState() {
    super.initState();
    _loadImage();
  }
  
  Future<void> _loadImage() async {
    final imageProvider = NetworkImage(widget.imageUrl);
    final completer = Completer<void>();
    
    imageProvider.resolve(const ImageConfiguration()).addListener(
      ImageStreamListener((ImageInfo info, bool synchronousCall) {
        if (mounted) {
          setState(() {
            _loadState = ImageLoadState.success;
          });
          completer.complete();
        }
      }, onError: (dynamic exception, StackTrace? stackTrace) {
        if (mounted) {
          setState(() {
            _loadState = ImageLoadState.error;
          });
          completer.complete();
        }
      }),
    );
    
    await completer.future;
  }
  
  @override
  Widget build(BuildContext context) {
    return switch (_loadState) {
      ImageLoadState.loading => _buildLoadingWidget(),
      ImageLoadState.success => Image.network(widget.imageUrl),
      ImageLoadState.error => _buildErrorWidget(),
    };
  }
  
  Widget _buildLoadingWidget() {
    return Container(
      color: Colors.grey.shade200,
      child: const Center(
        child: CircularProgressIndicator(),
      ),
    );
  }
  
  Widget _buildErrorWidget() {
    return Container(
      color: Colors.grey.shade300,
      child: const Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(Icons.error, color: Colors.red, size: 48),
            SizedBox(height: 8),
            Text('图片加载失败', style: TextStyle(color: Colors.grey)),
          ],
        ),
      ),
    );
  }
}

关键技术点

1. ImageStreamListener

ImageStreamListener用于监听图片加载状态：

imageProvider.resolve(const ImageConfiguration()).addListener(
  ImageStreamListener(
    (ImageInfo info, bool synchronousCall) {
      // 加载成功回调
    },
    onError: (dynamic error, StackTrace? stackTrace) {
      // 加载失败回调
    },
  ),
);

2. mounted检查

在setState前检查mounted可以避免组件已销毁时更新状态：

if (mounted) {
  setState(() {
    _loadState = ImageLoadState.success;
  });
}

3. Completer使用

使用Completer可以等待图片加载完成：

final completer = Completer<void>();
// ... 监听逻辑
await completer.future;

使用示例

class MyPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ListView(
      children: const [
        SizedBox(height: 200, child: ImageLoader(imageUrl: 'https://picsum.photos/400/300')),
        SizedBox(height: 16),
        SizedBox(height: 200, child: ImageLoader(imageUrl: 'https://invalid-url.com')),
      ],
    );
  }
}

最佳实践

1. 始终提供加载状态：让用户知道图片正在加载
2. 处理错误情况：提供友好的错误提示和重试选项
3. 使用占位符：保持布局稳定，避免UI抖动
4. 考虑缓存策略：减少重复加载，提升性能
5. 添加动画效果：增强用户体验，使加载过程更生动

常见问题

Q1: 如何知道图片加载的具体进度？

A: 使用loadingBuilder可以获取加载进度：

Image.network(
  imageUrl,
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;
    
    final progress = (loadingProgress.cumulativeBytesLoaded / 
                     loadingProgress.expectedTotalBytes!);
    return CircularProgressIndicator(value: progress);
  },
)

Q2: 如何避免重复加载同一张图片？

A: Flutter会自动缓存图片，但可以手动控制：

Image.network(
  imageUrl,
  cacheWidth: 300,
  cacheHeight: 200,
)

Q3: 如何在加载失败时显示默认图片？

A: 使用errorBuilder：

Image.network(
  imageUrl,
  errorBuilder: (context, error, stackTrace) {
    return Image.asset('assets/default_image.png');
  },
)

总结

Image加载状态管理是提升用户体验的关键技术。通过合理使用ImageStreamListener、状态枚举和setState，可以创建出流畅、友好的图片加载体验。记住要处理好加载中的状态、加载成功和加载失败三种情况，为用户提供清晰的视觉反馈。

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net