@@ -12,6 +12,29 @@ import 'implicit_animations.dart';
1212// Examples can assume:
1313// late Uint8List bytes;
1414
15+ /// Defines the transition animation behavior for [FadeInImage] .
16+ ///
17+ /// See also:
18+ ///
19+ /// * [FadeInImage.transition] , which uses this enum.
20+ enum FadeInImageTransition {
21+ /// The placeholder fades out, then the image fades in sequentially.
22+ ///
23+ /// This is the default behavior. The placeholder fade-out animation is
24+ /// controlled by [FadeInImage.fadeOutDuration] and [FadeInImage.fadeOutCurve] .
25+ /// The image fade-in animation is controlled by [FadeInImage.fadeInDuration]
26+ /// and [FadeInImage.fadeInCurve] .
27+ sequential,
28+
29+ /// The image fades in on top of the placeholder, which remains at full
30+ /// opacity until the image has fully faded in.
31+ ///
32+ /// [FadeInImage.fadeOutDuration] and [FadeInImage.fadeOutCurve] are ignored
33+ /// in this mode. The fade-in animation is controlled by
34+ /// [FadeInImage.fadeInDuration] and [FadeInImage.fadeInCurve] .
35+ fadeInOver,
36+ }
37+
1538/// An image that shows a [placeholder] image while the target [image] is
1639/// loading, then fades in the new image when it loads.
1740///
@@ -97,6 +120,7 @@ class FadeInImage extends StatefulWidget {
97120 this .alignment = Alignment .center,
98121 this .repeat = ImageRepeat .noRepeat,
99122 this .matchTextDirection = false ,
123+ this .transition = FadeInImageTransition .sequential,
100124 });
101125
102126 /// Creates a widget that uses a placeholder image stored in memory while
@@ -154,6 +178,7 @@ class FadeInImage extends StatefulWidget {
154178 this .alignment = Alignment .center,
155179 this .repeat = ImageRepeat .noRepeat,
156180 this .matchTextDirection = false ,
181+ this .transition = FadeInImageTransition .sequential,
157182 int ? placeholderCacheWidth,
158183 int ? placeholderCacheHeight,
159184 int ? imageCacheWidth,
@@ -224,6 +249,7 @@ class FadeInImage extends StatefulWidget {
224249 this .alignment = Alignment .center,
225250 this .repeat = ImageRepeat .noRepeat,
226251 this .matchTextDirection = false ,
252+ this .transition = FadeInImageTransition .sequential,
227253 int ? placeholderCacheWidth,
228254 int ? placeholderCacheHeight,
229255 int ? imageCacheWidth,
@@ -414,6 +440,15 @@ class FadeInImage extends StatefulWidget {
414440 /// once the image has loaded.
415441 final String ? imageSemanticLabel;
416442
443+ /// Controls the transition animation when the [image] finishes loading.
444+ ///
445+ /// Defaults to [FadeInImageTransition.sequential] , which fades out the
446+ /// [placeholder] before fading in the [image] .
447+ ///
448+ /// Use [FadeInImageTransition.fadeInOver] to have the [image] fade in on top
449+ /// of the [placeholder] without fading the placeholder out first.
450+ final FadeInImageTransition transition;
451+
417452 @override
418453 State <FadeInImage > createState () => _FadeInImageState ();
419454}
@@ -490,6 +525,7 @@ class _FadeInImageState extends State<FadeInImage> {
490525 fadeOutDuration: widget.fadeOutDuration,
491526 fadeInCurve: widget.fadeInCurve,
492527 fadeOutCurve: widget.fadeOutCurve,
528+ transition: widget.transition,
493529 );
494530 },
495531 );
@@ -519,8 +555,13 @@ class _AnimatedFadeOutFadeIn extends ImplicitlyAnimatedWidget {
519555 required this .fadeInDuration,
520556 required this .fadeInCurve,
521557 required this .wasSynchronouslyLoaded,
558+ required this .transition,
522559 }) : assert (! wasSynchronouslyLoaded || isTargetLoaded),
523- super (duration: fadeInDuration + fadeOutDuration);
560+ super (
561+ duration: transition == FadeInImageTransition .fadeInOver
562+ ? fadeInDuration
563+ : fadeInDuration + fadeOutDuration,
564+ );
524565
525566 final Widget target;
526567 final ProxyAnimation targetProxyAnimation;
@@ -532,6 +573,7 @@ class _AnimatedFadeOutFadeIn extends ImplicitlyAnimatedWidget {
532573 final Curve fadeInCurve;
533574 final Curve fadeOutCurve;
534575 final bool wasSynchronouslyLoaded;
576+ final FadeInImageTransition transition;
535577
536578 @override
537579 _AnimatedFadeOutFadeInState createState () => _AnimatedFadeOutFadeInState ();
@@ -555,7 +597,11 @@ class _AnimatedFadeOutFadeInState extends ImplicitlyAnimatedWidgetState<_Animate
555597 _placeholderOpacity =
556598 visitor (
557599 _placeholderOpacity,
558- widget.isTargetLoaded ? 0.0 : 1.0 ,
600+ // fadeInOver: placeholder stays opaque; it's removed from the tree
601+ // once the image animation completes rather than being faded out.
602+ (widget.isTargetLoaded && widget.transition != FadeInImageTransition .fadeInOver)
603+ ? 0.0
604+ : 1.0 ,
559605 (dynamic value) => Tween <double >(begin: value as double ),
560606 )
561607 as Tween <double >? ;
@@ -568,37 +614,51 @@ class _AnimatedFadeOutFadeInState extends ImplicitlyAnimatedWidgetState<_Animate
568614 return ;
569615 }
570616
571- _placeholderOpacityAnimation =
572- animation.drive (
573- TweenSequence <double >(< TweenSequenceItem <double >> [
574- TweenSequenceItem <double >(
575- tween: _placeholderOpacity! .chain (CurveTween (curve: widget.fadeOutCurve)),
576- weight: widget.fadeOutDuration.inMilliseconds.toDouble (),
577- ),
578- TweenSequenceItem <double >(
579- tween: ConstantTween <double >(0 ),
580- weight: widget.fadeInDuration.inMilliseconds.toDouble (),
581- ),
582- ]),
583- )..addStatusListener ((AnimationStatus status) {
617+ if (widget.transition == FadeInImageTransition .fadeInOver) {
618+ // Image fades in on top of the placeholder. The placeholder stays at full
619+ // opacity and is removed from the tree once the fade-in completes.
620+ _targetOpacityAnimation = animation.drive (
621+ _targetOpacity! .chain (CurveTween (curve: widget.fadeInCurve)),
622+ );
623+ _placeholderOpacityAnimation = animation.drive (ConstantTween <double >(1.0 ))
624+ ..addStatusListener ((AnimationStatus status) {
584625 if (_placeholderOpacityAnimation! .isCompleted) {
585- // Need to rebuild to remove placeholder now that it is invisible.
586626 setState (() {});
587627 }
588628 });
589-
590- _targetOpacityAnimation = animation.drive (
591- TweenSequence <double >(< TweenSequenceItem <double >> [
592- TweenSequenceItem <double >(
593- tween: ConstantTween <double >(0 ),
594- weight: widget.fadeOutDuration.inMilliseconds.toDouble (),
595- ),
596- TweenSequenceItem <double >(
597- tween: _targetOpacity! .chain (CurveTween (curve: widget.fadeInCurve)),
598- weight: widget.fadeInDuration.inMilliseconds.toDouble (),
599- ),
600- ]),
601- );
629+ } else {
630+ _placeholderOpacityAnimation =
631+ animation.drive (
632+ TweenSequence <double >(< TweenSequenceItem <double >> [
633+ TweenSequenceItem <double >(
634+ tween: _placeholderOpacity! .chain (CurveTween (curve: widget.fadeOutCurve)),
635+ weight: widget.fadeOutDuration.inMilliseconds.toDouble (),
636+ ),
637+ TweenSequenceItem <double >(
638+ tween: ConstantTween <double >(0 ),
639+ weight: widget.fadeInDuration.inMilliseconds.toDouble (),
640+ ),
641+ ]),
642+ )..addStatusListener ((AnimationStatus status) {
643+ if (_placeholderOpacityAnimation! .isCompleted) {
644+ // Need to rebuild to remove placeholder now that it is invisible.
645+ setState (() {});
646+ }
647+ });
648+
649+ _targetOpacityAnimation = animation.drive (
650+ TweenSequence <double >(< TweenSequenceItem <double >> [
651+ TweenSequenceItem <double >(
652+ tween: ConstantTween <double >(0 ),
653+ weight: widget.fadeOutDuration.inMilliseconds.toDouble (),
654+ ),
655+ TweenSequenceItem <double >(
656+ tween: _targetOpacity! .chain (CurveTween (curve: widget.fadeInCurve)),
657+ weight: widget.fadeInDuration.inMilliseconds.toDouble (),
658+ ),
659+ ]),
660+ );
661+ }
602662
603663 widget.targetProxyAnimation.parent = _targetOpacityAnimation;
604664 widget.placeholderProxyAnimation.parent = _placeholderOpacityAnimation;
@@ -610,13 +670,20 @@ class _AnimatedFadeOutFadeInState extends ImplicitlyAnimatedWidgetState<_Animate
610670 return widget.target;
611671 }
612672
673+ // In fadeInOver mode the target image is painted on top of the placeholder
674+ // so it can fade in over it. In sequential mode the placeholder is on top
675+ // so it can fade out while the target is revealed beneath it.
676+ final children = widget.transition == FadeInImageTransition .fadeInOver
677+ ? < Widget > [widget.placeholder, widget.target]
678+ : < Widget > [widget.target, widget.placeholder];
679+
613680 return Stack (
614681 fit: StackFit .passthrough,
615682 alignment: AlignmentDirectional .center,
616683 // Text direction is irrelevant here since we're using center alignment,
617684 // but it allows the Stack to avoid a call to Directionality.of()
618685 textDirection: TextDirection .ltr,
619- children: < Widget > [widget.target, widget.placeholder] ,
686+ children: children ,
620687 );
621688 }
622689
0 commit comments