awesome_carousel

Description:

awesome carousel

awesome_carousel #
A Flutter plug-in aimed at providing various carousel widgets.
Author #

Author: Juncai Li
Email: [email protected]
License: MIT
Repository: http://thispage.tech:9680/jclee1995/flutter-carousels
中文文档：http://thispage.tech:9680/jclee1995/flutter-carousels/-/blob/master/README_CN.md

Getting Started #
Carousel component provided in this module is very easy to realize carousel function in various demand scenarios, and developers can customize carousel related effects and carousel progress indicators.
Here are two examples of using Carousel's default carousel progress indicator:
import 'package:awesome_carousel/carousels.dart';
import 'package:flutter/material.dart';

class WidgetCarouselDemo extends StatelessWidget {
const WidgetCarouselDemo({Key? key});

@override
Widget build(BuildContext context) {
// Get the screen width and height
final double width = MediaQuery.of(context).size.width;
final double height = MediaQuery.of(context).size.height;

// Define a list of colors for carousel items
final List<Color> colors = [
Colors.amber,
Colors.blue,
Colors.red,
Colors.green,
const Color.fromARGB(255, 59, 255, 177),
];

// Create a list of widget units for the carousel
List<Widget> units = [];

for (var i = 0; i < colors.length; i++) {
units.add(
Container(
width: width,
height: height,
decoration: BoxDecoration(
color: colors[i],
),
child: Center(
child: Text(
'Page $i',
style: const TextStyle(
fontSize: 46,
fontWeight: FontWeight.w900,
),
),
),
),
);
}

return Column(
children: [
// Create a horizontal carousel with circular indicators
Carousel(
units,
indicatorShape: BoxShape.circle,
indicatorWidth: 16,
currentIndicatorColor: Colors.purple,
),
const Divider(),
// Create a vertical carousel with rectangular indicators
ClipRRect(
borderRadius: BorderRadius.circular(40.0), // Rounded corner radius
child: Carousel(
units.reversed.toList(),
scrollDirection: Axis.vertical,
indicatorShape: BoxShape.rectangle,
indicatorWidth: 10,
indicatorHeight: 10,
currentIndicatorColor: Colors.pink,
onUnitTapped: (index) => print('Carousel unit $index was tapped'),
onIndicatorTapped: (index) => print('Progress indicator unit $index was tapped'),
),
)
],
);
}
}
copied to clipboard
The effect is as follows:

In order to achieve more complex functions, it is necessary to define more parameters and use the carousel controller. The following is an example of customizing the carousel progress indicator style and using network pictures as carousel units.
import 'package:flutter/material.dart';
import 'package:awesome_carousel/carousels.dart';

class NetworkImageCarouselDemo extends StatelessWidget {
final List<String> imageUrls;

final CarouselController _controller;

const NetworkImageCarouselDemo(
this.imageUrls,
this._controller, {
super.key,
});

@override
Widget build(BuildContext context) {
return Column(
children: [
Carousel(
_buildImages(context),
height: 400.0, // 设置轮播图高度
controller: _controller,
indicatorColor: const Color.fromARGB(255, 190, 255, 130),
// currentIndicatorColor: Colors.transparent,
indicatorBuilder: _indicatorBuilder,
// 当用户点击图像时触发的回调函数
onUnitTapped: (int index) {
print('点击了第 $index 张图片');
},
),
Row(
mainAxisAlignment: MainAxisAlignment.center,
children: [
ElevatedButton(
onPressed: () {
_controller.toFirstPage();
},
child: const Text('首页'),
),
const Spacer(
flex: 1,
),
ElevatedButton(
onPressed: () {
_controller.toPreviousPage();
},
child: const Text('上一页'),
),
const Spacer(
flex: 1,
),
ElevatedButton(
onPressed: () {
_controller.toNextPage();
},
child: const Text('下一页'),
),
const Spacer(
flex: 1,
),
ElevatedButton(
onPressed: () {
_controller.toLastPage();
},
child: const Text('尾页'),
),
],
)
],
);
}

List<Widget> _buildImages(BuildContext context) {
List<Widget> res = [];
for (String url in imageUrls) {
res.add(
Image.network(
url,
fit: BoxFit.cover, // 使图片宽度占满
width: MediaQuery.of(context).size.width, // 设置宽度为屏幕宽度
errorBuilder: (context, error, stackTrace) {
// 在加载失败时返回一个占位图，确保图片占用固定高度
return Container(
height: MediaQuery.of(context).size.height,
color: Colors.grey,
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
const Text(
'Image loading error:',
style: TextStyle(
color: Colors.red,
),
),
Text(
"原因: $error\n追溯：$stackTrace",
style: const TextStyle(
color: Colors.white,
),
maxLines: 9,
overflow: TextOverflow.ellipsis,
),
],
),
);
},
),
);
}
return res;
}

