更新记录

1.0.0（2026-10-02）

• 首个版本：三端（Android / iOS / 鸿蒙）本地通知与定时提醒，uni-app 与 uni-app x 双框架可用，功能详见 readme。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

其他

hans-local-notify 本地通知 / 定时提醒

三端（Android + iOS + 鸿蒙）本地通知与定时提醒 UTS 插件，uni-app 与 uni-app x 双框架可用。

定位：不做通知样式库，不做厂商推送；专做"定时不丢"。

核心能力：

1. 重启不丢：调度任务持久化，设备重启后自动恢复（Android BOOT_COMPLETED 重排；鸿蒙由系统提醒代理原生托管）。
2. 精准触发：Android 12+ 精确闹钟豁免处理与自动降级、iOS UNCalendar/TimeInterval 触发器、鸿蒙 reminderAgent。
3. 三端 + 双框架：Android / iOS / 鸿蒙；经典 uni-app 与 uni-app x 同一套接口。
4. 就绪度诊断：getReadiness() 一次返回"能不能准时响"（授权 / 精确闹钟 / 电池优化 / OEM 自启动指引）。

快速开始

import { requestPermission, schedule, getReadiness } from '@/uni_modules/hans-local-notify'

// 1. 申请通知授权
requestPermission({
  success: (res) => console.log('授权状态', res.status) // granted / denied / provisional / notDetermined
})

// 2. 排一个 5 秒后的一次性提醒
schedule({
  id: 'demo-once',
  title: '喝水提醒',
  body: '该喝一杯水了',
  delaySeconds: 5,
  success: (id) => console.log('已排程', id),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

// 3. 诊断"能不能准时响"
getReadiness({
  success: (r) => {
    // r.notificationGranted        通知是否已授权
    // r.exactAlarmAllowed          Android 12+ 精确闹钟豁免（其他平台 null）
    // r.batteryOptimizationIgnored 电池优化白名单（其他平台 null）
    // r.autoStartGuideUrl          检测到 OEM 时的设置页跳转方案（intent: URI）
    // r.pendingCount / r.platformLimit  待触发数与平台上限
  }
})

回调统一主线程触发，uvue / vue 页面可直接更新状态。所有异步 API 均为 success / fail / complete 回调形态；fail 回调参数见 NotifyFail。

API

schedule 参数（NotifyScheduleOptions）

{
  id?: string,              // 缺省自动生成；持久化与 cancel 的主键
  title: string,
  subtitle?: string,        // iOS subtitle / Android 子文本
  body: string,
  badge?: number,           // iOS 角标
  sound?: string,           // iOS 生效（已注册铃声名，缺省系统默认）；Android 8+ 由渠道决定
  vibrate?: boolean,        // 缺省 true
  vibratePattern?: number[],// Android 震动节奏（毫秒 on/off 交替）
  channelId?: string,       // Android 渠道，缺省插件默认渠道
  extras?: Map<string, string>,  // 点击回调原样带回
  pagePath?: string,        // 点击后要打开的应用内页面
  triggerAt?: number,       // 绝对触发时间(ms) —— 与 delaySeconds 二选一，都传以 triggerAt 为准
  delaySeconds?: number,    // 相对延迟（秒）
  repeatRule?: {            // 缺省一次性
    kind: 'once' | 'daily' | 'weekly' | 'monthly' | 'interval',
    weekdays?: number[],        // weekly：1=周日 ... 7=周六（对齐 iOS）
    daysOfMonth?: number[],     // monthly：1~31
    intervalSeconds?: number    // interval：最小 60
  },
  maxOccurrences?: number,  // 周期上限，缺省无限
  success / fail / complete
}

create 参数（NotifyCreateOptions）

与 schedule 共用全部内容字段（id / title / subtitle / body / badge / sound / vibrate / vibratePattern / channelId / extras / pagePath），没有 triggerAt / delaySeconds / repeatRule / maxOccurrences。id 不传由平台自动生成，返回值即最终 id。

其他 API 参数

Android 8+ 渠道创建后 importance / 声音 / 震动 不可再编程修改（仅用户可改），重复调用同名渠道只更新 name/description。

周期语义

• 本地时间：daily/weekly/monthly 以首次触发时刻的时:分:秒为锚，跨时区/DST 保持"本地时间"语义（Android 收到时间/时区变化广播后自动重排）。
• monthly 月末兜底：不存在的日期（如 2 月 31 日）按当月最后一天触发。

类型参考

数据类型

NotifyReadinessResult（getReadiness success 回调）

NotifyPendingItem（getPendingList success 回调元素）

uni-app x 侧该回调参数声明为 Array<any>（iOS 桥接兼容），元素按本表形状取字段即可。

NotifyClickEvent（onNotificationClick 回调）

NotifyFail（所有 fail 回调参数，extends IUniError）

枚举

平台差异（重要）

错误码（9013xxx）

权限与数据说明

• Android：POST_NOTIFICATIONS、SCHEDULE_EXACT_ALARM / USE_EXACT_ALARM（闹钟提醒类应用政策允许）、RECEIVE_BOOT_COMPLETED、WAKE_LOCK、REORDER_TASKS（点击通知热启动前置任务栈，normal 级）。
• iOS：系统用户通知授权（UNUserNotificationCenter）。
• 鸿蒙：通知授权 + PUBLISH_AGENT_REMINDER。
• 数据仅保存在本机（任务标题、正文、触发时间、周期规则、extras、目标页面路径），用于调度持久化与重启恢复；不上传任何数据，不含厂商推送通道，不读取通知栏内容。

常见问题（为什么不响）

1. 授权没给：先 getReadiness() 看 notificationGranted；拒绝后引导去系统设置。
2. Android 12+ 不准点：exactAlarmAllowed === false 说明无精确闹钟豁免，已自动降级（Doze 下有 ≥9 分钟节流）。openExactAlarmSettings() 引导用户授权；高频提醒（<9 分钟）建议配合前台保活类插件。
3. 小米/华为/OPPO/vivo 杀后台：getReadiness().autoStartGuideUrl 会给出对应设置页 intent URI，引导用户加自启动/电池白名单。
4. iOS 注册到第 65 条失败：系统 pending 上限 64，先 cancel 腾位或 getPendingList 清理。
5. 鸿蒙第 31 条失败：系统提醒实例上限 30。
6. 通知栏不显示但没报错：Android 8+ 检查渠道是否被用户关闭（系统设置 → 应用 → 通知渠道）。
7. 重启后没响：Android 首次安装后需启动过一次应用再重启（receiver 注册随安装生效）；确认未使用"强制停止"（强制停止会清除闹钟直到下次启动应用）。