notification - PythonIDE Docs

本地通知：申请权限、定时提醒、管理待发送通知、设置角标。不包含远程推送。

边界：只做本机本地通知。远程推送不在本模块；锁屏实时状态请看 live_activity。

#模块概览

项	说明
导入	`import notification`
适合做什么	稍后提醒、番茄钟、每日复盘、角标计数
调用时机	放在按钮回调里；不要写在 AppUI `body()` 中
推荐顺序	查/申请权限 → `schedule` 或 `schedule_at_date` → 需要时用 `remove_*` / `set_badge`
标识符	`identifier` 保持稳定，方便取消或覆盖同一条通知

#快速开始

下面脚本申请权限，并在 60 秒后发送一条通知：

python

import notification

result = notification.request_permission()
if not result.get("granted"):
    print("未授权:", result)
else:
    print(notification.schedule(
        "demo.reminder",
        "休息一下",
        "站起来活动 1 分钟",
        delay=60,
    ))

#AppUI 示例

把申请权限、调度、取消都放进按钮回调；界面只展示当前状态。

python

import appui
import notification

REMINDER_ID = "demo.reminder"

state = appui.State(
    auth="未查询",
    pending="—",
    message="点击按钮开始",
)


def refresh_status():
    state.auth = str(notification.authorization_status())
    state.pending = str(notification.pending_count())


def schedule_one_minute():
    perm = notification.request_permission()
    if not perm.get("granted"):
        state.message = "未获得通知权限"
        return

    result = notification.schedule(
        REMINDER_ID,
        "稍后提醒",
        "1 分钟后见",
        delay=60,
    )
    refresh_status()
    state.message = f"已调度: {result}"


def cancel_reminder():
    notification.remove_pending(REMINDER_ID)
    refresh_status()
    state.message = "已取消待发送提醒"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("提醒", [
                appui.Button("1 分钟后提醒", action=schedule_one_minute)
                .button_style("bordered_prominent"),
                appui.Button("取消这条提醒", action=cancel_reminder, role="destructive"),
            ]),
            appui.Section("状态", [
                appui.LabeledContent("授权", value=state.auth),
                appui.LabeledContent("待发送", value=state.pending),
                appui.Text(state.message).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("本地通知")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`request_permission()`	申请权限 → `{"granted": bool}`
`authorization_status()`	查询授权 → 如 `authorized` / `denied`
`schedule(...)`	延迟 `delay` 秒后发送
`schedule_at_date(...)`	指定年月日时分发送
`remove_pending(id)`	取消一条待发送
`remove_all_pending()`	取消全部待发送
`pending_count()`	待发送数量
`pending_identifiers()`	待发送 ID 列表
`set_badge(n)`	设置角标，`0` 清除

#权限

request_permission() — 弹出系统授权，等待用户选择。

python

result = notification.request_permission()
if result.get("granted"):
    ...

authorization_status() — 只查询，不弹窗。

python

status = notification.authorization_status()
# authorized | denied | not_determined | provisional

也可用 permission 查询：permission.status("notifications")。

#调度

schedule(identifier, title, body, delay=5.0, sound=True, badge=0) — 相对延迟发送。

python

notification.schedule(
    "stretch.break",
    "活动一下",
    "站起来伸展 1 分钟",
    delay=60,
    sound=True,
    badge=1,
)

参数	说明
`identifier`	稳定 ID
`title` / `body`	标题与正文
`delay`	延迟秒数
`badge`	`0` 表示不修改角标

schedule_at_date(identifier, title, body, year, month, day, *, hour=0, minute=0, repeats=False) — 绝对时间发送。

python

notification.schedule_at_date(
    "daily.review",
    "每日复盘",
    "整理今天的笔记",
    2026, 6, 10,
    hour=21,
    minute=30,
)

注意：参数是 year, month, day, hour, minute，不是 Unix 时间戳。

#待发送与角标

API	说明
`remove_pending(identifier)`	取消指定 ID
`remove_all_pending()`	取消全部
`pending_count()`	返回 `int`
`pending_identifiers()`	返回 `list`
`set_badge(number)`	设置角标；`0` 清除

python

notification.remove_pending("stretch.break")
print(notification.pending_count())
print(notification.pending_identifiers())
notification.set_badge(3)

#常见错误

错误写法	后果	修正
未授权就 `schedule`	通知可能不出现	先 `request_permission()`，检查 `granted`
`schedule_at_date` 传时间戳	参数不匹配	传年月日时分
每次随机 `identifier`	无法取消旧通知	使用固定 ID
在 `body()` 里调度	刷新时反复触发	放进按钮回调

#相关文档

文档	用途
permission	统一查询 `notifications` 权限
live_activity	锁屏与灵动岛实时活动
原生能力入口	MiniApp 场景配方

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。