搜尋套件、儲存庫與 APP 分類

套件詳情v1.0.0

state_notifier

ValueNotifier,但位於 Flutter 之外,並帶有某些額外功能

AndroidiOSWebmacOSWindowsLinux
近 30 天下載
415萬
喜歡數
338
Pub 分數
160

安裝套件

flutter pub add state_notifier

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

StateNotifier 是一個 Dart 套件,它在 ValueNotifier 的基礎上擴展了用於在 Flutter 框架之外進行狀態管理的增強功能。它提供了一種乾淨、反應式的狀態管理方式,並內建支援異步操作、錯誤處理和除錯工具。此套件專為非 Flutter 環境(如 Web、桌面及伺服器端應用)設計,與依賴注入整合良好,並促進關注點分離。透過不可變更新和簡化訂閱機制,該套件提升了效能與開發者體驗。

適用情境

  • 在非Flutter Dart應用中管理應用狀態
  • 使用錯誤恢復處理非同步狀態轉換
  • 與依賴項注入系統整合
  • 跨平台建構可重用的狀態邏輯
  • 建立可測試且可維護的狀態類別

主要特色

  • 擴展 ValueNotifier 以提供額外功能
  • 支援非同步狀態更新與錯誤
  • 不可變狀態更新
  • 內建的除錯工具
  • 平台無關設計
  • 與 DI 框架的輕鬆整合

適合對象

  • Dart 開發人員建構跨平台應用
  • 需要在多個平台之間共享狀態邏輯的團隊
  • 需要強大狀態管理但不使用 Flutter 的項目
  • 尋求輕量級、可測試狀態解決方案的開發者

使用建議

  • 不打算直接在Flutter組件中使用
  • 需要手動訂閱管理
  • 最佳搭配依賴注入系統
  • 有限的內建UI整合
  • 可能需要額外的樣板程式碼來處理複雜的狀態流程

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

pub package Welcome to state_notifier~

This package is a recommended solution for managing state when using Provider or Riverpod.

Long story short, instead of extending ChangeNotifier, extend StateNotifier:

class City {
  City({required this.name, required this.population});
  final String name;
  final int population;
}


class CityNotifier extends StateNotifier<List<City>> {
  CityNotifier() : super(const <City>[]);

  void addCity(City newCity) {
    state = [
      ...state,
      newCity,
    ];
  }
}

Motivation

The purpose of StateNotifier is to be a simple solution to control state in an immutable manner.
While ChangeNotifier is simple, through its mutable nature, it can be harder to maintain as it grows larger.

By using immutable state, it becomes a lot simpler to:

  • compare previous and new state
  • implement an undo-redo mechanism
  • debug the application state

Good practices

DON'T update the state of a StateNotifier outside the notifier

While you could technically write:

class Counter extends StateNotifier<int> {
  Counter(): super(0);
}

final notifier = Counter();
notifier.state++;

That is considered an anti-pattern (and your IDE should show a warning).

Only the StateNotifier should modify its state. Instead, prefer using a method:

class Counter extends StateNotifier<int> {
  Counter(): super(0);

  void increment() => state++:
}

final notifier = Counter();
notifier.increment();

The goal is to centralize all the logic that modifies a StateNotifier within the StateNotifier itself.

FAQ

Why are listeners called when the new state is == to the previous state?

You may realize that a StateNotifier does not use == to verify that the state has changed before notifying for changes.

This behavior is voluntary, for performance reasons.

The reasoning is that StateNotifier is typically used with complex objects, which often override == to perform a deep comparison.
But performing a deep comparison can be a costly operation, especially since it is common for the state to contain lists/maps.
Similarly, for complex states, it is rare that when calling notifier.state = newState, the new and previous states are the same.

As such, instead of using ==, StateNotifier relies on identical to compare objects.
This way, when using StateNotifier with simple states like int/enums, it will correctly filter identical states. At the same time, this preserves performance on complex states, as identical will not perform a deep object comparison.

Using custom notification filter logic

You can override the method updateShouldNotify(T old,T current) of a StateNotifier to change the default behaviour, such as for:

  • using == instead of identical to filter updates, for deep state comparison
  • always returning true to revert to older behaviors of StateNotifier
  @override
  bool updateShouldNotify(User old, User current) {
    /// only update the User content changes, even if using a different instance
    return old.name != current.name && old.age != current.age;
  }

