Image.asset constructor Null safety
- String name,
- {Key? key,
- AssetBundle? bundle,
- ImageFrameBuilder? frameBuilder,
- ImageErrorWidgetBuilder? errorBuilder,
- String? semanticLabel,
- bool excludeFromSemantics = false,
- double? scale,
- double? width,
- double? height,
- Color? color,
- Animation<
double> ? opacity, - BlendMode? colorBlendMode,
- BoxFit? fit,
- AlignmentGeometry alignment = Alignment.center,
- ImageRepeat repeat = ImageRepeat.noRepeat,
- Rect? centerSlice,
- bool matchTextDirection = false,
- bool gaplessPlayback = false,
- bool isAntiAlias = false,
- String? package,
- FilterQuality filterQuality = FilterQuality.low,
- int? cacheWidth,
- int? cacheHeight}
Creates a widget that displays an ImageStream obtained from an asset
bundle. The key for the image is given by the name
argument.
The package
argument must be non-null when displaying an image from a
package and null otherwise. See the Assets in packages
section for
details.
If the bundle
argument is omitted or null, then the
DefaultAssetBundle will be used.
By default, the pixel-density-aware asset resolution will be attempted. In addition:
- If the
scale
argument is provided and is not null, then the exact asset specified will be used. To display an image variant with a specific density, the exact path must be provided (e.g.images/2x/cat.png
).
If excludeFromSemantics is true, then semanticLabel will be ignored.
If cacheWidth
or cacheHeight
are provided, it indicates to the
engine that the image must be decoded at the specified size. The image
will be rendered to the constraints of the layout or width and height
regardless of these parameters. These parameters are primarily intended
to reduce the memory usage of ImageCache.
The name
and repeat arguments must not be null.
Either the width and height arguments should be specified, or the widget should be placed in a context that sets tight layout constraints. Otherwise, the image dimensions will change as the image is loaded, which will result in ugly layout changes.
Use filterQuality to specify the rendering quality of the image.
pubspec.yaml
file contains the following:
flutter:
assets:
- images/cat.png
- images/2x/cat.png
- images/3.5x/cat.png
On a screen with a device pixel ratio of 2.0, the following widget would
render the images/2x/cat.png
file:
Image.asset('images/cat.png')
This corresponds to the file that is in the project's images/2x/
directory with the name cat.png
(the paths are relative to the
pubspec.yaml
file).
On a device with a 4.0 device pixel ratio, the images/3.5x/cat.png
asset
would be used. On a device with a 1.0 device pixel ratio, the
images/cat.png
resource would be used.
The images/cat.png
image can be omitted from disk (though it must still
be present in the manifest). If it is omitted, then on a device with a 1.0
device pixel ratio, the images/2x/cat.png
image would be used instead.
Assets in packages
To create the widget with an asset from a package, the package
argument
must be provided. For instance, suppose a package called my_icons
has
icons/heart.png
.
Image.asset('icons/heart.png', package: 'my_icons')
Assets used by the package itself should also be displayed using the
package
argument as above.
If the desired asset is specified in the pubspec.yaml
of the package, it
is bundled automatically with the app. In particular, assets used by the
package itself must be specified in its pubspec.yaml
.
A package can also choose to have assets in its 'lib/' folder that are not
specified in its pubspec.yaml
. In this case for those images to be
bundled, the app has to specify which ones to include. For instance a
package named fancy_backgrounds
could have:
lib/backgrounds/background1.png
lib/backgrounds/background2.png
lib/backgrounds/background3.png
To include, say the first image, the pubspec.yaml
of the app should
specify it in the assets section:
assets:
- packages/fancy_backgrounds/backgrounds/background1.png
The lib/
is implied, so it should not be included in the asset path.
See also:
- AssetImage, which is used to implement the behavior when the scale is omitted.
- ExactAssetImage, which is used to implement the behavior when the scale is present.
- flutter.dev/assets-and-images/, an introduction to assets in Flutter.
Implementation
Image.asset(
String name, {
super.key,
AssetBundle? bundle,
this.frameBuilder,
this.errorBuilder,
this.semanticLabel,
this.excludeFromSemantics = false,
double? scale,
this.width,
this.height,
this.color,
this.opacity,
this.colorBlendMode,
this.fit,
this.alignment = Alignment.center,
this.repeat = ImageRepeat.noRepeat,
this.centerSlice,
this.matchTextDirection = false,
this.gaplessPlayback = false,
this.isAntiAlias = false,
String? package,
this.filterQuality = FilterQuality.low,
int? cacheWidth,
int? cacheHeight,
}) : image = ResizeImage.resizeIfNeeded(
cacheWidth,
cacheHeight,
scale != null
? ExactAssetImage(name, bundle: bundle, scale: scale, package: package)
: AssetImage(name, bundle: bundle, package: package),
),
loadingBuilder = null,
assert(alignment != null),
assert(repeat != null),
assert(matchTextDirection != null),
assert(cacheWidth == null || cacheWidth > 0),
assert(cacheHeight == null || cacheHeight > 0),
assert(isAntiAlias != null);