State Restoration of Flutter App

Android and iOS can interrupt app processes to optimize useful resource utilization. The system can kill apps within the background to realize extra reminiscence and CPU for the foreground. A killed app will begin from scratch when a consumer brings it again. Nevertheless, the consumer expects to see the identical app state as once they left it as a substitute of beginning over once more.

On this tutorial, you’ll see the way to protect the state of Flutter apps when the system decides to kill them. Within the course of, you’ll learn to:

• Arrange the setting.
• Uncover the restorable states.
• Implement apps with state restoration.
• Take a look at state restoration.

Notice: This tutorial assumes you’re engaged on macOS and constructing apps for each Android and iOS. Nevertheless, you may as well work on Linux or Home windows and construct for Android solely. If that’s the case, ignore iOS-specific elements, and use the Shift-F10 key shortcut as a substitute of Management-R. You can too construct the identical app for the online or desktop, however state restoration has no which means on these platforms.

Getting Began

Obtain the starter undertaking by clicking Obtain supplies on the high or backside of the tutorial.

On this tutorial, you’ll construct a ToDo checklist app that permits you to add a title and date for every merchandise. Then, you’ll add the state restoration performance, so that you don’t lose any essential information if the app closes unexpectedly.

First, you’ll discover the easy app. Open and run the starter undertaking. You need to use Management-R in Android Studio. Press the plus button and kind a title within the Merchandise particulars dialog.

A dialog on the highest of the navigation stack and the textual content of the merchandise title make up the in-memory state. So, now you’ll check the (lack of) restoration! You need to do it individually for each platforms.

Testing on Android

Go to Developer settings and activate the choice Don’t preserve actions. Then, convey your app to the entrance. You’ll see the state loss — the app begins from scratch, and the dialog isn’t restored:

To simulate the restoration of a course of, it’s a must to ship your app to the background. Then, convey one other app to the foreground. Lastly, return to your app. Getting back from the latest app switcher with out touching some other app isn’t sufficient. Additionally, don’t swipe out your app from the recents. The system received’t restore the state after that.

Notice: Disable the Don’t preserve actions possibility after the state restoration testing! Leaving it enabled might trigger battery drain and information loss in different apps. Plenty of apps don’t deal with state restoration correctly.

Testing on iOS

iOS doesn’t have the choice to implement course of killing like Android. You need to carry out some guide work. Begin by opening ios/Runner.xcworkspace in Xcode. Set the Construct Configuration to Profile, as on the screenshot under:

Notice that constructing the app in Profile mode takes extra time than in Debug. Within the case of the easy app from this tutorial, it shouldn’t have any measurable impression. However, if you’re engaged on bigger initiatives, you could need to use Debug mode by default. In such instances, you’ll be able to swap to Profile mode solely when wanted.

Subsequent, press the play button (or Command-R, not Management like in Android Studio!) to run the app. Press the plus button and kind a title within the Merchandise particulars modal. Ship the app to the background by urgent the House button or performing a gesture. Press the cease button (or Command-.) in Xcode. And eventually, reopen the app by tapping its icon. Don’t use Xcode to launch the app at this stage!

Discovering the Restorable States

Earlier than you start coding, consider what precisely the restorable elements of your app are. A superb start line is to search for StatefulWidgets. Because the identify suggests, they need to include mutable states. Notice that solely the in-memory state issues for restoration functions. Take a look at the easy instance with the checkbox:

Right here, you save the checked state immediately in a persistent manner, someplace just like the native database, file or backend. So, it is mindless to incorporate it within the restoration logic, even when a checkbox is inside StatefulWidget. Now, take a look at the second instance with a checkbox and a button to commit its state:

On this case, the state between tapping a checkbox and a button exists solely in reminiscence. So, it must be the topic of restoration. Different frequent sources of the restorable state embrace:

• TextField (together with textual content obscuring states)
• Radio buttons
• Expandable and collapsible widgets (e.g., Drawer)
• Scrollable containers (e.g., ListViews)

Notice the final bullet. The scrollable container could also be contained in the StatelessWidget. But, its scroll place is an in-memory state. In such a case, you could need to convert your widget to a StatefulWidget and add a subject for the ScrollController into its State.

The restorable state covers extra than simply the widget’s content material. The navigation stack can also be an in-memory state. Customers anticipate to return to the identical place they have been earlier than leaving the app. Notice that dialogs — like pop-ups and modals — are on the stack too.

Implementing State Restoration

Notice: Modifications you utilized by sizzling restart and sizzling reload options are misplaced when the app course of is killed, identical to an unpreserved in-memory state. All the time chilly begin your app utilizing Management-R or the play button earlier than testing the state restoration.

