跨平台开发 / 系统课时

加载网络图片并处理失败

加载网络图片并处理失败

本篇解决 Flutter 应用中展示远程图片时常见的加载问题,学习如何使用 Image.network 获取网络资源,并通过占位、错误处理提升页面稳定性。

学习目标

  • 掌握 Image.network 加载远程图片的基本方式
  • 理解图片加载过程中的占位和失败处理机制
  • 能够在实际页面中构建更可靠的网络图片展示组件

使用 Image.network 加载远程图片

移动应用中的头像、商品图片和文章封面通常来自服务器,而不是打包在应用内部。Flutter 提供了 Image.network 用于根据图片 URL 创建图片组件。

最简单的用法是传入图片地址:

dart
import 'package:flutter/material.dart';

class NetworkImageDemo extends StatelessWidget {
  const NetworkImageDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Image.network(
        'https://example.com/images/flutter-logo.png',
        width: 200,
        height: 200,
      ),
    );
  }
}

预期结果

text
页面中央显示指定 URL 对应的远程图片。

Image.network 会在内部创建图片加载任务。图片下载完成前,组件处于等待状态;下载成功后显示图片;下载失败则进入错误状态。

处理加载中的显示效果

网络环境不稳定时,用户可能会看到短暂空白。可以通过 loadingBuilder 提供加载过程中的展示内容。

dart
Image.network(
  'https://example.com/images/product.png',
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) {
      return child;
    }

    return const Center(
      child: CircularProgressIndicator(),
    );
  },
)

预期结果

text
图片加载完成前显示进度指示器,加载完成后替换为真实图片。

loadingBuilder 会在图片资源逐步读取时被调用。实际项目中通常会结合固定尺寸容器,避免图片加载过程中导致页面布局跳动。

处理网络图片加载失败

远程图片可能因为地址失效、服务器异常或网络不可用而加载失败。errorBuilder 可以提供备用展示内容。

dart
Image.network(
  'https://example.com/images/avatar.png',
  errorBuilder: (context, error, stackTrace) {
    return const Icon(
      Icons.broken_image,
      size: 64,
    );
  },
)

预期结果

text
图片加载失败时显示 broken_image 图标,而不是让页面出现异常状态。

错误处理组件应该符合业务场景。例如头像可以显示默认头像,商品图可以显示占位图片,而不是所有场景都使用同一个错误图标。

网络图片使用中的常见问题

实际开发中,网络图片通常还需要考虑以下情况:

  • 图片地址可能为空,需要在创建 Image.network 前判断。
  • 图片尺寸过大,需要配合缓存和尺寸约束减少内存压力。
  • 列表中大量图片同时加载,需要避免一次创建过多资源。

当图片来自用户上传或第三方接口时,错误处理不是可选功能,而是页面稳定性的一部分。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

加载网络图片并处理失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通