Image.network constructor

Image.network(
  1. String src, {
  2. Key? key,
  3. double scale = 1.0,
  4. ImageFrameBuilder? frameBuilder,
  5. ImageLoadingBuilder? loadingBuilder,
  6. ImageErrorWidgetBuilder? errorBuilder,
  7. String? semanticLabel,
  8. bool excludeFromSemantics = false,
  9. double? width,
  10. double? height,
  11. Color? color,
  12. Animation<double>? opacity,
  13. BlendMode? colorBlendMode,
  14. BoxFit? fit,
  15. AlignmentGeometry alignment = Alignment.center,
  16. ImageRepeat repeat = ImageRepeat.noRepeat,
  17. Rect? centerSlice,
  18. bool matchTextDirection = false,
  19. bool gaplessPlayback = false,
  20. FilterQuality filterQuality = FilterQuality.medium,
  21. bool isAntiAlias = false,
  22. Map<String, String>? headers,
  23. int? cacheWidth,
  24. int? cacheHeight,
  25. WebHtmlElementStrategy webHtmlElementStrategy = WebHtmlElementStrategy.never,
})

Creates a widget that displays an ImageStream obtained from the network.

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.

The scale argument specifies the linear scale factor for drawing this image at its intended size and applies to both the width and the height. For example, if this is 2.0, it means that there are four image pixels for every one logical pixel, and the image's actual width and height (as given by the dart:ui.Image.width and dart:ui.Image.height properties) are double the height and width that should be used when painting the image (e.g. in the arguments given to Canvas.drawImage).

All network images are cached regardless of HTTP headers.

An optional headers argument can be used to send custom HTTP headers with the image request.

Use filterQuality to specify the rendering quality of the image.

If excludeFromSemantics is true, then semanticLabel will be ignored.

If cacheWidth or cacheHeight are provided, they indicate to the engine that the image should 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.

In the case where the network image is on the Web platform, the cacheWidth and cacheHeight parameters are ignored as the web engine delegates image decoding to the web which does not support custom decode sizes.

Same-origin policy on Web

Due to browser restriction on Cross-Origin Resource Sharing (CORS), Flutter on the Web platform can not fetch images from other origins (domain, scheme, or port) than the origin that hosts the app, unless the image hosting origin explicitly allows so. CORS errors can be resolved by configuring the image hosting server. More information can be found at Mozilla's introduction on same-origin policy and CORS errors.

If it's not possible to configure the host, such as when images are hosted on a CDN or from arbitrary URLs, the app can set the webHtmlElementStrategy parameter of Image.network to display the image in an HTML element, which bypasses the same-origin policy.

The HTML element is placed in a platform view, and therefore has the following drawbacks:

  • Suboptimal performance.
  • Can't be captured by screenshot widgets.
  • The headers argument must be null or empty.
  • Some image options are ignored, including opacity, colorBlendMode, repeat, filtering, and blurring.

By default, this feature is turned off (WebHtmlElementStrategy.never).

Implementation

Image.network(
  String src, {
  super.key,
  double scale = 1.0,
  this.frameBuilder,
  this.loadingBuilder,
  this.errorBuilder,
  this.semanticLabel,
  this.excludeFromSemantics = false,
  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.filterQuality = FilterQuality.medium,
  this.isAntiAlias = false,
  Map<String, String>? headers,
  int? cacheWidth,
  int? cacheHeight,
  WebHtmlElementStrategy webHtmlElementStrategy = WebHtmlElementStrategy.never,
}) : image = ResizeImage.resizeIfNeeded(
       cacheWidth,
       cacheHeight,
       NetworkImage(
         src,
         scale: scale,
         headers: headers,
         webHtmlElementStrategy: webHtmlElementStrategy,
       ),
     ),
     assert(cacheWidth == null || cacheWidth > 0),
     assert(cacheHeight == null || cacheHeight > 0);