Usage

Integration with Freezed

While entirely optional, it is recommended to use StateNotifier in combination with Freezed.
Freezed is a code-generation package for data-classes in Dart, which automatically generates methods like copyWith and adds support for union-types.

A typical example would be using Freezed to handle data vs error vs loading states. With its union-types, it can lead to a significant improvement in maintainability as it:

  • ensures that your application will not enter illogical states (such as both having a "data" and being in the "loading" state)
  • ensures that logic handles all possible cases. Such as forcing that the loading/error cases be checked before trying to access the data.

The idea is that, rather than defining the data, error and loading state in a single object like:

class MyState {
  MyState(...);
  final Data data;
  final Object? error;
  final bool loading;
}

We can use Freezed to define it as:

@freezed
class MyState {
  factory MyState.data(Data data) = MyStateData;
  factory MyState.error(Object? error) = MyStateError;
  factory MyState.loading() = MyStateLoading;
}

That voluntarily prevents us from doing:

void main() {
  MyState state;
  print(state.data);
}

Instead, we can use the generated map method to handle the various cases:

void main() {
  MyState state;
  state.when(
    data: (state) => print(state.data),
    loading: (state) => print('loading'),
    error: (state) => print('Error: ${state.error}'),
  );
}
Integration with provider/service locators

StateNotifier is easily compatible with provider through an extra mixin: LocatorMixin.

Consider a typical StateNotifier:

class Count {
  Count(this.count);
  final int count;
}

class Counter extends StateNotifier<Count> {
  Counter(): super(Count(0));

  void increment() {
    state = Count(state.count + 1);
  }
}

In this example, we may want to use Provider.of/context.read to connect our Counter with external services.

To do so, simply mix-in LocatorMixin as such:

class Counter extends StateNotifier<Count> with LocatorMixin {
// unchanged
}

That then gives you access to:

  • read, a function to obtain services
  • update, a new life-cycle that can be used to listen to changes on a service

We could use them to change our Counter incrementation to save the counter in a DB when incrementing the value:

class Counter extends StateNotifier<Count> with LocatorMixin {
  Counter(): super(Count(0))

  void increment() {
    state = Count(state.count + 1);
    read<LocalStorage>().writeInt('count', state.count);
  }
}

Where Counter and LocalStorage are defined using provider this way:

void main() {
  runApp(
    MultiProvider(
      providers: [
        Provider(create: (_) => LocalStorage()),
        StateNotifierProvider<Counter, Count>(create: (_) => Counter()),
      ],
      child: MyApp(),
    ),
  );
}

Then, Counter/Count are consumed using your typical context.watch/Consumer/context.select/...:

@override
Widget build(BuildContext context) {
  int count = context.watch<Count>().count;

  return Scaffold(
    body: Text('$count'),
    floatingActionButton: FloatingActionButton(
      onPressed: () => context.read<Counter>().increment(),
      child: Icon(Icons.add),
    ),
  );
}

Testing

When using LocatorMixin, you may want to mock a dependency for your tests.
Of course, we still don't want to depend on Flutter/provider to do such a thing.

Similarly, since state is protected, tests need a simple way to read the state.

As such, LocatorMixin also adds extra utilities to help you with this scenario:

myStateNotifier.debugMockDependency<MyDependency>(myDependency);
print(myStateNotifier.debugState);
myStateNotifier.debugUpdate();

As such, if we want to test our previous Counter, we could mock LocalStorage this way:

test('increment and saves to local storage', () {
  final mockLocalStorage = MockLocalStorage();
  final counter = Counter()
    ..debugMockDependency<LocalStorage>(mockLocalStorage);

  expect(counter.debugState, 0);

  counter.increment(); // works fine since we mocked the LocalStorage

  expect(counter.debugState, 1);
  // mockito stuff
  verify(mockLocalStorage.writeInt('int', 1));
});

Note: LocatorMixin only works on StateNotifier. If you try to use it on other classes by using with LocatorMixin, it will not work.

Sponsors

所屬分類

依賴

依賴清單 1 項

原始碼儲存庫

使用此套件的專案

所在榜單