Map<String, Widget> _indicatorBuilder(int index) {
return {
'plain': Container(
padding: const EdgeInsets.all(10),
child: Column(
children: [
const Text(
'plain',
style: TextStyle(
color: Colors.grey,
),
),
Container(
width: 30,
height: 10,
decoration: const BoxDecoration(color: Colors.white),
),
],
),
),
'active': Container(
padding: const EdgeInsets.all(10),
child: Column(
children: [
const Icon(
Icons.arrow_circle_down,
color: Colors.amber,
),
const Text(
'active',
style: TextStyle(
color: Colors.red,
fontSize: 20,
fontWeight: FontWeight.w700,
),
),
Container(
width: 30,
height: 10,
decoration: BoxDecoration(
color: switch (index) {
0 => Colors.blue,
1 => Colors.red,
2 => Colors.green,
3 => Colors.pink,
_ => Colors.purple,
},
),
),
],
),
)
};
}
}

copied to clipboard
The effect is as follows:

As you can see, because you can completely customize the carousel indicator and carousel items, as long as you have enough imagination, you can package some complex but exquisite carousels. For example, in the e-commerce scene, the first carousel unit is the introduction video of the goods, and the corresponding carousel indicator is the progress bar of the video, while the subsequent carousel unit is only the carousel picture. For example:

This can be easily realized by integrating the corresponding video player module with this module.
Network Carousel #

Added in v1.0.0+1.

A network carousel is a widely used form of carousel, especially in today's web applications, that displays a set of images in a cyclic manner. It is derived from the generic carousel class, Carousel, and is represented by the NetImgCarousel class. With NetImgCarousel, you can load a collection of images from URLs for a network carousel and customize various parameters related to images and the network.
Here is an example of how to use the NetImgCarousel class.
import 'package:flutter/material.dart';
import 'package:awesome_carousel/carousels.dart' show NetImgCarousel;

class NetImgCarouselExample extends StatelessWidget {
final List<String> imageUrls = [
'https://gitee.com/jacklee1995/example-pictures/raw/master/shoe/shoe1(1).png',
'https://gitee.com/jacklee1995/example-pictures/raw/master/shoe/shoe1(3).png',
'https://gitee.com/jacklee1995/example-pictures/raw/master/shoe/shoe1(5).png',
'https://gitee.com/jacklee1995/example-pictures/raw/master/shoe/shoe1(7).png',
'https://gitee.com/jacklee1995/example-pictures/raw/master/shoe/shoe1(2).png',
];

NetImgCarouselExample({super.key});

@override
Widget build(BuildContext context) {
return Center(
child: NetImgCarousel(
imageUrls,
height: 400.0,
indicatorColor: Colors.grey,
currentIndicatorColor: Colors.blue,
onUnitTapped: (index) {
// Carousel unit callback event
print('Tapped on unit $index');
},
onIndicatorTapped: (index) {
// Carousel indicator callback event
print('Tapped on indicator $index');
},
),
);
}
}
copied to clipboard
The running result of the code is as follows:

The NetImgCarousel class allows you to create network carousels with ease, making it convenient to display a collection of images from web URLs.
The following table describes the parameters of the netimgroom constructor:



Parameter Name
Type
Default Value
Description




imageUrls
List<String>

List of network image URLs to be displayed in the carousel.


height
double
400.0
Height of the carousel component.


width
double
0.0
Width of the carousel component.


useindicator
bool
true
Whether to use indicators, defaults to true.


