Adds doc example for Listview and pageview (#36391)
diff --git a/packages/flutter/lib/src/widgets/page_view.dart b/packages/flutter/lib/src/widgets/page_view.dart index bb61340..285879a 100644 --- a/packages/flutter/lib/src/widgets/page_view.dart +++ b/packages/flutter/lib/src/widgets/page_view.dart
@@ -562,6 +562,10 @@ /// /// [itemBuilder] will be called only with indices greater than or equal to /// zero and less than [itemCount]. + /// + /// [PageView.builder] by default does not support child reordering. If + /// you are planning to change child order at a later time, consider using + /// [PageView] or [PageView.custom]. PageView.builder({ Key key, this.scrollDirection = Axis.horizontal, @@ -579,6 +583,84 @@ /// Creates a scrollable list that works page by page with a custom child /// model. + /// + /// {@tool sample} + /// + /// This [PageView] uses a custom [SliverChildBuilderDelegate] to support child + /// reordering. + /// + /// ```dart + /// class MyPageView extends StatefulWidget { + /// @override + /// _MyPageViewState createState() => _MyPageViewState(); + /// } + /// + /// class _MyPageViewState extends State<MyPageView> { + /// List<String> items = <String>['1', '2', '3', '4', '5']; + /// + /// void _reverse() { + /// setState(() { + /// items = items.reversed.toList(); + /// }); + /// } + /// + /// @override + /// Widget build(BuildContext context) { + /// return Scaffold( + /// body: SafeArea( + /// child: PageView.custom( + /// childrenDelegate: SliverChildBuilderDelegate( + /// (BuildContext context, int index) { + /// return KeepAlive( + /// data: items[index], + /// key: ValueKey<String>(items[index]), + /// ); + /// }, + /// childCount: items.length, + /// findChildIndexCallback: (Key key) { + /// final ValueKey valueKey = key; + /// final String data = valueKey.value; + /// return items.indexOf(data); + /// } + /// ), + /// ), + /// ), + /// bottomNavigationBar: BottomAppBar( + /// child: Row( + /// mainAxisAlignment: MainAxisAlignment.center, + /// children: <Widget>[ + /// FlatButton( + /// onPressed: () => _reverse(), + /// child: Text('Reverse items'), + /// ), + /// ], + /// ), + /// ), + /// ); + /// } + /// } + /// + /// class KeepAlive extends StatefulWidget { + /// const KeepAlive({Key key, this.data}) : super(key: key); + /// + /// final String data; + /// + /// @override + /// _KeepAliveState createState() => _KeepAliveState(); + /// } + /// + /// class _KeepAliveState extends State<KeepAlive> with AutomaticKeepAliveClientMixin{ + /// @override + /// bool get wantKeepAlive => true; + /// + /// @override + /// Widget build(BuildContext context) { + /// super.build(context); + /// return Text(widget.data); + /// } + /// } + /// ``` + /// {@end-tool} PageView.custom({ Key key, this.scrollDirection = Axis.horizontal,
diff --git a/packages/flutter/lib/src/widgets/scroll_view.dart b/packages/flutter/lib/src/widgets/scroll_view.dart index 2ab40d5..c1b2897 100644 --- a/packages/flutter/lib/src/widgets/scroll_view.dart +++ b/packages/flutter/lib/src/widgets/scroll_view.dart
@@ -917,6 +917,10 @@ /// `addSemanticIndexes` argument corresponds to the /// [SliverChildBuilderDelegate.addSemanticIndexes] property. None may be /// null. + /// + /// [ListView.builder] by default does not support child reordering. If + /// you are planning to change child order at a later time, consider using + /// [ListView] or [ListView.custom]. ListView.builder({ Key key, Axis scrollDirection = Axis.vertical, @@ -1065,6 +1069,84 @@ /// /// For example, a custom child model can control the algorithm used to /// estimate the size of children that are not actually visible. + /// + /// {@tool sample} + /// + /// This [ListView] uses a custom [SliverChildBuilderDelegate] to support child + /// reordering. + /// + /// ```dart + /// class MyListView extends StatefulWidget { + /// @override + /// _MyListViewState createState() => _MyListViewState(); + /// } + /// + /// class _MyListViewState extends State<MyListView> { + /// List<String> items = <String>['1', '2', '3', '4', '5']; + /// + /// void _reverse() { + /// setState(() { + /// items = items.reversed.toList(); + /// }); + /// } + /// + /// @override + /// Widget build(BuildContext context) { + /// return Scaffold( + /// body: SafeArea( + /// child: ListView.custom( + /// childrenDelegate: SliverChildBuilderDelegate( + /// (BuildContext context, int index) { + /// return KeepAlive( + /// data: items[index], + /// key: ValueKey<String>(items[index]), + /// ); + /// }, + /// childCount: items.length, + /// findChildIndexCallback: (Key key) { + /// final ValueKey valueKey = key; + /// final String data = valueKey.value; + /// return items.indexOf(data); + /// } + /// ), + /// ), + /// ), + /// bottomNavigationBar: BottomAppBar( + /// child: Row( + /// mainAxisAlignment: MainAxisAlignment.center, + /// children: <Widget>[ + /// FlatButton( + /// onPressed: () => _reverse(), + /// child: Text('Reverse items'), + /// ), + /// ], + /// ), + /// ), + /// ); + /// } + /// } + /// + /// class KeepAlive extends StatefulWidget { + /// const KeepAlive({Key key, this.data}) : super(key: key); + /// + /// final String data; + /// + /// @override + /// _KeepAliveState createState() => _KeepAliveState(); + /// } + /// + /// class _KeepAliveState extends State<KeepAlive> with AutomaticKeepAliveClientMixin{ + /// @override + /// bool get wantKeepAlive => true; + /// + /// @override + /// Widget build(BuildContext context) { + /// super.build(context); + /// return Text(widget.data); + /// } + /// } + /// ``` + /// {@end-tool} const ListView.custom({ Key key, Axis scrollDirection = Axis.vertical,