|
| 1 | +# jk_custom_appbar |
| 2 | + |
| 3 | +Easy to use any custom widget as app bar / bottom bar. Support floating / pinned bars with scrolling behavior. Support in horizontal screen. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- Support bottom bar / app bar. |
| 8 | +- Use any custom widget as app bar / bottom bar. |
| 9 | +- Support reverse scrolling. |
| 10 | +- Support image background in app bar. |
| 11 | +- Support in horizontal mode. |
| 12 | + |
| 13 | +# Quick Start |
| 14 | + |
| 15 | +## Installation |
| 16 | + |
| 17 | +Add this to your package's `pubspec.yaml` file: |
| 18 | + |
| 19 | +```yaml |
| 20 | +dependencies: |
| 21 | + jk_custom_appbar: ^1.0.0 |
| 22 | +``` |
| 23 | +
|
| 24 | +# Usage |
| 25 | +
|
| 26 | +## Custom app bar / bottom bar |
| 27 | +
|
| 28 | +Both `appBar` and `bottomBar` can be expanded / collapsed during scrolling. |
| 29 | + |
| 30 | +But `appBarPinned` and `bottomBarPinned` will not be expanded / collapsed during scrolling, and always shown on screen. |
| 31 | + |
| 32 | +All these bars can be `null` (not shown) or put any your custom widget. |
| 33 | + |
| 34 | +``` |
| 35 | +var layout = JkAppBarLayout( |
| 36 | + appBar: Text("custom appBar widget here"), // optional |
| 37 | + appBarPinned: Text("custom appBarPinned widget here"), // optional |
| 38 | + bottomBar: Text("custom bottomBar widget here"), // optional |
| 39 | + bottomBarPinned: Text("custom bottomBarPinned widget here"), // optional |
| 40 | +); |
| 41 | +``` |
| 42 | +
|
| 43 | +## Show ListView / GridView as content (Important !) |
| 44 | +
|
| 45 | +To show a ListView / GridView / SingleChildScrollView as content, we need to use `JkAppBarListView` / `JkAppBarGridView` / `JkAppBarSingleChildScrollView`. |
| 46 | +
|
| 47 | +The API of all the new three classes are all the same with flutter official classes, but only the class name changes. |
| 48 | +
|
| 49 | +NOTE: use flutter official ListView / GridView / SingleChildScrollView won't make app bars expand/collapse. |
| 50 | +
|
| 51 | +``` |
| 52 | +var layout = JkAppBarLayout( |
| 53 | + ... |
| 54 | + child: JkAppBarListView.builder( // API are the same with ListView |
| 55 | + itemCount: 300, |
| 56 | + itemBuilder: (context, index) => Text("List Item $index"), |
| 57 | + ), |
| 58 | +); |
| 59 | +``` |
| 60 | +
|
| 61 | +``` |
| 62 | +var layout = JkAppBarLayout( |
| 63 | + ... |
| 64 | + child: JkAppBarGridView.builder( // API are the same with GridView |
| 65 | + itemCount: 300, |
| 66 | + gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount( |
| 67 | + crossAxisCount: 2, mainAxisExtent: 30), |
| 68 | + itemCount: 300, |
| 69 | + itemBuilder: (context, index) => Text("Grid Item $index"), |
| 70 | + ), |
| 71 | +); |
| 72 | +``` |
| 73 | +
|
| 74 | +``` |
| 75 | +var layout = JkAppBarLayout( |
| 76 | + ... |
| 77 | + child: JkAppBarSingleChildScrollView.builder( // API are the same with SingleChildScrollView |
| 78 | + child: Column( |
| 79 | + children: List.generate(100, (index) => Text("Column $index")), |
| 80 | + ), |
| 81 | + ), |
| 82 | +); |
| 83 | +``` |
| 84 | +
|
| 85 | +## Snapping & Floating |
| 86 | +
|
| 87 | +`floating`=true means the `appBar` and `bottomBar` will be expanded anywhere when scrolling backward. |
| 88 | +
|
| 89 | +`floating`=false means the `appBar` and `bottomBar` ONLY be expanded anywhere when scrolling back to beginning of list. |
| 90 | +
|
| 91 | +`snap`=true means the `appBar` and `bottomBar` will be automatically expanded/collapseed when tapUp if bars not fully expanded/collapsed. |
| 92 | +
|
| 93 | +``` |
| 94 | +var layout = JkAppBarLayout( |
| 95 | + ... |
| 96 | + floating: true, |
| 97 | + snap: true, |
| 98 | +); |
| 99 | +``` |
| 100 | +
|
| 101 | +## Image background |
| 102 | +
|
| 103 | +Return an Image widget in `appBarBackgroundBuilder` to show an image as background of `appBar`. |
| 104 | +
|
| 105 | +`appBarBackgroundBuilder` is called every time when collapsed size changed, so typically we can make a fading effect for the image background here. |
| 106 | +
|
| 107 | +Set `backgroundIncludingAppBarPinned` as `true` makes the image also covers the area of `appBarPinned`. |
| 108 | +
|
| 109 | +``` |
| 110 | +var layout = JkAppBarLayout( |
| 111 | + ... |
| 112 | + backgroundIncludingAppBarPinned: true, |
| 113 | + appBarBackgroundBuilder: (collapsedRatio) { |
| 114 | + return Opacity( |
| 115 | + opacity: 1 - collapsedRatio, |
| 116 | + child: Image.asset("assets/your_background.jpg", |
| 117 | + fit: BoxFit.cover)); |
| 118 | + }, |
| 119 | +); |
| 120 | +``` |
| 121 | +
|
| 122 | +## Colored background |
| 123 | +
|
| 124 | +By default, we apply the color of system default AppBar as background. |
| 125 | +
|
| 126 | +You can customize the color by `appBarBackgroundColor`: |
| 127 | +
|
| 128 | +``` |
| 129 | +var layout = JkAppBarLayout( |
| 130 | + ... |
| 131 | + appBarBackgroundColor: Colors.green, |
| 132 | +); |
| 133 | +``` |
| 134 | +
|
| 135 | +## Default text size/color and icon color |
| 136 | +
|
| 137 | +By default, all the text size/color and icon color on the `appBar`, `appBarPinned`, `bottomBar`, `bottomBarPinned` will be the same with default system AppBar. |
| 138 | +
|
| 139 | +If you want to ignore these default theme/style, set `appBarDefaultTheme` as false: |
| 140 | +
|
| 141 | +``` |
| 142 | +var layout = JkAppBarLayout( |
| 143 | + ... |
| 144 | + appBarDefaultTheme: false, |
| 145 | +); |
| 146 | +``` |
| 147 | +
|
| 148 | +## Horizontal support |
| 149 | +
|
| 150 | +Set `scrollDirection` as `Axis.horizontal` to show app bars in horizontal mode. |
| 151 | +
|
| 152 | +Don't forget to set the `scrollDirection` in `JkAppBarListView` / `JkAppBarGridView` / `JkAppBarSingleChildScrollView` at the same time. |
| 153 | +
|
| 154 | +``` |
| 155 | +var layout = JkAppBarLayout( |
| 156 | + ... |
| 157 | + scrollDirection: Axis.horizontal, |
| 158 | + |
| 159 | + child: JkAppBarListView.builder( |
| 160 | + scrollDirection: Axis.horizontal, // Don't forget this |
| 161 | + itemCount: 300, |
| 162 | + itemBuilder: (context, index) => Text("List Item $index"), |
| 163 | + ), |
| 164 | +); |
| 165 | +``` |
| 166 | +
|
| 167 | +## Sample code |
| 168 | +
|
| 169 | +``` |
| 170 | +import 'package:flutter/material.dart'; |
| 171 | +import 'package:jk_custom_appbar/jk_appbar.dart'; |
| 172 | + |
| 173 | +void main() { |
| 174 | + runApp(const MyApp()); |
| 175 | +} |
| 176 | + |
| 177 | +class MyApp extends StatefulWidget { |
| 178 | + const MyApp({super.key}); |
| 179 | + |
| 180 | + @override |
| 181 | + State<MyApp> createState() => _MyAppState(); |
| 182 | +} |
| 183 | + |
| 184 | +class _MyAppState extends State<MyApp> with SingleTickerProviderStateMixin { |
| 185 | + @override |
| 186 | + Widget build(BuildContext context) { |
| 187 | + Widget child = JkAppBarLayout( |
| 188 | + appBar: Text("appBar"), // optional |
| 189 | + appBarPinned: Text("appBarPinned"), // optional |
| 190 | + bottomBarPinned: Text("bottomBarPinned"), // optional |
| 191 | + bottomBar: Text("bottomBar"), // optional |
| 192 | + child: JkAppBarListView.builder( |
| 193 | + itemCount: 300, |
| 194 | + itemBuilder: (_, index) => Text("Item $index"), |
| 195 | + ) |
| 196 | + ); |
| 197 | + |
| 198 | + return MaterialApp( |
| 199 | + home: Scaffold( |
| 200 | + body: child, |
| 201 | + ), |
| 202 | + ); |
| 203 | + } |
| 204 | +} |
| 205 | +``` |
0 commit comments