Image.asset constructor

Image.asset(String name, { Key key, AssetBundle bundle, double scale, double width, double height, Color color, BlendMode colorBlendMode, BoxFit fit, AlignmentGeometry alignment: Alignment.center, ImageRepeat repeat: ImageRepeat.noRepeat, Rect centerSlice, bool matchTextDirection: false, bool gaplessPlayback: false, String package })

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.

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.

Sample code

Suppose that the project's 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:

new 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 .

Then to display the image, use:

new 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:

Implementation

//
// TODO(ianh): Implement the following (see ../services/image_resolution.dart):
// ///
// /// * If [width] and [height] are both specified, and [scale] is not, then
// ///   size-aware asset resolution will be attempted also, with the given
// ///   dimensions interpreted as logical pixels.
// ///
// /// * If the images have platform, locale, or directionality variants, the
// ///   current platform, locale, and directionality are taken into account
// ///   during asset resolution as well.
///
/// 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.
///
/// ## Sample code
///
/// Suppose that the project's `pubspec.yaml` file contains the following:
///
/// ```yaml
/// 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:
///
/// ```dart
/// new 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` .
///
/// Then to display the image, use:
///
/// ```dart
/// new 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:
///
/// ```yaml
///  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.
///  * <https://flutter.io/assets-and-images/>, an introduction to assets in
///    Flutter.
Image.asset(String name, {
  Key key,
  AssetBundle bundle,
  double scale,
  this.width,
  this.height,
  this.color,
  this.colorBlendMode,
  this.fit,
  this.alignment: Alignment.center,
  this.repeat: ImageRepeat.noRepeat,
  this.centerSlice,
  this.matchTextDirection: false,
  this.gaplessPlayback: false,
  String package,
}) : image = scale != null
       ? new ExactAssetImage(name, bundle: bundle, scale: scale, package: package)
       : new AssetImage(name, bundle: bundle, package: package),
     assert(alignment != null),
     assert(repeat != null),
     assert(matchTextDirection != null),
     super(key: key);