Skip to content

Commit e8acfa2

Browse files
committed
Add FadeInImageTransition enum to control placeholder fade-out behavior
Fixes flutter#97068 Adds a `FadeInImageTransition` enum with two values: - `sequential` (default): existing behavior — placeholder fades out, then the image fades in. - `fadeInOver`: the image fades in on top of the placeholder, which stays at full opacity until the image has fully loaded. `fadeOutDuration` and `fadeOutCurve` are ignored in this mode and the total animation duration equals only `fadeInDuration`.
1 parent f2d640e commit e8acfa2

2 files changed

Lines changed: 230 additions & 30 deletions

File tree

‎packages/flutter/lib/src/widgets/fade_in_image.dart‎

Lines changed: 97 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -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

‎packages/flutter/test/widgets/fade_in_image_test.dart‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -690,5 +690,138 @@ void main() {
690690
);
691691
expect(tester.getSize(find.byType(FadeInImage)), Size.zero);
692692
});
693+
694+
group('FadeInImageTransition.fadeInOver', () {
695+
// Helper: finds the two RawImages inside a FadeInImage with fadeInOver.
696+
// In fadeInOver the Stack order is [placeholder, target], so the first
697+
// RawImage in the tree is the placeholder and the second is the target.
698+
({FadeInImageElements placeholder, FadeInImageElements target}) findFadeInOverImages(
699+
WidgetTester tester,
700+
) {
701+
final List<FadeInImageElements> elements =
702+
tester.elementList(find.byType(RawImage)).map(FadeInImageElements.new).toList();
703+
expect(elements, hasLength(2));
704+
// In [placeholder, target] stack order the first element is the placeholder.
705+
return (placeholder: elements.first, target: elements.last);
706+
}
707+
708+
testWidgets('placeholder stays opaque while image fades in', (WidgetTester tester) async {
709+
final placeholderProvider = TestImageProvider(placeholderImage);
710+
final imageProvider = TestImageProvider(targetImage);
711+
712+
await tester.pumpWidget(
713+
FadeInImage(
714+
placeholder: placeholderProvider,
715+
image: imageProvider,
716+
fadeInDuration: animationDuration,
717+
fadeOutDuration: animationDuration,
718+
fadeInCurve: Curves.linear,
719+
transition: FadeInImageTransition.fadeInOver,
720+
excludeFromSemantics: true,
721+
),
722+
);
723+
724+
placeholderProvider.complete();
725+
await tester.pump();
726+
727+
imageProvider.complete();
728+
await tester.pump();
729+
730+
// Placeholder should remain at full opacity while image fades in.
731+
for (var i = 0; i < 5; i += 1) {
732+
final ({FadeInImageElements placeholder, FadeInImageElements target}) images = findFadeInOverImages(tester);
733+
expect(
734+
images.placeholder.rawImage.image!.isCloneOf(placeholderImage),
735+
true,
736+
reason: 'placeholder image should still be shown',
737+
);
738+
expect(
739+
images.target.rawImage.image!.isCloneOf(targetImage),
740+
true,
741+
reason: 'target image should be shown',
742+
);
743+
expect(images.placeholder.opacity, moreOrLessEquals(1.0), reason: 'step $i');
744+
expect(images.target.opacity, moreOrLessEquals(i / 5), reason: 'step $i');
745+
await tester.pump(const Duration(milliseconds: 10));
746+
}
747+
});
748+
749+
testWidgets('placeholder is removed from tree once image fully fades in', (
750+
WidgetTester tester,
751+
) async {
752+
final placeholderProvider = TestImageProvider(placeholderImage);
753+
final imageProvider = TestImageProvider(targetImage);
754+
755+
await tester.pumpWidget(
756+
FadeInImage(
757+
placeholder: placeholderProvider,
758+
image: imageProvider,
759+
fadeInDuration: animationDuration,
760+
fadeOutDuration: animationDuration,
761+
transition: FadeInImageTransition.fadeInOver,
762+
excludeFromSemantics: true,
763+
),
764+
);
765+
766+
placeholderProvider.complete();
767+
imageProvider.complete();
768+
await tester.pump();
769+
expect(find.byType(Image), findsNWidgets(2));
770+
771+
await tester.pumpAndSettle();
772+
// After the animation completes the placeholder should be removed.
773+
expect(find.byType(Image), findsOneWidget);
774+
});
775+
776+
testWidgets('total animation duration equals only fadeInDuration', (
777+
WidgetTester tester,
778+
) async {
779+
final placeholderProvider = TestImageProvider(placeholderImage);
780+
final imageProvider = TestImageProvider(targetImage);
781+
782+
await tester.pumpWidget(
783+
FadeInImage(
784+
placeholder: placeholderProvider,
785+
image: imageProvider,
786+
fadeInDuration: animationDuration,
787+
fadeOutDuration: animationDuration * 10, // ignored in fadeInOver mode
788+
fadeInCurve: Curves.linear,
789+
transition: FadeInImageTransition.fadeInOver,
790+
excludeFromSemantics: true,
791+
),
792+
);
793+
794+
placeholderProvider.complete();
795+
imageProvider.complete();
796+
await tester.pump();
797+
798+
// After exactly one fadeInDuration the image should be fully opaque
799+
// and the placeholder removed from the tree.
800+
await tester.pump(animationDuration);
801+
await tester.pumpAndSettle();
802+
expect(find.byType(Image), findsOneWidget);
803+
});
804+
805+
testWidgets('shows a cached image immediately when synchronously loaded', (
806+
WidgetTester tester,
807+
) async {
808+
final placeholderProvider = TestImageProvider(placeholderImage);
809+
final imageProvider = TestImageProvider(targetImage);
810+
imageProvider.resolve(ImageConfiguration.empty);
811+
imageProvider.complete();
812+
813+
await tester.pumpWidget(
814+
FadeInImage(
815+
placeholder: placeholderProvider,
816+
image: imageProvider,
817+
transition: FadeInImageTransition.fadeInOver,
818+
),
819+
);
820+
821+
expect(findFadeInImage(tester).target.rawImage.image!.isCloneOf(targetImage), true);
822+
expect(findFadeInImage(tester).placeholder, isNull);
823+
expect(findFadeInImage(tester).target.opacity, 1);
824+
});
825+
});
693826
});
694827
}

0 commit comments

Comments
 (0)