Image
Image 用于显示图片，支持网络、本地资源、文件和内存图片。
构造方式速查
| 构造方式 | 适用场景 |
|---|---|
Image.network(url) | 网络图片 |
Image.asset(path) | 本地资源图片（需在 pubspec.yaml 中声明） |
Image.file(File(path)) | 本地文件图片 |
Image.memory(bytes) | 内存图片（Uint8List） |
构造函数
Image.network — 网络图片
dart
Image.network(
String url, { // 图片 URL（必填）
Key? key, // 组件标识
double? width, // 宽度
double? height, // 高度
BoxFit? fit, // 缩放模式（cover/contain/fill 等）
Color? color, // 颜色混合（与 colorBlendMode 配合）
BlendMode? colorBlendMode, // 颜色混合模式
AlignmentGeometry alignment = Alignment.center, // 对齐方式
ImageRepeat repeat = ImageRepeat.noRepeat, // 重复方式
FilterQuality filterQuality = FilterQuality.low, // 过滤质量
int? cacheWidth, // 缓存宽度（解码前缩放，节省内存）
int? cacheHeight, // 缓存高度（解码前缩放，节省内存）
Widget Function(BuildContext, Widget, int?)? loadingBuilder, // 加载进度构建器
Widget Function(BuildContext, Object, StackTrace?)? errorBuilder, // 加载失败构建器
String? semanticLabel, // 语义标签
bool gaplessPlayback = false, // 图片切换时是否无缝过渡
bool isAntiAlias = false, // 是否抗锯齿
Map<String, String>? headers, // HTTP 请求头
})Image.asset — 本地资源图片
dart
Image.asset(
String name, { // 资源路径（必填）
Key? key, // 组件标识
double? width, // 宽度
double? height, // 高度
BoxFit? fit, // 缩放模式
Color? color, // 颜色混合
BlendMode? colorBlendMode, // 颜色混合模式
AlignmentGeometry alignment = Alignment.center, // 对齐方式
ImageRepeat repeat = ImageRepeat.noRepeat, // 重复方式
AssetBundle? bundle, // 资源包
String? package, // 包名
FilterQuality filterQuality = FilterQuality.low, // 过滤质量
int? cacheWidth, // 缓存宽度
int? cacheHeight, // 缓存高度
String? semanticLabel, // 语义标签
})常用属性速查
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
width | double? | null | 宽度 |
height | double? | null | 高度 |
fit | BoxFit? | null | 缩放模式 |
color | Color? | null | 颜色混合 |
colorBlendMode | BlendMode? | null | 颜色混合模式 |
alignment | AlignmentGeometry | center | 对齐方式 |
repeat | ImageRepeat | noRepeat | 重复方式 |
filterQuality | FilterQuality | low | 过滤质量 |
cacheWidth | int? | null | 缓存宽度（节省内存） |
cacheHeight | int? | null | 缓存高度（节省内存） |
loadingBuilder | Function? | null | 加载进度构建器 |
errorBuilder | Function? | null | 加载失败构建器 |
headers | Map? | null | HTTP 请求头（仅 network） |
fit — 缩放模式
| 值 | 效果 | 说明 |
|---|---|---|
BoxFit.fill | 拉伸填满 | 可能变形 |
BoxFit.contain | 等比缩放，完整显示 | 可能留白 |
BoxFit.cover | 等比缩放，填满区域 | 可能裁剪（最常用） |
BoxFit.fitWidth | 宽度填满 | 高度可能超出 |
BoxFit.fitHeight | 高度填满 | 宽度可能超出 |
BoxFit.none | 不缩放 | 原始大小 |
BoxFit.scaleDown | 只能缩小 | 不能放大 |
快速示例
网络图片
dart
import 'package:flutter/material.dart';
class ImageNetworkExample extends StatelessWidget {
const ImageNetworkExample({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('网络图片示例')),
body: Center(
// ─── ★ Image.network ──────────────
child: Image.network(
'https://picsum.photos/200/200',
width: 200,
height: 200,
fit: BoxFit.cover,
),
// ─── ☆ Image.network ──────────────
),
);
}
}带加载进度和错误处理
dart
import 'package:flutter/material.dart';
class ImageLoadingExample extends StatelessWidget {
const ImageLoadingExample({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('图片加载示例')),
body: Center(
// ─── ★ loadingBuilder + errorBuilder ──────────────
child: Image.network(
'https://picsum.photos/200/200',
fit: BoxFit.cover,
loadingBuilder: (context, child, loadingProgress) {
if (loadingProgress == null) return child;
final progress = loadingProgress.expectedTotalBytes != null
? loadingProgress.cumulativeBytesLoaded / loadingProgress.expectedTotalBytes!
: null;
return Center(child: CircularProgressIndicator(value: progress));
},
errorBuilder: (context, error, stackTrace) {
return const Icon(Icons.error, color: Colors.red);
},
),
// ─── ☆ loadingBuilder + errorBuilder ──────────────
),
);
}
}本地资源图片
dart
Image.asset('images/logo.png')在 pubspec.yaml 中声明：
yaml
flutter:
assets:
- images/logo.png # 单个文件
- images/ # 整个目录圆角图片
dart
// 方式 1：ClipRRect（推荐）
ClipRRect(
borderRadius: BorderRadius.circular(12),
child: Image.network(url, width: 200, height: 200, fit: BoxFit.cover),
)
// 方式 2：CircleAvatar（圆形）
CircleAvatar(
radius: 50,
backgroundImage: NetworkImage(url),
)
// 方式 3：Container + decoration
Container(
width: 200,
height: 200,
decoration: BoxDecoration(
borderRadius: BorderRadius.circular(12),
image: DecorationImage(
image: NetworkImage(url),
fit: BoxFit.cover,
),
),
)占位图 + 渐显效果
dart
// 使用 FadeInImage
FadeInImage.assetNetwork(
placeholder: 'assets/loading.png', // 占位图
image: 'https://example.com/photo.jpg',
fit: BoxFit.cover,
)
// 使用透明度动画
FadeInImage.memoryNetwork(
placeholder: kTransparentImage,
image: 'https://example.com/photo.jpg',
fit: BoxFit.cover,
fadeOutDuration: const Duration(milliseconds: 300),
fadeInDuration: const Duration(milliseconds: 500),
)CachedNetworkImage（推荐用于网络图片）
需要添加依赖：cached_network_image: ^3.3.0
dart
CachedNetworkImage(
imageUrl: 'https://example.com/photo.jpg',
placeholder: (context, url) => const CircularProgressIndicator(),
errorWidget: (context, url, error) => const Icon(Icons.error),
fit: BoxFit.cover,
width: 200,
height: 200,
)Image 与 BoxDecoration 对比
| 特性 | Image | BoxDecoration(image:) |
|---|---|---|
| 可否点击 | 直接用 GestureDetector | 需要外层包 GestureDetector |
| 可否叠加 | 需要配合 Stack | 可同时设置 gradient、border、shadow |
| 适合场景 | 单独展示图片 | Container 的装饰背景 |