onUnitTapped
FunctionWithAInt?

Callback function when a unit in the carousel is clicked, optional.


onIndicatorTapped
FunctionWithAInt?

Callback function when an indicator is clicked, optional.


indicatorBuilder
FunctionIndicatorBuilder?

Custom indicator builder function, optional.


indicatorColor
Color
Colors.white
Default indicator color.


currentIndicatorColor
Color
Colors.blue
Color of the currently selected indicator.


indicatorWidth
double
40.0
Indicator width.


indicatorHeight
double
26.0
Indicator height.


indicatorMargin
double
3.0
Spacing between indicators.


indicatorToBottom
double
10.0
Distance of indicators from the bottom.


indicatorShape
BoxShape
BoxShape.rectangle
Default indicator shape.


pageSnapping
bool
true
Whether to enable page snapping, defaults to true.


padEnds
bool
true
Whether to add extra pages at the beginning and end of the carousel, default is true.


clipBehavior
Clip
Clip.hardEdge
The behavior for the clip.


reverse
bool
false
Whether to reverse the order of items.


scrollDirection
Axis
Axis.horizontal
The axis along which the page view scrolls.


controller
CarouselController?

Carousel controller, optional.


disableIndicatorDefaultCallbacks
bool
false
Whether to disable default indicator callback functions.


imgScale
double
1.0
Image scale factor, default is 1.0.


imgFrameBuilder
ImageFrameBuilder?

Image frame builder, optional.


imgLoadingBuilder
ImageLoadingBuilder?

Image loading builder, optional.


imgErrorBuilder
ImageErrorWidgetBuilder?

Image error widget builder, optional.


imgExcludeFromSemantics
bool
false
Whether to exclude the image from semantics, default is false.


imgSemanticLabel
String?

Image semantic label, optional.


imgWidth
double?

Image width, optional.


imgHeight
double?

Image height, optional.


imgColor
Color?

Image color, optional.


imgOpacity
Animation<double>?

Image opacity, optional.


imgColorBlendMode
BlendMode?

Image color blend mode, optional.


imgFit
BoxFit?

Image fit, optional.


imgCenterSlice
Rect?

Image center slice, optional.


imgAlignment
AlignmentGeometry
Alignment.center
Image alignment, optional.


imgRepeat
ImageRepeat
ImageRepeat.noRepeat
Image repeat mode, optional.


imgMatchTextDirection
bool
false
Whether the image should match the text direction, optional.


imgGaplessPlayback
bool
false
Whether to enable gapless playback for the image, optional.


imgFilterQuality
FilterQuality
FilterQuality.low
Image filter quality, optional.


imgIsAntiAlias
bool
false
Whether the image should be anti-aliased, optional.


imgHeaders
Map<String, String>?

Headers for the network image, optional.


imgCacheWidth
int?

Image cache width, optional.


imgCacheHeight
int?

Image cache height, optional.



Local Image Carousel #

Added in v1.0.0+1.

Local resource picture carousel is also a very common type of carousel. In Flutter, you need to configure the assets option of the pubspec.yaml file first to ensure that your pictures can be loaded normally.
Here's a simple example:
import 'package:flutter/material.dart';
import 'package:awesome_carousel/img_carousels/assert_img_carousel.dart';

class AssetImgCarouselExample extends StatelessWidget {
final List<String> assetImagePaths = [
'assets/image1.png',
'assets/image2.png',
'assets/image3.png',
];

AssetImgCarouselExample({super.key});

@override
Widget build(BuildContext context) {
return Center(
child: AssetImgCarousel(
assetImagePaths,
height: 400.0,
indicatorColor: Colors.grey,
currentIndicatorColor: Colors.blue,
indicatorShape: BoxShape.circle,
onUnitTapped: (index) {
print('Tapped on unit $index');
},
onIndicatorTapped: (index) {
print('Tapped on indicator $index');
},
),
);
}
}
copied to clipboard
The code produces the following result:

The table below describes the parameters of the AssetImgCarousel constructor:



Parameter Name
Parameter Type
Description




assetImagePaths
List
List of asset image file paths for the carousel.


height
double
Height of the carousel component.


