enhanced_change_notifier 1.0.1

A enhanced version of ChangeNotifier introduces new features `target`, `once`, and `immediate`.

enhanced_change_notifier

支持对象属性变化的定向通知。

Enhanced ChangeNotifier 在 Flutter Core 现有 ChangeNotifier 能力之外，增加了三个特性：

• target：指定属性变化时通知监听器。
• once：属性变化时只通知一次。
• immediate：监听器注册后立即发送一次通知，并在后续变化时继续通知。

语言: 中文 | English

平台支持

Android	iOS	MacOS	Web	Linux	Windows
✅	✅	✅	✅	✅	✅

环境要求

• Flutter >=3.0.0 <4.0.0
• Dart >=2.17.0

开始使用

已发布到 pub.dev，可以运行以下 Flutter 命令安装：

flutter pub add enhanced_change_notifier

Dart 用法

对于多个属性或可变数据类型，可以直接继承 EnhancedChangeNotifier，以满足缓存、定向监听等灵活需求。

import 'package:enhanced_change_notifier/enhanced_change_notifier.dart';

class AppModel extends EnhancedChangeNotifier {
  AppModel() {
    // 静默初始化：更新存储值，但不通知监听器。
    super.fromMap({"token": "initial-token"});
  }

  String? get token => this["token"];
  set token(String? token) {
    // 方式 1：通知式更新，保存值并通知 `token` 的监听器。
    super.properties["token"] = token;
    // 方式 2：通知式更新，保存值并通知 `token` 的监听器。
    this["token"] = token;
    // 方式 3: 静默更新 + 手动通知
    super.fromMap({"token": "new value"});
    notifyListeners("token");
  }
}

// GlobalFactory 用于创建全局单例实例。
final GlobalFactory<AppModel> appStateModel = GlobalFactory(() => AppModel());

void anyChangedListener() {
  print("any property is changed");
}

// 注册不同类型的监听器。
appStateModel.getInstance().addListener(anyChangedListener);
appStateModel.getInstance().addListener((String property) => print("$property is changed"), target: 'token');
appStateModel.getInstance().addListener((String property) => print("$property is changed, will notify only once."), target: 'token', once: true);
appStateModel.getInstance().addListener((String property) => print("$property is changed, will send immediately after listener is registered."), target: 'token', immediate: true);

// setter 会触发监听，因为内部使用了 `this["token"] = token` 或 super.properties["token"]。
appStateModel.getInstance().token = "fe3f6b58-684e-4063-ba3b-1b8f14981a8e";

// 移除指定监听器。
appStateModel.getInstance().removeListener(anyChangedListener);

Signal 是一个单值实现，可以在释放信号前缓存等待执行的监听器。

import 'package:enhanced_change_notifier/signal.dart';

Signal isConsumerReady = Signal();
isConsumerReady.value = false;

// 注册监听器：Signal(true) 时立即消费，否则等待一次释放。
isConsumerReady.promise(() => print("Task 1 executed"));
isConsumerReady.promise(() => print("Task 2 executed"));

// 延迟释放信号。
Future.delayed(Duration(milliseconds: 300), () => isConsumerReady.value = true);

EnhancedLatchNotifier 支持复杂数据类型的延迟通知，不同于只能处理布尔值的 Signal。

import 'package:enhanced_change_notifier/enhanced_change_notifier.dart';
import 'package:enhanced_change_notifier/enhanced_latch_notifier.dart';

class LatchStateEvent {
  String actionId;
  int value;
  LatchStateEvent(this.actionId, this.value);
}

class DelayedLatch extends EnhancedLatchNotifier<LatchStateEvent> {}

final GlobalFactory<DelayedLatch> latchDemo = GlobalFactory(() => DelayedLatch());
latchDemo.getInstance().addListener((event) {
  if (event.actionId == "test") {
    print("triggered ==> ${event.actionId}, ${event.value}");
  }
});
// 触发 latch 并缓存状态事件。
latchDemo.getInstance().fire(LatchStateEvent("test", 99));
// unlatch 调用后触发监听器。
Future.delayed(const Duration(seconds: 3), () => latchDemo.getInstance().unlatch());

其他信息

如果遇到问题，欢迎提交 issue。