Skip to content

Commit

Permalink
Update documentation & version
Browse files Browse the repository at this point in the history
  • Loading branch information
hongduc6 committed Apr 11, 2023
1 parent bda3088 commit e14b734
Show file tree
Hide file tree
Showing 5 changed files with 160 additions and 165 deletions.
8 changes: 7 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,10 @@
## [0.0.3]
* Reduced SDK constraints (>= 2.12.0)
* Added outermost item discarded effect and notify discarded swipe direction
* Improve performance
* Improve performance

## [1.0.0]
* Added consume mode, which allow cards to disappear after swiped.
* Take a custom StackedListController as a param for StackedListCarousel constructor.
* More smooth and clean animation.
* Allow user to customize outermost card and inner cards decoration.
261 changes: 121 additions & 140 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,20 @@
# stacked_list_carousel

**This package allows you to create a carousel of stacked items that is highly customizable and interactive. It is particularly well-suited for specific use cases, such as in-app banners.**
**This package allows you to create a carousel of stacked items that is highly customizable and interactive. It is particularly well-suited for specific use cases, such as in-app banners. Support 2 carousel behavior: loop and consume.**

<img alt="Demo" src="https://raw.githubusercontent.com/hongduc6/stacked_list_carousel/master/example/asset/demo.gif" height="500">
### Loop mode
The item won't be removed from items list after being swiped and will be inserted to last position. It also implements auto slide in a exact set duration.

## Features
* Support customize widget's items builder which provides variety attributes. The itemBuilder provides displayed size of built target, its index inside item list and whether built target is outermost displayed widget.

* Allow config fixed aspect ratio of display items. If cardAspectRatio is not provided, the rendered view will occupy all remain space.
<img alt="Demo" src="https://raw.githubusercontent.com/hongduc6/stacked_list_carousel/master/example/asset/loop_example.gif" height="500">

* 4 x 3
<img alt="Demo" src="https://raw.githubusercontent.com/hongduc6/stacked_list_carousel/master/example/asset/4_3.png" height="300">
### Consume mode
The item will be removed from items list after being swiped. The auto slide feature is not enabled in this mode. Also, an empty builder must be provided to build empty UI when all cards are consumed.

* 16 x 9
<img alt="Demo" src="https://raw.githubusercontent.com/hongduc6/stacked_list_carousel/master/example/asset/16_9.png" height="300">
<img alt="Demo" src="https://raw.githubusercontent.com/hongduc6/stacked_list_carousel/master/example/asset/consume_example.gif" height="500">

* Provide item discard listener, which provides its information and discarded swipe direction.
## Features
* Create a widget carousel which align its children vertically with well-animated and smooth transition animation.
* Provide item discard action listener, which provides its information and discarded swipe direction.

## Documentation

