跨平台开发 / 系统课时

加载本地资源图片

加载本地资源图片

本文解决 Flutter 应用中本地图片无法显示的问题,学习如何声明 assets 资源,并通过 Image.asset 在页面中加载项目内的图片文件。

学习目标

  • 理解 Flutter assets 资源管理方式。
  • 掌握 pubspec.yaml 中图片资源声明方法。
  • 能够使用 Image.asset 显示本地图片并验证加载结果。

声明 Flutter 图片资源

Flutter 不会自动扫描项目目录中的图片文件,需要先在 pubspec.yaml 中声明资源路径。声明后,构建工具才会把图片打包进应用。

假设项目结构如下:

text
project/
  assets/
    images/
      logo.png
  lib/
    main.dart

需要在 pubspec.yaml 中配置:

yaml
flutter:
  assets:
    - assets/images/logo.png

修改配置后需要执行依赖更新,让 Flutter 重新读取资源列表。

bash
flutter pub get

预期结果

text
命令执行成功,项目重新生成资源配置。

如果路径拼写错误,运行时通常会出现资源不存在的异常,因此目录名称和文件名必须完全匹配。

使用 Image.asset 加载图片

声明资源后,可以通过 Image.asset 根据路径读取图片。

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

void main() {
  runApp(const MaterialApp(home: ImageDemo()));
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Image.asset(
          'assets/images/logo.png',
          width: 120,
          height: 120,
        ),
      ),
    );
  }
}

预期结果

text
应用启动后,页面中央显示 assets/images/logo.png 图片。

Image.asset 的路径必须与 pubspec.yaml 中声明的路径一致,不支持省略目录层级。

控制图片显示效果

图片加载后,可以通过尺寸和填充方式适配不同布局。

常用参数包括:

参数 作用
width 设置显示宽度
height 设置显示高度
fit 控制图片缩放方式

例如头像、商品图等场景通常需要限制尺寸并设置填充方式:

dart
Image.asset(
  'assets/images/logo.png',
  width: 80,
  height: 80,
  fit: BoxFit.cover,
)

预期结果

text
图片显示为 80x80 区域,并按照 cover 规则填充。

排查图片无法显示的问题

本地图片加载失败时,可以按以下顺序检查:

  • 确认图片文件实际存在于项目目录。
  • 检查 pubspec.yaml 缩进是否正确,YAML 对空格敏感。
  • 确认资源路径大小写完全一致。
  • 修改 assets 后重新执行 flutter pub get。

如果图片资源属于大量静态文件,也可以声明整个目录:

yaml
flutter:
  assets:
    - assets/images/

预期结果

text
assets/images/目录下的图片资源都可以通过对应路径加载。

本地资源适合应用内固定图片,例如启动图、图标和内置插图。如果图片需要从服务器动态更新,应使用网络图片加载方案,而不是打包 assets。

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

目录与阅读设置

阅读设置

17

记录一个想法

加载本地资源图片

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

登录哪都通