jk_fast_listview

Description:

jk fast listview

JkFastListView #
ListView / GridView for Flutter. Support fast scrolling among a large amount of data, flexible widget size, index-based scrolling, item recycler.
Features #

Most API are the same with official flutter's ListView / GridView.
Fast scrolling among a large amount of data.
Flexible widget size.
scroll to item with specified index.
Listen to index of current first visible item.
Item recycler.

Who need this package? #

If all the items has the same width & height, please use official flutter ListView and GridView. Both classes work well with fixed-size items, also support fast scrolling among a large amount of data in this case.
If the width & height of items are variable, and you need to fast jump to far-far-away item (by call jumpToIndex / animateToIndex, or drag scrollbar by user), please use this package. This is useful for some applications (ex. chat app).

Quick Start #
Installation #
Add this to your package's pubspec.yaml file:
dependencies:
jk_fast_listview: ^0.8.0
copied to clipboard
Usage #
Build a ListView #
NOTE: name of most of the params are the same with official flutter's ListView and GridView. We don't explain each params here again.
var listview = JkFastListView(
itemCount: 999999,
itemBuilder: (context, index) => Text("Item $index"),

// optional, cannot be used in grid type
separatorBuilder: (context, index) => const Divider(), // optional
);
copied to clipboard
Build a GridView #
var listview = JkFastListView(
itemCount: 999999,
itemBuilder: (context, index) => Text("Item $index"),

crossAxisCount: 3, // add this line to make 3 items per row

// another way to specify item count per row, cannot use with 'crossAxisCount'
// maxCrossAxisExtent: 300,

mainAxisSpacing: 20, // optional
crossAxisSpacing: 20, // optional
);
copied to clipboard
other common optional params #
The definition of these following parameters can be found in ListView
var listview = JkFastListView(
...
cacheExtent: 300, // optional
scrollDirection: Axis.horizontal, // optional
reverse: true, // optional
);
copied to clipboard
set initial item index #
final itemController = JkItemController();

// [optional] set which item should be visible from the beginning
// initialIndex: index of item that should be visible from the beginning
// alignment: null or 0~1 (double)
// null: not specified the position of item
// 0: place the item at the beginning of listview
// 1: place the item at the end of listview
// 0.5: place the item at the center of listview
itemController.setInitialIndex(initialIndex: 1000, alignment: 0.5);

var listview = JkFastListView(
...
itemController: itemController,
);
copied to clipboard
scrollTo / animateTo item with specified index #
// jump to item with index 1000
itemController.jumpToIndex(1000, alignment: 1);

// like 'jumpToIndex', but with animation
itemController.animateToIndex(1000,
alignment: 1,
duration: const Duration(milliseconds: 300),
curve: Curves.easeIn);
copied to clipboard
Listen to index of current first visible item #
var listview = JkFastListView(
...
onScrollPosition: (index, ratio) {
log("first visible item index is $index");
// ratio: 0~1 (double),
// 0: not visible,
// 1: totally visible,
// 0.5: only bottom-half of the item is visible
},
);
copied to clipboard
get current first visible item index #
int topIndex = itemController.getFirstVisibleIndex();
copied to clipboard
Precautions about recycler #
There are something different from the official flutter's ListView and GridView.
This package use recycler to recycle (not delete) items when items scroll out-of visible area, and restore (not create) back items when items scroll into visible area.
So, for some case (ex. your items have animation effect), you should override didUpdateWidget method in State of StatefulWidget of your item widget, and do something to cleanup some resources or state here (ex. stop animation).
The method didUpdateWidget will be called every time when a widget restore-back from recycler, with a new widget configuration pass into.
Performance tuning #
Not assign a key as possible.

A widget without a key will use recycler to increase performance. Such a widget will be recycled when it is scroll out of screen, and will be reused later when a another new item (maybe with different index) scroll-in.
A widget with a key won't be recycled. Such a widget is always created and destroyed when it is scrolling in and out of visible area.
only assign a key to widget if items in the visible area will be reordered / removed, and your widget has state that you want to keep after items reordered / removed in visible area.
I think it is better to remember item state outside of item widget.