Adds animateToItem to the CarouselController (#162694)
Closes #161368 This PR adds the `animateToItem` method to the `CarouselController`, enabling smooth, index-based navigation for carousels with fixed or dynamically-sized items (via `flexWeights`). https://github.com/user-attachments/assets/c0fe375a-5495-4d56-8b2d-0bd6d0bd0639 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [ ] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
This commit is contained in:
Mairramer
GitHub
parent
fef2adca24
commit
40e4c5eed1
@ -1547,6 +1547,63 @@ class CarouselController extends ScrollController {
|
||||
}
|
||||
}
|
||||
|
||||
/// Animates the controlled carousel to the given item index.
|
||||
///
|
||||
/// For [CarouselView], this will scroll the carousel so the item at [index] becomes
|
||||
/// the leading item.
|
||||
///
|
||||
/// If the [index] is less than 0, the carousel will scroll to the first item.
|
||||
/// If the [index] is greater than the number of items, the carousel will scroll
|
||||
/// to the last item.
|
||||
///
|
||||
/// For [CarouselView.weighted], animates to make the item at [index] occupy the primary,
|
||||
/// most prominent position determined by the largest weight in `flexWeights`.
|
||||
///
|
||||
/// The animation uses the provided [Duration] and [Curve]. The returned [Future]
|
||||
/// completes when the animation finishes.
|
||||
///
|
||||
/// The [Duration] defaults to 300 milliseconds and [Curve] defaults to [Curves.ease].
|
||||
///
|
||||
/// Does nothing if the carousel is not attached to this controller.
|
||||
Future<void> animateToItem(
|
||||
int index, {
|
||||
Duration duration = const Duration(milliseconds: 300),
|
||||
Curve curve = Curves.ease,
|
||||
}) async {
|
||||
if (!hasClients || _carouselState == null) {
|
||||
return;
|
||||
}
|
||||
|
||||
final bool hasFlexWeights = _carouselState!._flexWeights?.isNotEmpty ?? false;
|
||||
index = index.clamp(0, _carouselState!.widget.children.length - 1);
|
||||
|
||||
await Future.wait<void>(<Future<void>>[
|
||||
for (final _CarouselPosition position in positions.cast<_CarouselPosition>())
|
||||
position.animateTo(
|
||||
_getTargetOffset(position, index, hasFlexWeights),
|
||||
duration: duration,
|
||||
curve: curve,
|
||||
),
|
||||
]);
|
||||
}
|
||||
|
||||
double _getTargetOffset(_CarouselPosition position, int index, bool hasFlexWeights) {
|
||||
if (!hasFlexWeights) {
|
||||
return index * _carouselState!._itemExtent!;
|
||||
}
|
||||
|
||||
final _CarouselViewState carouselState = _carouselState!;
|
||||
final List<int> weights = carouselState._flexWeights!;
|
||||
final int totalWeight = weights.reduce((int a, int b) => a + b);
|
||||
final double dimension = position.viewportDimension;
|
||||
|
||||
final int maxWeightIndex = weights.indexOf(weights.max);
|
||||
int leadingIndex = carouselState._consumeMaxWeight ? index : index - maxWeightIndex;
|
||||
leadingIndex = leadingIndex.clamp(0, _carouselState!.widget.children.length - 1);
|
||||
|
||||
return dimension * (weights.first / totalWeight) * leadingIndex;
|
||||
}
|
||||
|
||||
@override
|
||||
ScrollPosition createScrollPosition(
|
||||
ScrollPhysics physics,
|
||||
|
||||
@ -1432,6 +1432,201 @@ void main() {
|
||||
|
||||
expect(tester.takeException(), isNull);
|
||||
});
|
||||
|
||||
group('CarouselController.animateToItem', () {
|
||||
testWidgets('CarouselView.weighted horizontal, not reversed, flexWeights [7,1]', (
|
||||
WidgetTester tester,
|
||||
) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[7, 1],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.horizontal,
|
||||
reverse: false,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('CarouselView.weighted horizontal, reversed, flexWeights [7,1]', (
|
||||
WidgetTester tester,
|
||||
) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[7, 1],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.horizontal,
|
||||
reverse: true,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('CarouselView.weighted vertical, not reversed, flexWeights [7,1]', (
|
||||
WidgetTester tester,
|
||||
) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[7, 1],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.vertical,
|
||||
reverse: false,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('CarouselView.weighted vertical, reversed, flexWeights [7,1]', (
|
||||
WidgetTester tester,
|
||||
) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[7, 1],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.vertical,
|
||||
reverse: true,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets(
|
||||
'CarouselView.weighted horizontal, not reversed, flexWeights [1,7] and consumeMaxWeight false',
|
||||
(WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[1, 7],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.horizontal,
|
||||
reverse: false,
|
||||
consumeMaxWeight: false,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
testWidgets('CarouselView.weighted horizontal, reversed, flexWeights [1,7]', (
|
||||
WidgetTester tester,
|
||||
) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[1, 7],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.horizontal,
|
||||
reverse: true,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets(
|
||||
'CarouselView.weighted vertical, not reversed, flexWeights [1,7] and consumeMaxWeight false',
|
||||
(WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[1, 7],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.vertical,
|
||||
consumeMaxWeight: false,
|
||||
reverse: false,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
testWidgets(
|
||||
'CarouselView.weighted vertical, reversed, flexWeights [1,7] and consumeMaxWeight false',
|
||||
(WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[1, 7],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.vertical,
|
||||
consumeMaxWeight: false,
|
||||
reverse: true,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
testWidgets(
|
||||
'CarouselView.weighted vertical, reversed, flexWeights [1,7] and consumeMaxWeight',
|
||||
(WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
flexWeights: <int>[1, 7],
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.vertical,
|
||||
reverse: true,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
testWidgets('CarouselView horizontal, not reversed', (WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
numberOfChildren: 20,
|
||||
scrollDirection: Axis.horizontal,
|
||||
reverse: false,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('CarouselView horizontal, reversed', (WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
numberOfChildren: 10,
|
||||
scrollDirection: Axis.horizontal,
|
||||
reverse: true,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('CarouselView vertical, not reversed', (WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
numberOfChildren: 10,
|
||||
scrollDirection: Axis.vertical,
|
||||
reverse: false,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('CarouselView vertical, reversed', (WidgetTester tester) async {
|
||||
await runCarouselTest(
|
||||
tester: tester,
|
||||
numberOfChildren: 10,
|
||||
scrollDirection: Axis.vertical,
|
||||
reverse: true,
|
||||
);
|
||||
});
|
||||
|
||||
testWidgets('CarouselView positions items correctly', (WidgetTester tester) async {
|
||||
const int numberOfChildren = 5;
|
||||
final CarouselController controller = CarouselController();
|
||||
addTearDown(controller.dispose);
|
||||
await tester.pumpWidget(
|
||||
MaterialApp(
|
||||
home: Scaffold(
|
||||
body: CarouselView.weighted(
|
||||
flexWeights: const <int>[2, 3, 1],
|
||||
controller: controller,
|
||||
itemSnapping: true,
|
||||
children: List<Widget>.generate(numberOfChildren, (int index) {
|
||||
return Center(child: Text('Item $index'));
|
||||
}),
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
await tester.pumpAndSettle();
|
||||
|
||||
// Get the RenderBox of the CarouselView to determine its position and boundaries.
|
||||
final RenderBox carouselBox = tester.renderObject(find.byType(CarouselView));
|
||||
final Offset carouselPos = carouselBox.localToGlobal(Offset.zero);
|
||||
final double carouselLeft = carouselPos.dx;
|
||||
final double carouselRight = carouselLeft + carouselBox.size.width;
|
||||
|
||||
for (int i = 0; i < numberOfChildren; i++) {
|
||||
controller.animateToItem(i, curve: Curves.easeInOut);
|
||||
await tester.pumpAndSettle();
|
||||
|
||||
expect(find.text('Item $i'), findsOneWidget);
|
||||
|
||||
// Get the item's RenderBox and determine its position.
|
||||
final RenderBox itemBox = tester.renderObject(find.text('Item $i'));
|
||||
final Rect itemRect = itemBox.localToGlobal(Offset.zero) & itemBox.size;
|
||||
|
||||
// Validate that the item is positioned within the CarouselView boundaries.
|
||||
expect(itemRect.left, greaterThanOrEqualTo(carouselLeft));
|
||||
expect(itemRect.right, lessThanOrEqualTo(carouselRight));
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
Finder getItem(int index) {
|
||||
@ -1450,3 +1645,77 @@ Future<TestGesture> hoverPointerOverCarouselItem(WidgetTester tester, Key key) a
|
||||
await gesture.moveTo(center);
|
||||
return gesture;
|
||||
}
|
||||
|
||||
Future<void> runCarouselTest({
|
||||
required WidgetTester tester,
|
||||
List<int> flexWeights = const <int>[],
|
||||
bool consumeMaxWeight = true,
|
||||
required int numberOfChildren,
|
||||
required Axis scrollDirection,
|
||||
required bool reverse,
|
||||
}) async {
|
||||
final CarouselController controller = CarouselController();
|
||||
addTearDown(controller.dispose);
|
||||
await tester.pumpWidget(
|
||||
MaterialApp(
|
||||
home: Scaffold(
|
||||
body:
|
||||
(flexWeights.isEmpty)
|
||||
? CarouselView(
|
||||
scrollDirection: scrollDirection,
|
||||
reverse: reverse,
|
||||
controller: controller,
|
||||
itemSnapping: true,
|
||||
itemExtent: 300,
|
||||
children: List<Widget>.generate(numberOfChildren, (int index) {
|
||||
return Center(child: Text('Item $index'));
|
||||
}),
|
||||
)
|
||||
: CarouselView.weighted(
|
||||
flexWeights: flexWeights,
|
||||
scrollDirection: scrollDirection,
|
||||
reverse: reverse,
|
||||
controller: controller,
|
||||
itemSnapping: true,
|
||||
consumeMaxWeight: consumeMaxWeight,
|
||||
children: List<Widget>.generate(numberOfChildren, (int index) {
|
||||
return Center(child: Text('Item $index'));
|
||||
}),
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
|
||||
double realOffset() {
|
||||
return tester.state<ScrollableState>(find.byType(Scrollable)).position.pixels;
|
||||
}
|
||||
|
||||
// Calculate the index of the middle item.
|
||||
// The calculation depends on the scroll direction (normal or reverse).
|
||||
// For reverse scrolling, the middle item is calculated taking into account the end of the list,
|
||||
// reversing the calculation so that the item that appears in the middle when scrolling is the correct one.
|
||||
// For normal scrolling, we simply get the middle item.
|
||||
final int middleIndex =
|
||||
reverse
|
||||
? (numberOfChildren - 1 - (numberOfChildren / 2).round())
|
||||
: (numberOfChildren / 2).round();
|
||||
|
||||
controller.animateToItem(
|
||||
middleIndex,
|
||||
duration: const Duration(milliseconds: 100),
|
||||
curve: Curves.easeInOut,
|
||||
);
|
||||
await tester.pumpAndSettle();
|
||||
|
||||
// Verify that the middle item is visible.
|
||||
expect(find.text('Item $middleIndex'), findsOneWidget);
|
||||
expect(realOffset(), controller.offset);
|
||||
|
||||
// Scroll to the first item.
|
||||
controller.animateToItem(0, duration: const Duration(milliseconds: 100), curve: Curves.easeInOut);
|
||||
await tester.pumpAndSettle();
|
||||
|
||||
// Verify that the first item is visible.
|
||||
expect(find.text('Item 0'), findsOneWidget);
|
||||
expect(realOffset(), controller.offset);
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user