Flutter列表和滚动控件小结
ListView
ListView 是一个 Flutter 中的控件,用于显示可滚动的列表。它可以包含多个子控件,并允许用户垂直或水平滚动列表项。以下是 ListView 的构造函数定义:
属性解析
ListView({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.shrinkWrap = false, // 是否缩小包裹内容
super.padding, // 内边距
this.itemExtent, // 每个列表项的高度或宽度
this.prototypeItem, // 用于计算高度的原型项目
bool addAutomaticKeepAlives = true, // 是否自动保留活动状态
bool addRepaintBoundaries = true, // 是否添加重绘边界
bool addSemanticIndexes = true, // 是否添加语义索引
super.cacheExtent, // 缓存范围
List<Widget> children = const <Widget>[], // 子控件列表
int? semanticChildCount, // 语义子控件数量
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
});
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry,表示内边距。
- itemExtent:可选参数,类型为 double,表示每个列表项的高度(垂直)或宽度(水平)。
- prototypeItem:可选参数,类型为 Widget,表示用于计算高度的原型项目。
- addAutomaticKeepAlives:可选参数,类型为 bool,表示是否自动保留活动状态,默认为 true。
- addRepaintBoundaries:可选参数,类型为 bool,表示是否添加重绘边界,默认为 true。
- addSemanticIndexes:可选参数,类型为 bool,表示是否添加语义索引,默认为 true。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- children:可选参数,类型为 List,表示子控件列表,默认为空列表。
- semanticChildCount:可选参数,类型为 int?,表示语义子控件数量。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('Comprehensive ListView Example'),
),
body: ListView(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: true, // 缩小包裹内容
padding: EdgeInsets.all(16.0), // 内边距
itemExtent: 60.0, // 每个列表项的高度
addAutomaticKeepAlives: true, // 自动保留活动状态
addRepaintBoundaries: true, // 添加重绘边界
addSemanticIndexes: true, // 添加语义索引
cacheExtent: 200.0, // 缓存范围
semanticChildCount: 4, // 语义子控件数量
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'list_view', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
children: <Widget>[
Container(
color: Colors.red,
height: 60.0,
child: Center(child: Text('Item 1')),
),
Container(
color: Colors.green,
height: 60.0,
child: Center(child: Text('Item 2')),
),
Container(
color: Colors.blue,
height: 60.0,
child: Center(child: Text('Item 3')),
),
Container(
color: Colors.yellow,
height: 60.0,
child: Center(child: Text('Item 4')),
),
],
),
),
);
}
}
ListView.builder
ListView.builder 是 Flutter 中用于创建一个懒加载列表视图的构造函数。与 ListView 不同的是,它只在需要时动态地生成其子项,而不是一次性创建所有子项,这对于大型或无限列表非常有效。
以下是 ListView.builder 的构造函数定义:
属性解析
ListView.builder({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.shrinkWrap = false, // 是否缩小包裹内容
super.padding, // 内边距
this.itemExtent, // 每个列表项的高度或宽度
this.prototypeItem, // 用于计算高度的原型项目
required NullableIndexedWidgetBuilder itemBuilder, // 构建每个列表项的回调函数
ChildIndexGetter? findChildIndexCallback, // 查找子项索引的回调函数
int? itemCount, // 列表项数量
bool addAutomaticKeepAlives = true, // 是否自动保留活动状态
bool addRepaintBoundaries = true, // 是否添加重绘边界
bool addSemanticIndexes = true, // 是否添加语义索引
super.cacheExtent, // 缓存范围
int? semanticChildCount, // 语义子控件数量
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
});
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry,表示内边距。
- itemExtent:可选参数,类型为 double,表示每个列表项的高度(垂直)或宽度(水平)。
- prototypeItem:可选参数,类型为 Widget,表示用于计算高度的原型项目。
- itemBuilder:必需参数,类型为 NullableIndexedWidgetBuilder,用于构建每个列表项的回调函数。
- findChildIndexCallback:可选参数,类型为 ChildIndexGetter,用于查找子项索引的回调函数。
- itemCount:可选参数,类型为 int?,表示列表项数量。
- addAutomaticKeepAlives:可选参数,类型为 bool,表示是否自动保留活动状态,默认为 true。
- addRepaintBoundaries:可选参数,类型为 bool,表示是否添加重绘边界,默认为 true。
- addSemanticIndexes:可选参数,类型为 bool,表示是否添加语义索引,默认为 true。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- semanticChildCount:可选参数,类型为 int?,表示语义子控件数量。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('ListView.builder Example'),
),
body: ListView.builder(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: true, // 缩小包裹内容
padding: EdgeInsets.all(16.0), // 内边距
itemExtent: 60.0, // 每个列表项的高度
itemCount: 100, // 列表项数量
itemBuilder: (context, index) {
// 构建每个列表项的回调函数
return Container(
color: index % 2 == 0 ? Colors.blue : Colors.green,
height: 60.0,
child: Center(child: Text('Item $index')),
);
},
addAutomaticKeepAlives: true, // 自动保留活动状态
addRepaintBoundaries: true, // 添加重绘边界
addSemanticIndexes: true, // 添加语义索引
cacheExtent: 200.0, // 缓存范围
semanticChildCount: 100, // 语义子控件数量
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'list_view_builder', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
),
),
);
}
}
这个示例展示了如何使用 ListView.builder 来构建一个可滚动、懒加载的列表视图,并且涵盖了大多数参数的用法。
ListView.separated
ListView.separated 是 Flutter 中用于创建一个带有分隔符的懒加载列表视图的构造函数。与 ListView.builder 不同,它在列表项之间插入了分隔符,这对于需要在列表项之间添加固定内容(如分隔线、广告等)的场景非常有用。
属性解析
ListView.separated({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.shrinkWrap = false, // 是否缩小包裹内容
super.padding, // 内边距
required NullableIndexedWidgetBuilder itemBuilder, // 构建每个列表项的回调函数
ChildIndexGetter? findChildIndexCallback, // 查找子项索引的回调函数
required IndexedWidgetBuilder separatorBuilder,// 构建分隔符的回调函数
required int itemCount, // 列表项数量
bool addAutomaticKeepAlives = true, // 是否自动保留活动状态
bool addRepaintBoundaries = true, // 是否添加重绘边界
bool addSemanticIndexes = true, // 是否添加语义索引
super.cacheExtent, // 缓存范围
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
});
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry,表示内边距。
- itemBuilder:必需参数,类型为 NullableIndexedWidgetBuilder,用于构建每个列表项的回调函数。
- findChildIndexCallback:可选参数,类型为 ChildIndexGetter,用于查找子项索引的回调函数。
- separatorBuilder:必需参数,类型为 IndexedWidgetBuilder,用于构建分隔符的回调函数。
- itemCount:必需参数,类型为 int,表示列表项数量。
- addAutomaticKeepAlives:可选参数,类型为 bool,表示是否自动保留活动状态,默认为 true。
- addRepaintBoundaries:可选参数,类型为 bool,表示是否添加重绘边界,默认为 true。
- addSemanticIndexes:可选参数,类型为 bool,表示是否添加语义索引,默认为 true。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('ListView.separated Example'),
),
body: ListView.separated(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: true, // 缩小包裹内容
padding: EdgeInsets.all(16.0), // 内边距
itemCount: 20, // 列表项数量
itemBuilder: (context, index) {
// 构建每个列表项的回调函数
return Container(
color: Colors.blue,
height: 60.0,
child: Center(child: Text('Item $index')),
);
},
separatorBuilder: (context, index) {
// 构建分隔符的回调函数
return Divider(color: Colors.black);
},
addAutomaticKeepAlives: true, // 自动保留活动状态
addRepaintBoundaries: true, // 添加重绘边界
addSemanticIndexes: true, // 添加语义索引
cacheExtent: 200.0, // 缓存范围
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'list_view_separated', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
),
),
);
}
}
ListView.custom
ListView.custom 是 Flutter 中一个高度可定制的列表视图构造函数,可以使用自定义的 SliverChildDelegate 来控制子项的生成和管理。它比其他 ListView 构造函数更灵活,但也需要更多的配置。
以下是 ListView.custom 的构造函数定义:
属性解析
const ListView.custom({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.shrinkWrap = false, // 是否缩小包裹内容
super.padding, // 内边距
this.itemExtent, // 每个列表项的高度
this.prototypeItem, // 用于计算高度的原型项目
required this.childrenDelegate, // 子项代理
super.cacheExtent, // 缓存范围
super.semanticChildCount, // 语义子控件数量
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
})
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry,表示内边距。
- itemExtent:可选参数,类型为 double,表示每个列表项的高度(垂直)或宽度(水平)。
- prototypeItem:可选参数,类型为 Widget,表示用于计算高度的原型项目。
- childrenDelegate:必需参数,类型为 SliverChildDelegate,用于控制子项的生成和管理。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- semanticChildCount:可选参数,类型为 int?,表示语义子控件数量。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('ListView.custom Example'),
),
body: ListView.custom(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: true, // 缩小包裹内容
padding: EdgeInsets.all(16.0), // 内边距
itemExtent: 60.0, // 每个列表项的高度
childrenDelegate: SliverChildBuilderDelegate(
(context, index) {
return Container(
color: index % 2 == 0 ? Colors.blue : Colors.green,
height: 60.0,
child: Center(child: Text('Item $index')),
);
},
childCount: 100, // 列表项数量
),
cacheExtent: 200.0, // 缓存范围
semanticChildCount: 100, // 语义子控件数量
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'list_view_custom', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
),
),
);
}
}
GridView.count
GridView.count 是 Flutter 中一个用于创建具有固定列数的网格视图的构造函数。它提供了一种简单的方法来定义网格布局,而不需要手动计算每个项目的位置。
属性解析
GridView.count({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.shrinkWrap = false, // 是否缩小包裹内容
super.padding, // 内边距
required int crossAxisCount, // 交叉轴(水平)上的列数
double mainAxisSpacing = 0.0, // 主轴(垂直)上的间距
double crossAxisSpacing = 0.0, // 交叉轴(水平)上的间距
double childAspectRatio = 1.0, // 子项宽高比
bool addAutomaticKeepAlives = true, // 是否自动保留活动状态
bool addRepaintBoundaries = true, // 是否添加重绘边界
bool addSemanticIndexes = true, // 是否添加语义索引
super.cacheExtent, // 缓存范围
List<Widget> children = const <Widget>[], // 子组件列表
int? semanticChildCount, // 语义子控件数量
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
})
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry,表示内边距。
- crossAxisCount:必需参数,类型为 int,表示交叉轴(水平)上的列数。
- mainAxisSpacing:可选参数,类型为 double,表示主轴(垂直)上的间距,默认为 0.0。
- crossAxisSpacing:可选参数,类型为 double,表示交叉轴(水平)上的间距,默认为 0.0。
- childAspectRatio:可选参数,类型为 double,表示子项的宽高比,默认为 1.0。
- addAutomaticKeepAlives:可选参数,类型为 bool,表示是否自动保留活动状态,默认为 true。
- addRepaintBoundaries:可选参数,类型为 bool,表示是否添加重绘边界,默认为 true。
- addSemanticIndexes:可选参数,类型为 bool,表示是否添加语义索引,默认为 true。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- children:可选参数,类型为 List,表示子组件列表,默认为空列表。
- semanticChildCount:可选参数,类型为 int?,表示语义子控件数量。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('GridView.count Example'),
),
body: GridView.count(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: true, // 缩小包裹内容
padding: EdgeInsets.all(16.0), // 内边距
crossAxisCount: 4, // 每行有 4 列
mainAxisSpacing: 10.0, // 主轴(垂直)上的间距
crossAxisSpacing: 10.0, // 交叉轴(水平)上的间距
childAspectRatio: 1.0, // 子项宽高比
children: List.generate(20, (index) {
// 生成 20 个子项
return Container(
color: Colors.blueAccent,
child: Center(child: Text('Item $index')),
);
}),
cacheExtent: 200.0, // 缓存范围
semanticChildCount: 20, // 语义子控件数量
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'grid_view_count', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
),
),
);
}
}
GridView.builder
GridView.builder 是 Flutter 中一个用于创建具有自定义网格布局的构造函数,通过 SliverGridDelegate 控制网格的布局特性,并通过 IndexedWidgetBuilder 动态生成每个子项。这使得它在处理大数据集时非常有效。
属性解析
GridView.builder({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.shrinkWrap = false, // 是否缩小包裹内容
super.padding, // 内边距
required this.gridDelegate, // 网格代理
required NullableIndexedWidgetBuilder itemBuilder, // 项目构建器
ChildIndexGetter? findChildIndexCallback, // 子项索引查找回调
int? itemCount, // 列表项数量
bool addAutomaticKeepAlives = true, // 是否自动保留活动状态
bool addRepaintBoundaries = true, // 是否添加重绘边界
bool addSemanticIndexes = true, // 是否添加语义索引
super.cacheExtent, // 缓存范围
int? semanticChildCount, // 语义子控件数量
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
})
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry,表示内边距。
- gridDelegate:必需参数,类型为 SliverGridDelegate,用于控制网格的布局特性。
- itemBuilder:必需参数,类型为 NullableIndexedWidgetBuilder,用于构建每个子项。
- findChildIndexCallback:可选参数,类型为 ChildIndexGetter,用于查找子项索引的回调函数。
- itemCount:可选参数,类型为 int?,表示列表项数量。
- addAutomaticKeepAlives:可选参数,类型为 bool,表示是否自动保留活动状态,默认为 true。
- addRepaintBoundaries:可选参数,类型为 bool,表示是否添加重绘边界,默认为 true。
- addSemanticIndexes:可选参数,类型为 bool,表示是否添加语义索引,默认为 true。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- semanticChildCount:可选参数,类型为 int?,表示语义子控件数量。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('GridView.builder Example'),
),
body: GridView.builder(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: true, // 缩小包裹内容
padding: EdgeInsets.all(16.0), // 内边距
gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
crossAxisCount: 5, // 每行有 4 列
mainAxisSpacing: 10.0, // 主轴(垂直)上的间距
crossAxisSpacing: 10.0, // 交叉轴(水平)上的间距
childAspectRatio: 1.0, // 子项宽高比
),
itemBuilder: (context, index) {
// 项目构建器
return Container(
color: Colors.blueAccent,
child: Center(child: Text('Item $index')),
);
},
itemCount: 20, // 列表项数量
cacheExtent: 200.0, // 缓存范围
semanticChildCount: 20, // 语义子控件数量
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'grid_view_builder', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
),
),
);
}
}
GridView.extent
GridView.extent 是 Flutter 中一个用于创建具有最大横轴尺寸约束的网格视图的构造函数。它根据每个子项的最大宽度自动调整网格列数,从而使得网格布局更加灵活。
属性解析
GridView.extent({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.shrinkWrap = false, // 是否缩小包裹内容
super.padding, // 内边距
required double maxCrossAxisExtent, // 最大交叉轴尺寸
double mainAxisSpacing = 0.0, // 主轴(垂直)上的间距
double crossAxisSpacing = 0.0, // 交叉轴(水平)上的间距
double childAspectRatio = 1.0, // 子项宽高比
bool addAutomaticKeepAlives = true, // 是否自动保留活动状态
bool addRepaintBoundaries = true, // 是否添加重绘边界
bool addSemanticIndexes = true, // 是否添加语义索引
super.cacheExtent, // 缓存范围
List<Widget> children = const <Widget>[], // 子组件列表
int? semanticChildCount, // 语义子控件数量
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
})
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry,表示内边距。
- maxCrossAxisExtent:必需参数,类型为 double,表示子项在交叉轴方向上的最大尺寸。
- mainAxisSpacing:可选参数,类型为 double,表示主轴(垂直)上的间距,默认为 0.0。
- crossAxisSpacing:可选参数,类型为 double,表示交叉轴(水平)上的间距,默认为 0.0。
- childAspectRatio:可选参数,类型为 double,表示子项的宽高比,默认为 1.0。
- addAutomaticKeepAlives:可选参数,类型为 bool,表示是否自动保留活动状态,默认为 true。
- addRepaintBoundaries:可选参数,类型为 bool,表示是否添加重绘边界,默认为 true。
- addSemanticIndexes:可选参数,类型为 bool,表示是否添加语义索引,默认为 true。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- children:可选参数,类型为 List,表示子组件列表,默认为空列表。
- semanticChildCount:可选参数,类型为 int?,表示语义子控件数量。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('GridView.extent Example'),
),
body: GridView.extent(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: true, // 缩小包裹内容
padding: EdgeInsets.all(16.0), // 内边距
maxCrossAxisExtent: 150.0, // 子项在交叉轴方向上的最大尺寸
mainAxisSpacing: 10.0, // 主轴(垂直)上的间距
crossAxisSpacing: 10.0, // 交叉轴(水平)上的间距
childAspectRatio: 1.0, // 子项宽高比
children: List.generate(20, (index) {
// 生成 20 个子项
return Container(
color: Colors.blueAccent,
child: Center(child: Text('Item $index')),
);
}),
cacheExtent: 200.0, // 缓存范围
semanticChildCount: 20, // 语义子控件数量
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'grid_view_extent', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
),
),
);
}
}
CustomScrollView:
CustomScrollView 是 Flutter 中一个用于创建具有自定义滚动行为的滚动视图的构造函数。它允许你在其中放置多个 Sliver 小部件,从而实现复杂的滚动效果。
属性解析
const CustomScrollView({
super.key,
super.scrollDirection = Axis.vertical, // 滚动方向,默认垂直
super.reverse = false, // 是否反向滚动
super.controller, // 滚动控制器
super.primary, // 是否是主滚动视图
super.physics, // 滚动物理特性
super.scrollBehavior, // 滚动行为
super.shrinkWrap = false, // 是否缩小包裹内容
super.center, // 定位中心锚点
super.anchor = 0.0, // 锚点位置
super.cacheExtent, // 缓存范围
this.slivers = const <Widget>[], // Sliver小部件列表
super.semanticChildCount, // 语义子控件数量
super.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
super.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
super.restorationId, // 恢复ID
super.clipBehavior = Clip.hardEdge, // 剪切行为
});
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认为垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动,默认为 false。
- controller:可选参数,类型为 ScrollController,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool,表示是否是主滚动视图。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- scrollBehavior:可选参数,类型为 ScrollBehavior,表示滚动行为。
- shrinkWrap:可选参数,类型为 bool,表示是否缩小包裹内容,默认为 false。
- center:可选参数,用于指定滚动视图中间的子项。
- anchor:可选参数,类型为 double,表示锚点位置,默认为 0.0。
- cacheExtent:可选参数,类型为 double,表示缓存范围。
- slivers:必需参数,类型为 List,表示包含的 Sliver 小部件。
- semanticChildCount:可选参数,类型为 int?,表示语义子控件数量。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('CustomScrollView Example'),
),
body: CustomScrollView(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
controller: ScrollController(), // 滚动控制器
// primary: true, // 是主滚动视图
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
shrinkWrap: false, // 不缩小包裹内容
slivers: <Widget>[
SliverAppBar(
pinned: true,
expandedHeight: 200.0,
flexibleSpace: FlexibleSpaceBar(
title: Text('SliverAppBar'),
background: Image.network(
'https://via.placeholder.com/800x400',
fit: BoxFit.cover,
),
),
),
SliverList(
delegate: SliverChildBuilderDelegate(
(BuildContext context, int index) {
return ListTile(
title: Text('Item #$index'),
);
},
childCount: 20, // 列表项数量
),
),
SliverGrid(
gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
crossAxisCount: 2, // 每行有 2 列
mainAxisSpacing: 10.0, // 主轴(垂直)上的间距
crossAxisSpacing: 10.0, // 交叉轴(水平)上的间距
childAspectRatio: 1.0, // 子项宽高比
),
delegate: SliverChildBuilderDelegate(
(BuildContext context, int index) {
return Container(
color: Colors.blue[100 * (index % 9)],
child: Center(child: Text('Grid Item #$index')),
);
},
childCount: 20, // 网格项数量
),
),
],
cacheExtent: 200.0, // 缓存范围
semanticChildCount: 40, // 语义子控件数量
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 键盘隐藏行为
restorationId: 'custom_scroll_view', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
),
),
);
}
}
ListWheelScrollView
ListWheelScrollView 是 Flutter 中一个用于创建类似于旋转木马(carousal)或滚轮选择器(wheel picker)效果的滚动视图的构造函数。它通过将子项以圆环形式排列,实现一种独特的 3D 滚动体验。
属性解析
ListWheelScrollView({
super.key,
this.controller, // 滚动控制器
this.physics, // 滚动物理特性
this.diameterRatio = RenderListWheelViewport.defaultDiameterRatio, // 圆环直径比,默认值
this.perspective = RenderListWheelViewport.defaultPerspective, // 透视度,默认值
this.offAxisFraction = 0.0, // 离轴偏移量
this.useMagnifier = false, // 是否使用放大效果
this.magnification = 1.0, // 放大倍数
this.overAndUnderCenterOpacity = 1.0, // 中心上下方的透明度
required this.itemExtent, // 子项高度
this.squeeze = 1.0, // 挤压系数
this.onSelectedItemChanged, // 选中子项变化时的回调
this.renderChildrenOutsideViewport = false, // 是否渲染视口外的子项
this.clipBehavior = Clip.hardEdge, // 剪切行为
this.restorationId, // 恢复ID
this.scrollBehavior, // 滚动行为
required List<Widget> children, // 子组件列表
});
- key:用于标识控件的唯一值。
- controller:可选参数,类型为 FixedExtentScrollController,用于控制和监听滚动事件。
- physics:可选参数,类型为 ScrollPhysics,表示滚动物理特性,如弹性、惯性等。
- diameterRatio:可选参数,类型为 double,表示圆环直径与视口高度的比例,默认为 2.0。
- perspective:可选参数,类型为 double,表示视角距离,越小越明显透视效果,默认为 0.003。
- offAxisFraction:可选参数,类型为 double,表示离轴偏移量,范围在 -1.0 到 1.0 之间。
- useMagnifier:可选参数,类型为 bool,表示是否使用放大镜效果,默认为 false。
- magnification:可选参数,类型为 double,表示放大倍数,仅当 useMagnifier 为 true 时有效,默认为 1.0。
- overAndUnderCenterOpacity:可选参数,类型为 double,表示中心上下方子项的透明度,默认为 1.0。
- itemExtent:必需参数,类型为 double,表示每个子项的高度。
- squeeze:可选参数,类型为 double,表示子项挤压系数,默认为 1.0。
- onSelectedItemChanged:可选参数,类型为 ValueChanged?,表示选中子项变化时的回调函数。
- renderChildrenOutsideViewport:可选参数,类型为 bool,表示是否渲染视口外的子项,默认为 false。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- scrollBehavior:可选参数,类型为 ScrollBehavior?,表示滚动行为。
- children:必需参数,类型为 List,表示子组件列表。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('ListWheelScrollView Example'),
),
body: Center(
child: ListWheelScrollView(
controller: FixedExtentScrollController(), // 滚动控制器
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
diameterRatio: 2.0, // 圆环直径比
perspective: 0.003, // 透视度
offAxisFraction: 0.0, // 离轴偏移量
useMagnifier: true, // 使用放大效果
magnification: 1.5, // 放大倍数
overAndUnderCenterOpacity: 0.5, // 中心上下方的透明度
itemExtent: 50.0, // 子项高度
squeeze: 1.0, // 挤压系数
onSelectedItemChanged: (int index) {
// 选中子项变化时的回调
print("Selected Item: $index");
},
renderChildrenOutsideViewport: false, // 不渲染视口外的子项
clipBehavior: Clip.hardEdge, // 剪切行为
restorationId: 'list_wheel_scroll_view', // 恢复ID
scrollBehavior:
ScrollConfiguration.of(context).copyWith(dragDevices: {
PointerDeviceKind.touch,
PointerDeviceKind.mouse,
}), // 滚动行为
children: List<Widget>.generate(20, (index) {
return Container(
alignment: Alignment.center,
color: Colors.blue[100 * (index % 9)],
child: Text('Item #$index'),
);
}),
),
),
),
);
}
}
SingleChildScrollView
SingleChildScrollView 是 Flutter 中一个用于在有限空间内滚动显示单个子项的滚动视图。它适用于内容量较大且不能一次完全展示在屏幕上的情况。
属性解析
const SingleChildScrollView({
super.key,
this.scrollDirection = Axis.vertical, // 滚动方向,默认垂直方向
this.reverse = false, // 是否反向滚动
this.padding, // 内边距
this.primary, // 是否使用主滚动控制器
this.physics, // 滚动物理特性
this.controller, // 滚动控制器
this.child, // 子组件
this.dragStartBehavior = DragStartBehavior.start,// 拖拽开始行为
this.clipBehavior = Clip.hardEdge, // 剪切行为
this.restorationId, // 恢复ID
this.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
});
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动,默认为 false。
- padding:可选参数,类型为 EdgeInsetsGeometry?,表示内边距。
- primary:可选参数,类型为 bool?,表示是否使用主滚动控制器。
- physics:可选参数,类型为 ScrollPhysics?,表示滚动物理特性,如弹性、惯性等。
- controller:可选参数,类型为 ScrollController?,用于控制和监听滚动事件。
- child:可选参数,类型为 Widget?,表示要滚动的子组件。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示键盘隐藏行为,默认为 ScrollViewKeyboardDismissBehavior.manual。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('SingleChildScrollView Example'),
),
body: SingleChildScrollView(
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
padding: EdgeInsets.all(16.0), // 内边距
// primary: true, // 使用主滚动控制器
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
controller: ScrollController(), // 滚动控制器
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
clipBehavior: Clip.hardEdge, // 剪切行为
restorationId: 'single_child_scroll_view', // 恢复ID
keyboardDismissBehavior:
ScrollViewKeyboardDismissBehavior.onDrag, // 拖动时隐藏键盘
child: Column(
children: List<Widget>.generate(20, (index) {
return Container(
margin: EdgeInsets.symmetric(vertical: 8.0),
color: Colors.blue[100 * (index % 9)],
height: 100.0,
alignment: Alignment.center,
child: Text('Item #$index'),
);
}),
),
),
),
);
}
}
PageView
PageView 是 Flutter 中一个用于创建分页视图的控件,允许用户通过滑动来在不同页面之间切换。它通常用于实现类似于幻灯片或分页导航的效果。
属性解析
PageView({
super.key,
this.scrollDirection = Axis.horizontal, // 滚动方向,默认水平方向
this.reverse = false, // 是否反向滚动
PageController? controller, // 分页控制器
this.physics, // 滚动物理特性
this.pageSnapping = true, // 是否自动对齐到最近的页面
this.onPageChanged, // 页面改变时的回调
List<Widget> children = const <Widget>[], // 子组件列表
this.dragStartBehavior = DragStartBehavior.start,// 拖拽开始行为
this.allowImplicitScrolling = false, // 是否允许隐式滚动
this.restorationId, // 恢复ID
this.clipBehavior = Clip.hardEdge, // 剪切行为
this.scrollBehavior, // 滚动行为
this.padEnds = true, // 是否填充两端空白
});
- key:用于标识控件的唯一值。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认水平方向 (Axis.horizontal)。
- reverse:可选参数,类型为 bool,表示是否反向滚动,默认为 false。
- controller:可选参数,类型为 PageController?,用于控制和监听页面滚动事件。
- physics:可选参数,类型为 ScrollPhysics?,表示滚动物理特性,如弹性、惯性等。
- pageSnapping:可选参数,类型为 bool,表示是否自动对齐到最近的页面,默认为 true。
- onPageChanged:可选参数,类型为 ValueChanged?,表示页面改变时的回调函数。
- children:可选参数,类型为 List,表示子组件列表,默认为空列表。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- allowImplicitScrolling:可选参数,类型为 bool,表示是否允许隐式滚动,默认为 false。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
- scrollBehavior:可选参数,类型为 ScrollBehavior?,表示滚动行为。
- padEnds:可选参数,类型为 bool,表示是否填充两端空白,默认为 true。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('PageView Example'),
),
body: PageView(
scrollDirection: Axis.horizontal, // 滚动方向:水平
reverse: false, // 不反向滚动
controller: PageController(), // 分页控制器
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
pageSnapping: true, // 自动对齐到最近的页面
onPageChanged: (int index) {
// 页面改变时的回调
print("Current Page: $index");
},
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
allowImplicitScrolling: false, // 不允许隐式滚动
restorationId: 'page_view', // 恢复ID
clipBehavior: Clip.hardEdge, // 剪切行为
scrollBehavior:
ScrollConfiguration.of(context).copyWith(dragDevices: {
PointerDeviceKind.touch,
PointerDeviceKind.mouse,
}), // 滚动行为
padEnds: true, // 填充两端空白
children: <Widget>[
Container(
color: Colors.red,
child: Center(child: Text('Page 1')),
),
Container(
color: Colors.green,
child: Center(child: Text('Page 2')),
),
Container(
color: Colors.blue,
child: Center(child: Text('Page 3')),
),
],
),
),
);
}
}
NestedScrollView
NestedScrollView 是 Flutter 中一个用于嵌套滚动的控件,通常用于实现带有固定或浮动头部的复杂滚动布局。它允许在一个视图中同时包含 Sliver 组件和普通组件,并处理它们之间的滚动协调。
属性解析
const NestedScrollView({
super.key,
this.controller, // 滚动控制器
this.scrollDirection = Axis.vertical, // 滚动方向,默认垂直方向
this.reverse = false, // 是否反向滚动
this.physics, // 滚动物理特性
required this.headerSliverBuilder, // 构建头部 Sliver 的回调
required this.body, // 主体部分
this.dragStartBehavior = DragStartBehavior.start,// 拖拽开始行为
this.floatHeaderSlivers = false, // 是否让 header Sliver 浮动
this.clipBehavior = Clip.hardEdge, // 剪切行为
this.restorationId, // 恢复ID
this.scrollBehavior, // 滚动行为
});
- key:用于标识控件的唯一值。
- controller:可选参数,类型为 ScrollController?,用于控制和监听滚动事件。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认垂直方向 (Axis.vertical)。
- reverse:可选参数,类型为 bool,表示是否反向滚动,默认为 false。
- physics:可选参数,类型为 ScrollPhysics?,表示滚动物理特性,如弹性、惯性等。
- headerSliverBuilder:必需参数,类型为 NestedScrollViewHeaderSliversBuilder,用于构建头部 Sliver 组件的回调函数。
- body:必需参数,类型为 Widget,表示主体部分的内容。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖拽开始行为,默认为 DragStartBehavior.start。
- floatHeaderSlivers:可选参数,类型为 bool,表示是否让头部 Sliver 浮动,默认为 false。
- clipBehavior:可选参数,类型为 Clip,表示剪切行为,默认为 Clip.hardEdge。
- restorationId:可选参数,类型为 String?,表示恢复ID。
- scrollBehavior:可选参数,类型为 ScrollBehavior?,表示滚动行为。
示例
class ExamplePage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
body: NestedScrollView(
controller: ScrollController(), // 滚动控制器
scrollDirection: Axis.vertical, // 滚动方向:垂直
reverse: false, // 不反向滚动
physics: BouncingScrollPhysics(), // 弹性滚动物理特性
dragStartBehavior: DragStartBehavior.start, // 拖拽开始行为
floatHeaderSlivers: true, // 让 header Sliver 浮动
clipBehavior: Clip.hardEdge, // 剪切行为
restorationId: 'nested_scroll_view', // 恢复ID
scrollBehavior:
ScrollConfiguration.of(context).copyWith(dragDevices: {
PointerDeviceKind.touch,
PointerDeviceKind.mouse,
}), // 滚动行为
headerSliverBuilder: (BuildContext context, bool innerBoxIsScrolled) {
return <Widget>[
SliverAppBar(
expandedHeight: 200.0,
floating: true,
pinned: true,
flexibleSpace: FlexibleSpaceBar(
title: Text('NestedScrollView Example'),
background: Image.network(
'https://via.placeholder.com/350x150',
fit: BoxFit.cover,
),
),
),
];
},
body: ListView.builder(
padding: EdgeInsets.all(8.0),
itemCount: 30,
itemBuilder: (context, index) {
return Container(
margin: EdgeInsets.symmetric(vertical: 8.0),
color: Colors.blue[100 * ((index % 9) + 1)],
height: 100.0,
alignment: Alignment.center,
child: Text('Item #$index'),
);
},
),
),
),
);
}
}
这个示例展示了如何使用 NestedScrollView 来构建一个具有复杂滚动布局的视图,其中包括一个浮动的头部和一个可以滚动的主体部分。
Scrollbar
Scrollbar 是 Flutter 中用于在滚动视图上显示滚动条的控件,提供了视觉反馈以指示当前滚动位置。它可以与任何可滚动的子组件一起使用,如 ListView、GridView 等。
属性解析
const Scrollbar({
super.key,
required this.child, // 必需参数,用于包裹的子组件
this.controller, // 滚动控制器
this.thumbVisibility, // 是否显示滑块
this.trackVisibility, // 是否显示轨道
this.thickness, // 滑块厚度
this.radius, // 滑块圆角半径
this.notificationPredicate, // 通知谓词
this.interactive, // 是否可交互
this.scrollbarOrientation, // 滚动条方向
@Deprecated(
'Use ScrollbarThemeData.trackVisibility to resolve based on the current state instead. '
'This feature was deprecated after v3.4.0-19.0.pre.',
)
this.showTrackOnHover, // 悬停时是否显示轨道
});
- key:用于标识控件的唯一值。
- child:必需参数,类型为 Widget,表示要包裹的子组件。
- controller:可选参数,类型为 ScrollController?,用于控制和监听滚动事件。
- thumbVisibility:可选参数,类型为 bool?,表示是否一直显示滑块。
- trackVisibility:可选参数,类型为 bool?,表示是否一直显示轨道。
- thickness:可选参数,类型为 double?,表示滑块的厚度。
- radius:可选参数,类型为 Radius?,表示滑块的圆角半径。
- notificationPredicate:可选参数,类型为 ScrollNotificationPredicate,表示哪些滚动通知应该被处理,默认为 defaultScrollNotificationPredicate。
- interactive:可选参数,类型为 bool?,表示滚动条是否可交互,默认为 true。
- scrollbarOrientation:可选参数,类型为 ScrollbarOrientation?,表示滚动条的方向(水平或垂直)。
- showTrackOnHover:可选参数,类型为 bool?,表示悬停时是否显示轨道,此属性已被弃用,建议使用 ScrollbarThemeData.trackVisibility。
示例
class ExamplePage extends StatelessWidget {
final ScrollController _scrollController = ScrollController();
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('Scrollbar Example'),
),
body: Scrollbar(
controller: _scrollController, // 滚动控制器
thumbVisibility: true, // 始终显示滑块
trackVisibility: true, // 始终显示轨道
thickness: 8.0, // 滑块厚度
radius: Radius.circular(10.0), // 滑块圆角半径
interactive: true, // 滚动条可交互
scrollbarOrientation: ScrollbarOrientation.right, // 滚动条方向
child: ListView.builder(
controller: _scrollController,
padding: EdgeInsets.all(8.0),
itemCount: 30,
itemBuilder: (context, index) {
return Container(
margin: EdgeInsets.symmetric(vertical: 8.0),
color: Colors.blue[100 * ((index % 9) + 1)],
height: 100.0,
alignment: Alignment.center,
child: Text('Item #$index'),
);
},
),
),
),
);
}
}
DraggableScrollableSheet
DraggableScrollableSheet 是 Flutter 中一个可拖动滚动的控件,通常用于创建可拖动的底部面板。它允许用户通过拖动来调整其大小,从而显示和隐藏更多内容。
属性解析
const DraggableScrollableSheet({
super.key,
this.initialChildSize = 0.5, // 初始子组件大小
this.minChildSize = 0.25, // 最小子组件大小
this.maxChildSize = 1.0, // 最大子组件大小
this.expand = true, // 是否扩展以填满父级
this.snap = false, // 是否启用对齐
this.snapSizes, // 对齐尺寸
this.snapAnimationDuration, // 对齐动画持续时间
this.controller, // 控制器
this.shouldCloseOnMinExtent = true, // 最小时是否关闭
required this.builder, // 必需参数,构建子组件
});
- key:用于标识控件的唯一值。
- initialChildSize:可选参数,类型为 double,表示初始子组件占据的父组件高度比例,默认值为 0.5。
- minChildSize:可选参数,类型为 double,表示子组件占据的最小父组件高度比例,默认值为 0.25。
- maxChildSize:可选参数,类型为 double,表示子组件占据的最大父组件高度比例,默认值为 1.0。
- expand:可选参数,类型为 bool,表示子组件是否扩展以填满父组件,默认值为 true。
- snap:可选参数,类型为 bool,表示是否启用对齐功能,默认值为 false。
- snapSizes:可选参数,类型为 List?,表示启用对齐时的对齐尺寸列表。
- snapAnimationDuration:可选参数,类型为 Duration?,表示对齐动画的持续时间。
- controller:可选参数,类型为 DraggableScrollableController?,用于控制和监听拖动事件。
- shouldCloseOnMinExtent:可选参数,类型为 bool,表示是否在达到最小尺寸时关闭面板,默认值为 true。
- builder:必需参数,类型为 Widget Function(BuildContext, ScrollController),用于构建子组件。
示例
class ExamplePage extends StatelessWidget {
final ScrollController _scrollController = ScrollController();
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('DraggableScrollableSheet Example'),
),
body: Stack(
children: <Widget>[
Center(
child: Text('Main Content'),
),
DraggableScrollableSheet(
initialChildSize: 0.3, // 初始子组件大小
minChildSize: 0.1, // 最小子组件大小
maxChildSize: 0.8, // 最大子组件大小
expand: false, // 不扩展以填满父级
snap: true, // 启用对齐
snapSizes: [0.3, 0.6, 0.8], // 对齐尺寸
snapAnimationDuration: Duration(milliseconds: 200), // 对齐动画持续时间
builder:
(BuildContext context, ScrollController scrollController) {
return Container(
color: Colors.blue[100],
child: ListView.builder(
controller: scrollController,
itemCount: 30,
itemBuilder: (BuildContext context, int index) {
return ListTile(
title: Text('Item #$index'),
);
},
),
);
},
),
],
),
),
);
}
}
ScrollController
ScrollController 是一个用于控制和监听滚动视图(如 ListView、GridView 和 CustomScrollView 等)的控件。在Flutter中,ScrollController为开发者提供了丰富的API来控制滚动视图的行为。
属性解析
ScrollController({
this.initialScrollOffset = 0.0, // 初始滚动偏移量
this.keepScrollOffset = true, // 是否保持滚动偏移量
this.debugLabel, // 调试标签
this.onAttach, // 附加回调
this.onDetach, // 分离回调
});
- initialScrollOffset:可选参数,类型为 double,表示初始滚动偏移量,默认值为 0.0。
- keepScrollOffset:可选参数,类型为 bool,表示是否在控件重新创建时保持滚动偏移量,默认值为 true。
- debugLabel:可选参数,类型为 String?,用于调试目的的标签。
- onAttach:可选参数,类型为 VoidCallback?,当控制器被附加到一个滚动视图时调用的回调。
- onDetach:可选参数,类型为 VoidCallback?,当控制器从一个滚动视图分离时调用的回调。
示例
class ScrollControllerExample extends StatefulWidget {
@override
_ScrollControllerExampleState createState() =>
_ScrollControllerExampleState();
}
class _ScrollControllerExampleState extends State<ScrollControllerExample> {
final ScrollController _controller = ScrollController();
@override
void initState() {
super.initState();
_controller.addListener(() {
print("Scroll Position: ${_controller.position.pixels}");
});
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
void _scrollToTop() {
_controller.animateTo(
0.0,
duration: Duration(seconds: 2),
curve: Curves.easeInOut,
);
}
void _scrollToEnd() {
_controller.animateTo(
_controller.position.maxScrollExtent,
duration: Duration(seconds: 2),
curve: Curves.easeInOut,
);
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text("ScrollController Example")),
body: Column(
children: [
Expanded(
child: ListView.builder(
controller: _controller,
itemCount: 50,
itemBuilder: (context, index) {
return ListTile(title: Text("Item $index"));
},
),
),
Row(
mainAxisAlignment: MainAxisAlignment.spaceAround,
children: [
ElevatedButton(
onPressed: _scrollToTop,
child: Text('Scroll to Top'),
),
ElevatedButton(
onPressed: _scrollToEnd,
child: Text('Scroll to End'),
),
],
),
],
),
);
}
}
使用 ScrollController 进行同步滚动
有时你可能需要在多个滚动视图之间实现同步滚动,这可以通过共享一个 ScrollController 实现。
class SynchronizedScrollExample extends StatefulWidget {
@override
_SynchronizedScrollExampleState createState() =>
_SynchronizedScrollExampleState();
}
class _SynchronizedScrollExampleState extends State<SynchronizedScrollExample> {
final ScrollController _controller1 = ScrollController();
final ScrollController _controller2 = ScrollController();
@override
void initState() {
super.initState();
_controller1.addListener(() {
if (_controller1.offset != _controller2.offset) {
_controller2.jumpTo(_controller1.offset);
}
});
_controller2.addListener(() {
if (_controller2.offset != _controller1.offset) {
_controller1.jumpTo(_controller2.offset);
}
});
}
@override
void dispose() {
_controller1.dispose();
_controller2.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text("Synchronized Scroll Example")),
body: Row(
children: [
Expanded(
child: ListView.builder(
controller: _controller1,
itemCount: 50,
itemBuilder: (context, index) {
return ListTile(title: Text("List 1 - Item $index"));
},
),
),
Expanded(
child: ListView.builder(
controller: _controller2,
itemCount: 50,
itemBuilder: (context, index) {
return ListTile(title: Text("List 2 - Item $index"));
},
),
),
],
),
);
}
}
RefreshIndicator
RefreshIndicator 是 Flutter 中用于实现下拉刷新功能的控件。它通常用在包含可滚动子组件(如 ListView 或 GridView)的场景中,允许用户通过下拉动作触发刷新操作。
属性解析
const RefreshIndicator({
super.key,
required this.child, // 必需参数,用于包裹的子组件
this.displacement = 40.0, // 刷新指示器下移距离
this.edgeOffset = 0.0, // 刷新指示器起始位置
required this.onRefresh, // 必需参数,下拉时触发的刷新回调
this.color, // 指示器颜色
this.backgroundColor, // 指示器背景色
this.notificationPredicate = defaultScrollNotificationPredicate, // 通知谓词
this.semanticsLabel, // 语义标签
this.semanticsValue, // 语义值
this.strokeWidth = RefreshProgressIndicator.defaultStrokeWidth, // 指示器线条粗细
this.triggerMode = RefreshIndicatorTriggerMode.onEdge, // 触发模式
});
- key:用于标识控件的唯一值。
- child:必需参数,类型为 Widget,表示要包裹的可滚动子组件。
- displacement:可选参数,类型为 double,表示刷新指示器下移的距离,默认值为 40.0。
- edgeOffset:可选参数,类型为 double,表示刷新指示器的起始位置,默认值为 0.0(即列表顶部)。
- onRefresh:必需参数,类型为 Future Function(),表示下拉时触发的异步刷新回调。
- color:可选参数,类型为 Color?,表示指示器的颜色。
- backgroundColor:可选参数,类型为 Color?,表示指示器的背景色。
- notificationPredicate:可选参数,类型为 ScrollNotificationPredicate,表示哪些滚动通知应该被处理,默认为 defaultScrollNotificationPredicate。
- semanticsLabel:可选参数,类型为 String?,表示用于辅助功能的语义标签。
- semanticsValue:可选参数,类型为 String?,表示用于辅助功能的语义值。
- strokeWidth:可选参数,类型为 double,表示指示器线条的粗细,默认值为 RefreshProgressIndicator.defaultStrokeWidth。
- triggerMode:可选参数,类型为 RefreshIndicatorTriggerMode,表示触发刷新的模式,默认值为 RefreshIndicatorTriggerMode.onEdge。
示例
class ExamplePage extends StatelessWidget {
final ScrollController _scrollController = ScrollController();
@override
Widget build(BuildContext context) {
return MaterialApp(
debugShowCheckedModeBanner: false,
home: Scaffold(
appBar: AppBar(
title: Text('RefreshIndicator Example'),
),
body: RefreshIndicator(
onRefresh: _handleRefresh, // 下拉时触发的刷新回调
displacement: 50.0, // 刷新指示器下移距离
edgeOffset: 10.0, // 刷新指示器起始位置
color: Colors.white, // 指示器颜色
backgroundColor: Colors.blue, // 指示器背景色
strokeWidth: 3.0, // 指示器线条粗细
triggerMode: RefreshIndicatorTriggerMode.anywhere, // 触发模式
child: ListView.builder(
padding: EdgeInsets.all(8.0),
itemCount: 30,
itemBuilder: (BuildContext context, int index) {
return Container(
margin: EdgeInsets.symmetric(vertical: 8.0),
color: Colors.blue[100 * ((index % 9) + 1)],
height: 100.0,
alignment: Alignment.center,
child: Text('Item #$index'),
);
},
),
),
),
);
}
Future<void> _handleRefresh() async {
await Future.delayed(Duration(seconds: 2)); // 模拟耗时操作,如网络请求
}
}
ReorderableListView
ReorderableListView 是 Flutter 中用于创建可拖动重新排序的列表视图。它允许用户通过拖动操作来改变子组件的位置,从而实现重新排序的效果。
属性解析
ReorderableListView({
super.key,
required List<Widget> children, // 必需参数,子组件列表
required this.onReorder, // 必需参数,重新排序回调
this.onReorderStart, // 开始重新排序回调
this.onReorderEnd, // 结束重新排序回调
this.itemExtent, // 子组件高度
this.itemExtentBuilder, // 子组件高度生成器
this.prototypeItem, // 原型子组件
this.proxyDecorator, // 拖动代理装饰器
this.buildDefaultDragHandles = true, // 是否构建默认拖动句柄
this.padding, // 内边距
this.header, // 列表头部组件
this.footer, // 列表尾部组件
this.scrollDirection = Axis.vertical, // 滚动方向
this.reverse = false, // 是否反向滚动
this.scrollController, // 滚动控制器
this.primary, // 是否使用主滚动视图
this.physics, // 滚动物理特性
this.shrinkWrap = false, // 是否包裹内容
this.anchor = 0.0, // 锚点
this.cacheExtent, // 缓存范围
this.dragStartBehavior = DragStartBehavior.start, // 拖动起始行为
this.keyboardDismissBehavior = ScrollViewKeyboardDismissBehavior.manual, // 键盘隐藏行为
this.restorationId, // 恢复ID
this.clipBehavior = Clip.hardEdge, // 剪裁行为
this.autoScrollerVelocityScalar, // 自动滚动速度标量
});
- key:用于标识控件的唯一值。
- children:必需参数,类型为 List,表示列表中的子组件。
- onReorder:必需参数,类型为 void Function(int oldIndex, int newIndex),重新排序时触发的回调函数。
- onReorderStart:可选参数,类型为 void Function(int index)?,开始重新排序时触发的回调函数。
- onReorderEnd:可选参数,类型为 void Function(int index)?,结束重新排序时触发的回调函数。
- itemExtent:可选参数,类型为 double?,设置每个子组件的高度。
- itemExtentBuilder:可选参数,类型为 NullableIndexed?,根据索引动态生成子组件高度。
- prototypeItem:可选参数,类型为 Widget?,用于确定子组件高度的原型子组件。
- proxyDecorator:可选参数,类型为 ReorderItemProxyDecorator?,用于自定义拖动代理的外观。
- buildDefaultDragHandles:可选参数,类型为 bool,表示是否构建默认拖动句柄,默认值为 true。
- padding:可选参数,类型为 EdgeInsetsGeometry?,表示内边距。
- header:可选参数,类型为 Widget?,表示列表头部组件。
- footer:可选参数,类型为 Widget?,表示列表尾部组件。
- scrollDirection:可选参数,类型为 Axis,表示滚动方向,默认值为 Axis.vertical。
- reverse:可选参数,类型为 bool,表示是否反向滚动,默认值为 false。
- scrollController:可选参数,类型为 ScrollController?,用于控制和监听滚动事件。
- primary:可选参数,类型为 bool?,表示是否使用主滚动视图。
- physics:可选参数,类型为 ScrollPhysics?,表示滚动的物理特性。
- shrinkWrap:可选参数,类型为 bool,表示是否根据子组件大小调整自身大小,默认值为 false。
- anchor:可选参数,类型为 double,表示锚点位置,默认值为 0.0。
- cacheExtent:可选参数,类型为 double?,表示缓存范围。
- dragStartBehavior:可选参数,类型为 DragStartBehavior,表示拖动起始行为,默认值为 DragStartBehavior.start。
- keyboardDismissBehavior:可选参数,类型为 ScrollViewKeyboardDismissBehavior,表示滚动时键盘的隐藏行为,默认值为 ScrollViewKeyboardDismissBehavior.manual。
- restorationId:可选参数,类型为 String?,用于状态恢复的 ID。
- clipBehavior:可选参数,类型为 Clip,表示剪裁行为,默认值为 Clip.hardEdge。
- autoScrollerVelocityScalar:可选参数,类型为 double?,表示自动滚动速度标量。
示例
class ReorderablePage extends StatefulWidget {
@override
_ReorderablePageState createState() => _ReorderablePageState();
}
class _ReorderablePageState extends State<ReorderablePage> {
final List<String> items = List.generate(10, (index) => 'Item #$index');
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(
title: Text('ReorderableListView Example'),
),
body: ReorderableListView(
padding: EdgeInsets.all(8.0), // 内边距
children: List.generate(items.length, (index) {
return ListTile(
key: ValueKey(items[index]),
title: Text(items[index]),
);
}),
onReorder: (int oldIndex, int newIndex) {
setState(() {
if (oldIndex < newIndex) {
newIndex -= 1;
}
final String item = items.removeAt(oldIndex);
items.insert(newIndex, item);
});
},
onReorderStart: (int index) {
print('Started reordering at $index');
},
onReorderEnd: (int index) {
print('Finished reordering at $index');
},
scrollDirection: Axis.vertical, // 滚动方向
reverse: false, // 不反向滚动
scrollController: ScrollController(), // 滚动控制器
physics: BouncingScrollPhysics(), // 滚动物理特性
shrinkWrap: true, // 根据子组件大小调整自身大小
header: Container(
padding: EdgeInsets.all(16.0),
color: Colors.blue[100],
child: Text('Header', style: TextStyle(fontSize: 20)),
),
footer: Container(
padding: EdgeInsets.all(16.0),
color: Colors.blue[100],
child: Text('Footer', style: TextStyle(fontSize: 20)),
),
),
),
);
}
}
功能增强控件
Scrollable: 最基础的滚动控件,可以包含一个可滚动的子组件。
Scrollbar: 为可滚动组件添加滚动条。
RefreshIndicator: 下拉刷新组件,用于实现下拉刷新功能。
SliverAppBar: 可以滚动和折叠的应用栏,通常与 CustomScrollView 一起使用。
NestedScrollView: 支持嵌套滚动的视图。
NotificationListener: 监听子组件发送的通知事件。