width
double
Width of the carousel component.


useindicator
bool
Whether to use indicators, defaults to true.


onUnitTapped
FunctionWithAInt?
Callback function when a unit in the carousel is clicked, optional.


onIndicatorTapped
FunctionWithAInt?
Callback function when an indicator is clicked, optional.


indicatorBuilder
FunctionIndicatorBuilder?
Custom indicator builder function, optional.


indicatorColor
Color
Default indicator color.


currentIndicatorColor
Color
Color of the currently selected indicator.


indicatorWidth
double
Indicator width.


indicatorHeight
double
Indicator height.


indicatorMargin
double
Spacing between indicators.


indicatorToBottom
double
Distance of indicators from the bottom.


indicatorShape
BoxShape
Default indicator shape, defaults to a rectangle.


pageSnapping
bool
Whether to enable page snapping, defaults to true.


padEnds
bool
Whether to add extra pages at the beginning and end of the carousel, default is true.


clipBehavior
Clip
The behavior for the clip.


reverse
bool
Whether to reverse the order of items.


scrollDirection
Axis
The axis along which the page view scrolls.


controller
CarouselController?
Carousel controller, optional.


disableIndicatorDefaultCallbacks
bool
Whether to disable default indicator callback functions.


imgScale
double
Image scale factor.


imgFrameBuilder
ImageFrameBuilder?
Custom image frame builder, optional.


imgExcludeFromSemantics
bool
Whether the image should be excluded from semantics, default is false.


imgAlignment
AlignmentGeometry
Alignment of the image within its frame.


imgRepeat
ImageRepeat
How the image should repeat.


imgMatchTextDirection
bool
Whether the image should match the text direction.


imgGaplessPlayback
bool
Whether to enable gapless playback of images, default is false.


imgFilterQuality
FilterQuality
The filter quality for the image, default is FilterQuality.low.


imgIsAntiAlias
bool
Whether the image should be anti-aliased.


imgErrorBuilder
ImageErrorWidgetBuilder?
Custom image error widget builder, optional.


imgSemanticLabel
String?
Semantic label for the image, optional.


imgWidth
double?
Image width, optional.


imgHeight
double?
Image height, optional.


imgColor
Color?
Color applied to the image, optional.


imgOpacity
Animation
Image opacity, optional.


imgColorBlendMode
BlendMode?
Blend mode applied to the image, optional.


imgFit
BoxFit?
How the image fits within its frame, optional.


imgCenterSlice
Rect?
The center slice for the image, optional.


imgHeaders
Map<String, String>?
Headers for network image requests, optional.


imgCacheWidth
int?
Maximum width for image caching, optional.


imgCacheHeight
int?
Maximum height for image caching, optional.


imgPackage
String?
Package name for the image, optional.



API #
Class CarouselController #
The CarouselController class is used to manage carousel control. It includes multiple methods for controlling carousel navigation, animations, and status notifications.
Constructor
CarouselController(
int total, {
int initialPage = 0,
bool keepPage = true,
double viewportFraction = 1.0,
Curve curve = Curves.ease,
Duration duration = const Duration(milliseconds: 300),
})
copied to clipboard
Parameters

total (int): Represents the total number of pages in the carousel.
initialPage (int): Represents the initial page index, defaulting to 0.
keepPage (bool): Indicates whether to keep the page's state after navigating, with a default of true.
viewportFraction (double): Represents the fraction of the page width that is visible in the viewport, with a default of 1.0.
curve (Curve): Represents the animation curve for page transitions, defaulting to Curves.ease.
duration (Duration): Represents the duration of the page transition animation, with a default of Duration(milliseconds: 300).

Methods
goToPage(int page)
This method is used to navigate to a specific page within the carousel using a custom method.

page (int): The index of the page to navigate to.

toFirstPage()
This method is used to navigate to the first page within the carousel using a custom method.
toPreviousPage()
This method is used to navigate to the previous page within the carousel using a custom method. If the current page is already the first page, it will navigate to the last page.
toNextPage()
This method is used to navigate to the next page within the carousel using a custom method. If the current page is already the last page, it will navigate to the first page.
toLastPage()
This method is used to navigate to the last page within the carousel using a custom method.
Properties
currentPage

