本地通知

简介

Nylo Website 通过 LocalNotification 类提供本地通知系统。这允许您在 iOS 和 Android 上发送即时或定时的富内容通知。

本地通知不支持 Web 平台。在 Web 上尝试使用它们将抛出 NotificationException。

基本用法

使用构建器模式或静态方法发送通知：

import 'package:nylo_framework/nylo_framework.dart';

// Builder pattern
await LocalNotification(title: "Hello", body: "World").send();

// Using the helper function
await localNotification("Hello", "World").send();

// Using the static method
await LocalNotification.sendNotification(
  title: "Hello",
  body: "World",
);

定时通知

安排通知在特定时间发送：

// Schedule for tomorrow
final tomorrow = DateTime.now().add(Duration(days: 1));

await LocalNotification(
  title: "Reminder",
  body: "Don't forget your appointment!",
).send(at: tomorrow);

// Using the static method
await LocalNotification.sendNotification(
  title: "Reminder",
  body: "Don't forget your appointment!",
  at: tomorrow,
);

构建器模式

LocalNotification 类提供流畅的构建器 API。所有链式方法都返回 LocalNotification 实例：

await LocalNotification(title: "New Photo", body: "Check this out!")
    .addPayload("photo_id:123")
    .addId(42)
    .addSubtitle("From your friend")
    .addBadgeNumber(3)
    .addSound("custom_sound.wav")
    .send();

链式方法

send()

Future<void> send({
  DateTime? at,
  AndroidScheduleMode? androidScheduleMode,
})

如果提供了 at 参数，则在该时间安排通知。否则立即显示。

平台配置

平台特定选项通过 AndroidNotificationConfig 和 IOSNotificationConfig 对象进行配置。

Android 配置

将 AndroidNotificationConfig 传递给 setAndroidConfig()：

await LocalNotification(
  title: "Android Notification",
  body: "With custom configuration",
)
.setAndroidConfig(AndroidNotificationConfig(
  channelId: "custom_channel",
  channelName: "Custom Channel",
  channelDescription: "Notifications from custom channel",
  importance: Importance.max,
  priority: Priority.high,
  enableVibration: true,
  vibrationPattern: [0, 1000, 500, 1000],
  enableLights: true,
  ledColor: Color(0xFF00FF00),
))
.send();

AndroidNotificationConfig 属性

iOS 配置

将 IOSNotificationConfig 传递给 setIOSConfig()：

await LocalNotification(
  title: "iOS Notification",
  body: "With custom configuration",
)
.setIOSConfig(IOSNotificationConfig(
  presentAlert: true,
  presentBanner: true,
  presentSound: true,
  threadIdentifier: "thread_1",
  interruptionLevel: InterruptionLevel.active,
))
.addBadgeNumber(1)
.addSound("custom_sound.wav")
.send();

IOSNotificationConfig 属性

附件（仅 iOS）

为 iOS 通知添加图片、音频或视频附件。附件从 URL 下载：

await LocalNotification(
  title: "New Photo",
  body: "Check out this image!",
)
.addAttachment(
  "https://example.com/image.jpg",
  "photo.jpg",
  showThumbnail: true,
)
.send();

管理通知

取消特定通知

await LocalNotification.cancelNotification(42);

// With a tag (Android)
await LocalNotification.cancelNotification(42, tag: "my_tag");

取消所有通知

await LocalNotification.cancelAllNotifications();

清除角标计数

await LocalNotification.clearBadgeCount();

权限

向用户请求通知权限：

// Request with defaults
await LocalNotification.requestPermissions();

// Request with specific options
await LocalNotification.requestPermissions(
  alert: true,
  badge: true,
  sound: true,
  provisional: false,
  critical: false,
  vibrate: true,
  enableLights: true,
  channelId: 'default_notification_channel_id',
  channelName: 'Default Notification Channel',
);

权限会在首次通过 NyScheduler.taskOnce 发送通知时自动请求。

平台设置

iOS 设置

在您的 Info.plist 中添加：

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

Android 设置

在您的 AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />

API 参考

静态方法

实例方法（链式调用）