|
3 | 3 | # Shared Value
|
4 | 4 |
|
5 | 5 | A wrapper over [InheritedModel](https://api.flutter.dev/flutter/widgets/InheritedModel-class.html),
|
6 |
| - this module allows users to easily share global state between multiple widgets. |
| 6 | + this module allows users to easily manage global state in your flutter apps. |
7 | 7 |
|
8 |
| -It's a low-boilerplate generalization of the `Provider` state management solution. |
| 8 | +At a high level, `SharedValue` puts your variables in an intelligent "container" that is flutter-aware. |
| 9 | + |
| 10 | +It can be viewed as a low-boilerplate generalization of the `Provider` state management solution. |
9 | 11 |
|
10 | 12 | ## Usage
|
11 | 13 |
|
12 | 14 | *1. Initialize*
|
13 | 15 |
|
14 | 16 | ```dart
|
| 17 | +// This global SharedValue can be shared across the entire app |
| 18 | +final SharedValue<int> counter = SharedValue( |
| 19 | + value: 0, // initial value (optional) |
| 20 | +); |
| 21 | +
|
15 | 22 | main() {
|
16 |
| - // Insert Shared Value into the widget tree. |
17 |
| - runApp(SharedValue.wrapApp(MyApp())); |
| 23 | + runApp( |
| 24 | + // don't forget this! |
| 25 | + SharedValue.wrapApp( |
| 26 | + MyApp(), |
| 27 | + ), |
| 28 | + ); |
18 | 29 | }
|
19 |
| -
|
20 |
| -// Create a `SharedValue` object that holds the value of our counter. |
21 |
| -var counter = SharedValue(value: 0); |
22 | 30 | ```
|
23 | 31 |
|
24 | 32 | *2. Use*
|
25 | 33 |
|
| 34 | +Unlike other state management solutions, |
| 35 | +SharedValue works everywhere you'd expect dart code to work, even without a `BuildContext`. |
| 36 | + |
26 | 37 | ```dart
|
27 |
| -// Use [counter] anywhere, even without a `BuildContext` |
| 38 | +// Read [counter] |
28 | 39 | print(counter.value);
|
29 | 40 |
|
30 |
| -// Update [counter] anywhere. |
31 |
| -counter.update((value) => value + 1); |
| 41 | +// Update [counter] |
| 42 | +counter.value += 1; |
32 | 43 |
|
33 |
| -// Rebuild [MyWidget] whenever [counter] changes. |
34 |
| -class MyWidgetState extends State<MyWidget> { |
35 |
| - @override |
36 |
| - Widget build(BuildContext context) { |
| 44 | +// Use [counter] in widgets, and let shared value do the rest. |
| 45 | +Widget build(BuildContext context) { |
37 | 46 |
|
38 |
| - // The .of(context) bit makes this widget rebuild everytime counter is changed |
39 |
| - int counterValue = counter.of(context); |
| 47 | + // The .of(context) bit makes this widget rebuild automatically |
| 48 | + int counterValue = counter.of(context); |
40 | 49 |
|
41 |
| - return Text("Counter: $counterValue"); |
42 |
| - } |
| 50 | + return Text("Counter: $counterValue"); |
43 | 51 | }
|
44 | 52 | ```
|
45 | 53 |
|
46 | 54 | *3. Persist*
|
47 | 55 |
|
48 | 56 | ```dart
|
49 | 57 | // provide a shared_prefences key
|
50 |
| -var counter = SharedValue(value: 0, key: "counter"); |
51 |
| -
|
52 |
| -// Store [counter]'s value to shared preferences |
53 |
| -await counter.store(); |
| 58 | +final SharedValue<int> counter = SharedValue( |
| 59 | + key: "counter", // disk storage key for shared_preferences (optional) |
| 60 | + autosave: true, // autosave to shared prefs when value changes (optional) |
| 61 | +); |
54 | 62 |
|
55 | 63 | // Load [counter]'s value from shared preferences
|
56 | 64 | await counter.load();
|
| 65 | +
|
| 66 | +// Store [counter]'s value to shared preferences (enabling `autosave` does this automatically) |
| 67 | +await counter.store(); |
| 68 | +``` |
| 69 | + |
| 70 | +*4. Be cool* |
| 71 | + |
| 72 | +Use `.$` as an alias for `.value` :) |
| 73 | + |
| 74 | +``` |
| 75 | +print(counter.$); |
57 | 76 | ```
|
58 | 77 |
|
59 | 78 | ## Efficiency
|
60 | 79 |
|
61 |
| -Shared value is smart enough to only rebuild the widget that is using the shared value that was updated. No more, no less. |
| 80 | +Shared value is smart enough to only rebuild the widget that subscribes to updates using `.of(context)`, no more, no less. |
0 commit comments