Type: int
Description: Gets or sets the current page index of the carousel. By getting the currentPage property, you can obtain the current page index. By setting the currentPage property, you can navigate to a specific page.

Example #
final controller = CarouselController(3);

// Get the current page index
int current = controller.currentPage;

// Navigate to the second page
controller.goToPage(1);

// Navigate to the next page
controller.toNextPage();
copied to clipboard
Class Carousel #
The Carousel class is a versatile carousel component that allows you to create various types of carousels in your Flutter application. You can configure the appearance of the carousel, control its behavior, and define callback functions.
Constructor
Carousel(
List<Widget> units, {
Key? key,
double height = 400.0,
double width = 0.0,
FunctionWithAInt? onUnitTapped,
FunctionWithAInt? onIndicatorTapped,
bool useindicator = true,
Color indicatorColor = Colors.white,
Color currentIndicatorColor = Colors.blue,
double indicatorWidth = 40.0,
double indicatorHeight = 26.0,
double indicatorMargin = 3.0,
double indicatorToBottom = 10.0,
BoxShape indicatorShape = BoxShape.rectangle,
FunctionIndicatorBuilder? indicatorBuilder,
bool pageSnapping = true,
bool padEnds = true,
Clip clipBehavior = Clip.hardEdge,
bool reverse = false,
Axis scrollDirection = Axis.horizontal,
CarouselController? controller,
})
copied to clipboard
Parameters

units (List<Widget>): The list of components to be displayed in the carousel.
key (Key?): An optional parameter used to identify the widget in the widget tree.
height (double): The height of the carousel component, with a default value of 400.0.
width (double): The width of the carousel component, with a default of 0.0 (auto-adapts to screen width).
onUnitTapped (FunctionWithAInt?): A callback function triggered when a carousel unit is tapped. It is optional and receives an integer parameter representing the tapped unit's index.
onIndicatorTapped (FunctionWithAInt?): A callback function triggered when an indicator is tapped. It is optional and receives an integer parameter representing the tapped indicator's index.
useindicator (bool): Controls whether to display indicators beneath the carousel. The default value is true.
indicatorColor (Color): The default color of the indicators, defaulting to white.
currentIndicatorColor (Color): The color of the indicator for the currently selected page, defaulting to blue.
indicatorWidth (

double): The width of each indicator, with a default of 40.0.

indicatorHeight (double): The height of each indicator, with a default of 26.0.
indicatorMargin (double): The horizontal margin between indicators, with a default of 3.0.
indicatorToBottom (double): The distance of the indicators from the bottom, with a default of 10.0.
indicatorShape (BoxShape): The shape of the indicators, which can be either BoxShape.rectangle or BoxShape.circle. The default is BoxShape.rectangle.
indicatorBuilder (FunctionIndicatorBuilder?): A custom indicator builder function that allows you to define custom appearances for the indicators.
pageSnapping (bool): Controls whether to enable page snapping, with a default value of true.
padEnds (bool): Controls whether to add additional pages at the beginning and end of the carousel, with a default of true.
clipBehavior (Clip): Specifies how to clip the content of carousel units, defaulting to Clip.hardEdge.
reverse (bool): Controls whether to scroll through carousel units in reverse order, with a default value of false.
scrollDirection (Axis): Specifies the direction in which carousel units are scrolled, which can be Axis.horizontal or Axis.vertical, with a default of Axis.horizontal.
controller (CarouselController?): An optional carousel controller used to control the behavior and state of the carousel.
disableIndicatorDefaultCallbacks (bool): Specifies whether to disable the default indicator callback functions. The default value is false. When set to true, default indicator click events are not executed.

Example
Carousel(
[
Image.network('https://example.com/image1.jpg'),
Image.network('https://example.com/image2.jpg'),
Image.network('https://example.com/image3.jpg'),
],
height: 300.0,
onUnitTapped: (int index) {
print('Tapped unit at index $index');
},
indicatorColor: Colors.red,
currentIndicatorColor: Colors.green,
)
copied to clipboard
class NetImgCarousel #

Added in v1.0.0+1.

See above.