Expand All @@ -29,6 +28,29 @@ dependencies:
stacked_list_carousel: <latest version>
```

### Attributes

| **Name** | **Type** | **Notes** | **Description** |
|:------------------------------:|:---------------------------------:|:------------------------------------------------------------------------------------------------:|:--------------------------------------------------------:|
| items | List<T> | | List of card models with T type |
| cardBuilder | Function(BuildContext,T,Size) | - second params is built card model - third params are rendered card size | Card widget builder function |
| behavior | CarouselBehavior | enum: loop / consume | Config carousel transition behavior |
| outermostCardWrapper | Widget Function(Widget)? | wrap built outermost card with another widget | Avoid using complicated build functions if possible |
| innerCardsWrapper | Widget Function(Widget)? | wrap built inner cards with another widget | -- |
| cardSwipedCallback | void Function(T, SwipeDirection)? | - first param is swiped card model - second param is swiped direction when the card is discarded | Notify card discarded |
| cardAspectRatio | double? | | The width / height ratio of each card |
| controller | StackedListController? | | Provide a custom StackedListController |
| emptyBuilder | WidgetBuilder? | | Must be provided in consume mode |
| alignment | StackedListAxisAlignment | enum: top / bottom | Aligns card vertically top or bottom |
| outermostCardHeightFactor | double | Must be lower than 1 | The ratio between outermost card height / view height |
| animationDuration | Duration | | Transition animation duration |
| transitionCurve | Curve | | Defaults to Curves.easeIn |
| maxDisplayedItemCount | int | | Config max amount of displayed card |
| itemGapHeightFactor | double | outermostCardHeightFactor + (maxDisplayedItemCount - 1) * itemGapHeightFactor <= 1 | The height factor of gap between cards and view height |
| autoSlideDuration | Duration | | Config auto slide duration in loop mode |
| outermostCardAnimationDuration | Duration | | The duration of outermost card's flying effect animation |

### Implements

Import the package:
Expand All @@ -40,145 +62,104 @@ import 'package:stacked_list_carousel/stacked_list_carousel.dart';
Then use StackedCardCarousel widget

```
import 'package:flutter/material.dart';
import 'package:stacked_list_carousel/stacked_list_carousel.dart';
void main() => runApp(const MyApp());
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Stacked Cards Example',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: const Home(title: 'Awesome Card Carousel'),
);
}
}
class Home extends StatefulWidget {
const Home({Key? key, required this.title}) : super(key: key);
final String title;
@override
State<Home> createState() => _HomeState();
}
class _HomeState extends State<Home> {
@override
Widget build(BuildContext context) {
return Scaffold(
backgroundColor: Colors.grey,
body: StackedListCarousel<AwesomeInAppBanner>(
StackedListCarousel<AwesomeInAppBanner>(
items: banners,
// Highly customizable builder function which actual widget's size,
// its index inside item list, and whether built item is outermost
itemBuilder: (context, size, index, isOutermost) => ClipRRect(
borderRadius: BorderRadius.circular(6.0),
child: Stack(
children: [
Image.network(
banners[index].imgUrl,
width: size.width,
height: size.height,
),
Align(
alignment: Alignment.bottomRight,
child: Padding(
padding: const EdgeInsets.all(16.0),
child: Text(
banners[index].title,
style: TextStyle(
fontWeight: FontWeight.bold,
color: Colors.white,
fontSize:
30.0 * size.width / MediaQuery.of(context).size.width,
behavior: CarouselBehavior.consume,
// A widget builder callback to build cards with context, card model
// and its size attributes.
cardBuilder: (context, item, size) {
return ClipRRect(
borderRadius: BorderRadius.circular(10.0),
child: Stack(
children: [
Image.network(
item.imgUrl,
width: size.width,
height: size.height,
fit: BoxFit.cover,
),
Align(
alignment: Alignment.bottomRight,
child: Padding(
padding: const EdgeInsets.all(16.0),
child: Text(
item.title,
style: TextStyle(
fontWeight: FontWeight.bold,
color: Colors.white,
fontSize: 30.0 *
size.width /
MediaQuery.of(context).size.width,
),
),
),
),
),
if (!isOutermost)
SizedBox.expand(
child: Container(color: Colors.grey.withOpacity(0.65)),
)
],
),
),
// Config card's aspect ratio
cardAspectRatio: 2 / 3,
],
),
);
},
// You can config fixed card width / height ratio. For default, the ratio
// is view size width / height
// cardAspectRatio: 0.75,
// Config outermost card height factor relative to view height
outermostCardHeightFactor: 0.7,
outermostCardHeightFactor: 0.8,
// Gap height factor relative to view height
itemGapHeightFactor: 0.05,
// Config max item displayed count
maxDisplayedItemsCount: 3,
// Config view size height factor relative to view height
viewSizeHeightFactor: 0.85,
// Config animation transitions duration
autoSlideDuration: const Duration(seconds: 4),
transitionDuration: const Duration(milliseconds: 250),
outermostTransitionDuration: const Duration(milliseconds: 200),
// You can listen for discarded item and its swipe direction
onItemDiscarded: (index, direction) {
ScaffoldMessenger.of(context).clearSnackBars();
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(
content: Text(
'banner ${banners[index].title} discarded in $direction direction!'),
maxDisplayedItemCount: 3,
// You can config transition duration here (the animation between cards
// swap). Defaults to 450 milliseconds
animationDuration: const Duration(milliseconds: 550),
// You can config auto slide duration. This only works in loop mode.
autoSlideDuration: const Duration(seconds: 8),
// Define cards align
alignment: StackedListAxisAlignment.bottom,
// In consume mode, you must declare the empty builder, which will be
// built when user swiped all cards.
emptyBuilder: (context) => const Center(
child: Text('You have consumed all cards!'),
),
// You can customize inner cards wrapper builder. For example, you want to
// shade the unready cards, just wrap it with a gray decorated box.
innerCardsWrapper: (child) {
return Stack(
children: [
child,
Positioned.fill(
child: DecoratedBox(
decoration: BoxDecoration(
color: const Color(0xffA6A3CC).withOpacity(0.64),
borderRadius: BorderRadius.circular(12),
),
),
),
],
);
},
// You can also customize outermost card builder for some special effects.
outermostCardWrapper: (child) {
return DecoratedBox(
decoration: const BoxDecoration(
boxShadow: [
BoxShadow(
color: Colors.blueAccent,
blurRadius: 12,
blurStyle: BlurStyle.normal,
spreadRadius: 6,
),
],
),
child: child,
);
},
// When implementing use case like tinder card swipe,
// you'll wish to know what swipe behavior user did.
// This callback will provide the discard direction of
// corresponding item for you.
cardSwipedCallback: (item, direction) {
debugPrint('card swiped: ${item.title}, $direction');
},
),
);
}
}
class AwesomeInAppBanner {
final String imgUrl;
final String title;
final Color color;
const AwesomeInAppBanner(
this.imgUrl,
this.title,
this.color,
);
}
List<AwesomeInAppBanner> banners = <AwesomeInAppBanner>[
AwesomeInAppBanner(
'https://picsum.photos/id/100/600/900',
'My awesome banner 1',
Colors.green.shade300,
),
AwesomeInAppBanner(
'https://picsum.photos/id/200/600/900',
'My awesome banner 2',
Colors.red.shade300,
),
AwesomeInAppBanner(
'https://picsum.photos/id/300/600/900',
'My awesome banner 3',
Colors.purple.shade300,
),
AwesomeInAppBanner(
'https://picsum.photos/id/400/600/900',
'My awesome banner 4',
Colors.yellow.shade300,
),
AwesomeInAppBanner(
'https://picsum.photos/id/500/600/900',
'My awesome banner 5',
Colors.blue.shade300,
),
AwesomeInAppBanner(
'https://picsum.photos/id/600/600/900',
'My awesome banner 6',
Colors.orange.shade300,
),
];
```

### Contribution
Expand Down
2 changes: 1 addition & 1 deletion example/lib/main.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ class _HomeState extends State<Home> {
),
body: StackedListCarousel<AwesomeInAppBanner>(
items: banners,
behavior: CarouselBehavior.loop,
behavior: CarouselBehavior.consume,
// A widget builder callback to build cards with context, card model
// and its size attributes.
cardBuilder: (context, item, size) {
Expand Down
Loading

0 comments on commit e14b734

Please sign in to comment.