Lastly, you may get your fingers soiled by finding MaterialApp in fundamental.dart. Substitute // TODO: change with restorableScopeId with the next line of code:

restorationScopeId: 'app',

This may be any non-nullable string. If you wish to check the adjustments executed to the app, cease the app and rerun it with the assistance of Management-R or Command-R on macOS. Take a better look, and also you’ll see that there’s no seen impact but. The restorationScopeId allows the state restoration capability for descendant widgets. It additionally activates the essential navigation stack historical past restoration.

Enabling State Restoration on iOS

You want an additional iOS-specific step to allow state restoration. Open ios/Runner.xcodeproj in Xcode. Then, right-click the ios folder in Android Studio and choose Flutter ▸ Open iOS module in Xcode. In Xcode, assign the Restoration ID like within the screenshot under:

The adjustments within the ios/Runner/Base.lproj/Most important.storyboard XML file might embrace greater than the restoration ID. It’s regular that saving the file in a special Xcode model introduces adjustments within the numerous traces.

Including RestorationMixin

Open home_page.dart, and discover // TODO: add the RestorationMixin. Lengthen a category with RestorationMixin:

class _HomePageState extends State<HomePage> with RestorationMixin {

Subsequent, discover // TODO: implement the RestorationMixin strategies, and change it with:

@override
String? get restorationId => 'home_page'; // 1

@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) { // 2
// TODO: implement the RestorationMixin strategies
// TODO: register the checklist for restoration
// TODO: registering the scroll offset for restoration
// TODO: register the route for restoration 
}

Within the code above, you’ve gotten:

1. The restorationId getter. The worth must be distinctive throughout your app. Returning null disables the state restoration.
2. The registerForRestoration technique. You register your restorable properties right here.

Repeat the identical steps in add_item_page.dart. You need to use add_item_page because the restoration ID there. Run the app by urgent Management-R to examine if something has damaged.

Earlier than you register the restorable properties, it’s a must to create them. Within the easiest instances, simply change the sector varieties to their restorable equivalents. For instance, int to RestorableInt, TextEditingController to RestorableTextEditingController and so forth. If there’s no acceptable class within the framework, it’s a must to implement it your self.

Implementing the Restorable ToDo Merchandise Record

You’ll begin by creating the restorable ToDo gadgets checklist. The restoration course of begins with serializing. Serialization means changing to primitives, like int, double or String. Learn extra about primitives within the StandardMessageCodec documentation. The underlying native mechanisms can solely deal with the info in a serialized type. In the long run, you want a reverse course of: deserialization.

Substitute // TODO: create the RestorableToDoItemList class in restorable_todo_item_list.dart with the next code snippet:

class RestorableToDoItemList extends RestorableValue<Record<ToDoItem>> {
  @override
  Record<ToDoItem> createDefaultValue() => []; // 1

  @override
  void didUpdateValue(Record<ToDoItem>? oldValue) { // 2
    notifyListeners();
  }

  @override
  Record<ToDoItem> fromPrimitives(Object? information) => information is! Record // 3
      ? []
      : information
          .whereType<String>()
          .map((e) => ToDoItem.fromJson(jsonDecode(e)))
          .toList(growable: false);

  @override
  Object? toPrimitives() => // 4
      worth.map((e) => jsonEncode(e)).toList(growable: false);
}

A number of strategies are used right here:

1. createDefaultValue, which returns a worth to make use of when there’s no restoration information. On this case, it’s an empty checklist.
2. From didUpdateValue, you notify the listeners. Normally, you’ll be able to invoke notifyListeners() with none situation. However, if a primitive illustration of the brand new and previous values is similar, you’ll be able to skip the notifications. This could occur, for instance, if some fields of the category are excluded from serialization.
3. fromPrimitives builds the occasion of your class out of the uncooked information.
4. toPrimitives does the other operation. Its implementation should be symmetrical to a earlier one.

Restoring Most important Web page

It’s time to make use of the restorable checklist. Open main_page.dart, discover // TODO: change the sort to RestorableToDoItemList, and alter the ToDo checklist subject definition to the next:

