这一节主要讲三件事：Flutter 里的图片加载、本地资源的管理方式，以及网络图片该怎么处理。

Image Widget - 图片显示

实例：各种图片加载方式

// 从网络加载图片
Image.network(
  'https://example.com/image.png',
  width: 200,
  height: 200,
  fit: BoxFit.cover,
)
// 从本地资源加载图片
Image.asset('assets/images/logo.png')
// 从本地文件加载图片
Image.file(File('path/to/image.png'))
// 带加载状态的图片
Image.network(
  'https://example.com/image.png',
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;
    return Center(
      child: CircularProgressIndicator(
        value: loadingProgress.expectedTotalBytes != null
             loadingProgress.cumulativeBytesLoaded /
                loadingProgress.expectedTotalBytes!
            : null,
      ),
    );
  },
)
// 带错误处理的图片
Image.network(
  'https://example.com/image.png',
  errorBuilder: (context, error, stackTrace) {
    return const Icon(Icons.error, size: 50);
  },
)

Flutter 中常见的图片加载方式主要有三种：

• Image.network：用于加载网络图片。
• Image.asset：用于加载本地资源图片。
• Image.file：用于加载本地文件图片。

如果是网络图片，还可以配合 loadingBuilder 显示加载状态。

当图片加载失败时，可以使用 errorBuilder 做错误处理。

本地资源管理

在 pubspec.yaml 中配置资源文件夹：

flutter:
  assets:
    - assets/images/
    - assets/data.json

资源文件要先在 pubspec.yaml 中声明，才能正常使用。

可以配置整个目录，也可以单独配置某个文件。

实例：使用本地资源

// 使用本地图片
class AssetImageExample extends StatelessWidget {
  const AssetImageExample({super.key});
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // 使用 Image.asset 加载
        const Image(
          image: AssetImage('assets/images/logo.png'),
          width: 100,
        ),
        // 简写形式
        const Image.asset('assets/images/icon.png', width: 50),
        const SizedBox(height: 20),
        // 使用图片 fit
        Container(
          width: 200,
          height: 100,
          decoration: BoxDecoration(
            image: const DecorationImage(
              image: AssetImage('assets/images/bg.jpg'),
              fit: BoxFit.cover,
            ),
            border: Border.all(color: Colors.grey),
          ),
        ),
      ],
    );
  }
}

本地资源图片的使用方式比较直接。

• 可以通过 Image.asset 直接加载。
• 也可以使用 AssetImage 作为 image 参数传入。
• 如果是容器背景图，可以放到 DecorationImage 中使用。

BoxFit 图像适配

图片显示效果是否合适，关键在于 BoxFit 的选择。

值	说明
fill	拉伸填满（可能变形）
contain	等比缩放，最大化适应
cover	等比缩放，完全覆盖
fitWidth	等比缩放，宽度填满
fitHeight	等比缩放，高度填满
none	居中显示原始尺寸
scaleDown	contain 且不超过原始尺寸

实际开发中，cover 和 contain 最常用。

如果希望图片铺满区域，通常用 cover。如果希望完整显示图片，通常用 contain。

CachedNetworkImage - 图片缓存

使用 cached_network_image 包实现图片缓存。

添加依赖

dependencies:
  cached_network_image: ^3.0.0

处理网络图片时，更推荐使用带缓存能力的方案。

这样可以减少重复请求，也有助于提升加载体验。

实例：CachedNetworkImage

import 'package:cached_network_image/cached_network_image.dart';
class CachedImageExample extends StatelessWidget {
  const CachedImageExample({super.key});
  @override
  Widget build(BuildContext context) {
    return CachedNetworkImage(
      imageUrl: 'https://example.com/image.png',
      // 加载中显示
      placeholder: (context, url) => const CircularProgressIndicator(),
      // 错误显示
      errorWidget: (context, url, error) => const Icon(Icons.error),
      // 图片适配
      fit: BoxFit.cover,
      // 宽度高度
      width: 200,
      height: 200,
      // 圆形图片
      imageBuilder: (context, imageProvider) => CircleAvatar(
        backgroundImage: imageProvider,
      ),
    );
  }
}

这个组件除了能加载网络图片，还自带常用能力：

• 加载中占位。
• 加载失败提示。
• 图片缓存。
• 自定义图片展示形式。

如果页面里用到了网络图片，更推荐直接上 CachedNetworkImage。它会把图片自动缓存下来，加载速度更稳，整体显示性能也会更好。