class _HomePageState extends State<HomePage> with RestorationMixin {
  last _toDos = RestorableToDoItemList();

The checklist kind is now a subtype of the RestorableProperty as a substitute of the plain Record. Subsequent, change the direct entry to the checklist to a worth getter. Discover // TODO: use worth subject of the checklist — word that there are two such cases. Substitute the primary with:

kids: _toDos.worth.isEmpty

And the second with:

Record<Widget> _buildToDoList() => _toDos.worth

Subsequent, discover // TODO: create a brand new occasion of a listing, and change the checklist mutation with a brand new occasion containing an appended merchandise:

setState(() => _toDos.worth = [..._toDos.value, item]);

Then, change // TODO: dispose the restorable checklist to a dispose technique invocation:

_toDos.dispose();

Lastly, register the checklist for restoration by changing // TODO: register the checklist for restoration with:

registerForRestoration(_toDos, 'home_todos');

Run the app by urgent Management-R, and add some ToDos to the checklist. Now, carry out the testing steps from the Getting Began part to examine if the restoration works. You’ll see a consequence like within the screenshot under:

Restore the Scroll Place

The framework has no class like RestorableScrollController. So, it’s a must to additionally implement its restoration your self. Flutter makes use of a declarative UI. You possibly can’t question the SingleChildScrollView widget for its present scroll place, so it’s a must to add ScrollController to entry or set the scroll offset.

Open main_page.dart. Add a ScrollController together with its restorable offset instead of // TODO: add scroll offset and controller:

last _scrollOffset = RestorableDouble(0); // 1
last _scrollController = ScrollController(); // 2

Within the code above, you’ve gotten:

1. The RestorableDouble for the scroll offset (place).
2. The not restorable scroll controller.

Time to make use of them! In initState, discover // TODO: take heed to the scroll place adjustments, and change it with:

_scrollController
      .addListener(() => _scrollOffset.worth = _scrollController.offset); // 1
  WidgetsBinding.occasion?.addPostFrameCallback(
      (_) => _scrollController.jumpTo(_scrollOffset.worth)); // 2

The code might look sophisticated, nevertheless it’s truly quite simple. Right here’s what it incorporates:

1. Scroll listener updating the restorable offset.
2. Setting the restored scroll place on first initialization.

You need to bind a controller with a scrollable widget. Discover // TODO: assign scroll controller, and insert the next code there:

controller: _scrollController,

Don’t overlook to dispose the controller and offset. Substitute // TODO: dispose the scroll controller and offset with disposal technique calls:

_scrollController.dispose();
_scrollOffset.dispose();

To make it work, it’s worthwhile to register the scroll offset subject for restoration. Change // TODO: registering the scroll offset for restoration to:

registerForRestoration(_scrollOffset, 'scroll_offset');

Notice that the above operate must be inside a restoreState technique. Now, you’ll be able to run the app and add some ToDos to the checklist to make it scrollable.

Notice: You possibly can allow multiwindow mode and/or enlarge the font scale to cut back the variety of wanted gadgets.

Scroll by way of the checklist and carry out the testing steps from the Getting Began part. It ought to appear like this:

Implementing the Restorable Route Returning End result

The final modification on the primary web page refers back to the navigation to the add merchandise web page. Including restorationScopeId to the app allows navigation route restoration. However it doesn’t cowl returning the outcomes from different pages. To fill that hole, discover // TODO: change with restorable route in a main_page.dart file, and add the next fields:

late last _addItemRoute = RestorableRouteFuture<ToDoItem?>( // 1
  onPresent: (navigator, arguments) => navigator.restorablePush( // 2
    _addItemDialogRouteBuilder,
    arguments: arguments,
    ),
  onComplete: (ToDoItem? merchandise) { // 3
    if (merchandise != null) {
      setState(() => _toDos.worth = [..._toDos.value, item]);
    }
  });

static DialogRoute<ToDoItem?> _addItemDialogRouteBuilder( // 4
  BuildContext context,
  Object? arguments,
) => DialogRoute(
       context: context,
       builder: (_) => const AddItemPage(),
     );

Within the code above, you’ve gotten:

1. The restorable route declaration.
2. The onPresent callback for the navigation begin.
3. The onComplete callback for the navigation end, which is known as when you’ve gotten a consequence.
4. The static route builder. In the event you go a non-static operate right here, code will compile, however you’ll get a runtime error.

Use that route instead of // TODO: current restorable route:

onPressed: _addItemRoute.current,
tooltip: 'Add merchandise',

You need to dispose the route like some other restorable property. Substitute // TODO: dispose the route with:

_addItemRoute.dispose();

And eventually, register the route for restoration by changing // TODO: register the route for restoration with:

registerForRestoration(_addItemRoute, 'add_item_route');

Run the app, and faucet the floating motion button. Carry out the testing steps from the Getting Began part. You’ll see a consequence like this:

Implementing Easy Restorable Properties

Open add_item_page.dart. It has two properties: a textual content modifying controller holding the title and a date that got here from the picker. Each properties have restorable variations within the framework. Within the case of a textual content modifying controller, the code adjustments are easy. First, change TODO: add the RestorationMixin with:

class _AddItemPageState extends State<AddItemPage> with RestorationMixin {

Subsequent, change TextEditingController to its restorable model, RestorableTextEditingController. Discover // TODO: change with restorable controller, and alter the road to:

last _controller = RestorableTextEditingController();

Analogously, use RestorableDateTime instead of // TODO: change with restorable date:

last _dueDate = RestorableDateTime(DateTime.now());

You possibly can’t use the brand new fields immediately. Discover the traces with // TODO: change with worth property, and alter them accordingly:

controller: _controller.worth,
//...
youngster: Textual content(DateFormat.yMd().format(_dueDate.worth)),
//...
_controller.worth.textual content,
//...
_dueDate.worth,

Don’t overlook to dispose a restorable date. Change // TODO: dispose the date to:

_dueDate.dispose();

Lastly, set the restoration ID and register the properties for restoration. Discover // TODO: implement the RestorationMixin members, and change it with:

@override
String? get restorationId => 'add_item_page';

@override
void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
  registerForRestoration(_controller, 'title');
  registerForRestoration(_dueDate, 'due_date');
  // TODO: register route for restoration
}

Run the app, and faucet the floating motion button. Then, kind a title and select a date. Lastly, carry out the testing steps from the Getting Began part. The consequence ought to appear like this:

The sector for a date is last. You don’t modify the restorable date itself, however its underlying worth. Notice the default worth of the date. There’s no distinction between the worth you decide and that default.

Contemplate a case the place you open an merchandise, add dialog and ship the app to the background instantly. Then, you come two days later, and the app course of was killed within the meantime. Lastly, after restoration, you’ll see the date two days previously. In some instances, you could need to not save and restore the worth when a consumer hasn’t chosen something but.

Including State to Date Picker Restoration

The final — however not the least — a part of this tutorial is concerning the restorable path to the DatePicker. Like on the earlier web page, discover // TODO: change with restorable route, take away the callback, and add the fields:

late last RestorableRouteFuture<DateTime?> _restorableDatePickerRouteFuture =
  RestorableRouteFuture<DateTime?>(
    onComplete: (newDate) {
      if (newDate != null) {
        setState(() => _dueDate.worth = newDate);
      }
    },
    onPresent: (NavigatorState navigator, Object? arguments) =>
      navigator.restorablePush(
        _datePickerRoute,
        arguments: _dueDate.worth.millisecondsSinceEpoch, // 1
      ),
    );

static Route<DateTime> _datePickerRoute(
  BuildContext context,
  Object? arguments,
  ) => DialogRoute<DateTime>(
        context: context,
        builder: (context) => DatePickerDialog(
          restorationId: 'date_picker_dialog',
          initialEntryMode: DatePickerEntryMode.calendarOnly,
          initialDate: DateTime.fromMillisecondsSinceEpoch(arguments! as int), // 2
          firstDate: DateTime.now(),
          lastDate: DateTime(2243),
        ),
      );

Within the code above, you’ve gotten:

1. The navigation argument serialization.
2. The navigation consequence deserialization.

You not solely obtain a consequence right here but additionally go an preliminary date as an argument. The DateTime class isn’t primitive, so it’s not serializable utilizing StandardMessageCodec. That’s why it’s a must to go it because the variety of seconds for the reason that Unix epoch: January 1, 1970. The yr of final date (2243) is only a most supported worth.

Use the route instead of // TODO: current restorable route:

onTap: _restorableDatePickerRouteFuture.current,

Subsequent, dispose the route. Substitute // TODO: dispose the route with:

_restorableDatePickerRouteFuture.dispose();

Lastly, register the route for restoration instead of // TODO: register route for restoration in a restoreState technique:

registerForRestoration(_restorableDatePickerRouteFuture, 'date_picker_route_future');

The place to Go From Right here?

You made it by way of your entire tutorial about state restoration in Flutter! Get the entire code for this tutorial by clicking Obtain supplies on the high or backside of the tutorial.

You’ve gotten an amazing begin on state restoration, however this tutorial doesn’t cowl all the capabilities of the state restoration API. There are extra lessons, like RestorationBucket. Some lessons have extra strategies, like RestorationMixin.didToggleBucket. Some strategies have extra parameters, like oldBucket and initialRestore of RestorationMixin.restoreState. It’s possible you’ll discover them helpful in superior use instances.

A superb start line within the official Flutter documentation is the RestorationManager web page. You possibly can go ahead from there by following the hyperlinks to the subsequent lessons.

Wish to study extra about state restoration within the native platforms? Take a look at our different tutorials: State Restoration in SwiftUI for iOS and Jetpack Saved State for ViewModel: Getting Began for Android.

We hope you loved this tutorial. When you’ve got any questions or feedback, please be a part of the discussion board dialogue under!