Scripting
开始
文档
更新日志
开始
文档
更新日志
简体中文

通知

Notification 模块允许在 Scripting 应用中创建、管理和显示本地通知，可选地包含富文本内容以及交互操作。通过这些 API，您可以安排通知的触发时间、自定义通知外观，并定义用户可在通知界面直接执行的操作。

目录

  1. 通知调度
  2. 获取通知
  3. 移除通知
  4. 设置应用徽章数
  5. 自定义通知中展示的UI
  6. 在自定义UI中获取通知数据

1. 通知调度

使用 Notification.schedule 方法可以调度本地通知，并通过配置选项来实现自定义操作以及在展开时显示富通知UI的功能。

方法:

1Notification.schedule(options: NotificationScheduleOptions): Promise<boolean>

NotificationScheduleOptions

可用此类型来配置通知选项：

1type NotificationScheduleOptions = {
2  title: string
3  subtitle?: string
4  body?: string
5  badge?: number
6  silent?: boolean
7  userInfo?: Record<string, any>
8  threadIdentifier?: string
9  triggerTime?: number
10  repeatsType?: 'hourly' | 'daily' | 'weekly' | 'monthly'
11  actions?: NotificationAction[]
12  customUI?: boolean
13}
属性 类型 说明
title string 通知的主标题文本。
subtitle string (可选) 通知副标题，部分场景可能不显示。
body string (可选) 通知正文文本。
badge number (可选) 应用图标上要显示的徽章数量。
silent boolean (可选) 若为 true，则通知不会发出声音（默认值：true）。
userInfo Record<string, any> (可选) 自定义数据，会附加在通知上，可在脚本中访问。
threadIdentifier string (可选) 用于对通知进行分组显示的标识符。
triggerTime number (可选) 通知触发时间（毫秒），若为 null 则立即发送。
repeatsType 'hourly' | 'daily' | 'weekly' | 'monthly' (可选) 通知的重复间隔类型。
actions NotificationAction[] (可选) 通知中的交互操作（按钮等）。
customUI boolean (可选) 若为 true，则在长按或下拉时展示 notification.tsx 中定义的富通知自定义UI。

NotificationAction

1type NotificationAction = {
2  title: string          // 按钮标题
3  url: string            // 按钮点击后要打开的URL，支持 Scripting URL Scheme 或 https:// 链接
4  destructive?: boolean  // （可选）是否为 destructive 操作（一般用于删除或危险操作）
5}

使用 customUI 与 actions 的示例：

假设要发送一个喝水提醒的通知，在 notification.tsx 中可以自定义界面（如按钮“已喝水”或“忽略”），并在 actions 中设置相关操作按钮，让用户直接在通知上执行任务。

1// Hydration Reminder index.tsx
2
3await Notification.schedule({
4  title: "Hydration Reminder",
5  body: "Time to drink water!",
6  customUI: true,
7  repeatsType: "hourly", // 每小时提醒一次
8  triggerTime: Date.now() + 2000, // 2秒后发送示例
9  actions: [
10    {
11      title: "I Drank",
12      url: Script.createRunURLScheme("Hydration Reminder", { drank: true }),
13    },
14    {
15      title: "Ignore",
16      url: Script.createRunURLScheme("Hydration Reminder", { drank: false }),
17      destructive: true
18    }
19  ]
20})
21
22// 当脚本 "Hydration Reminder" 运行时，index.tsx 会作为入口点
23// 可读取 Script.queryParameters["drank"] 的值来确定用户是否喝水。
24const drank = Script.queryParameters["drank"]
25if (drank === "true") {
26  // 用户选择了“已喝水”
27} else if (drank === "false") {
28  // 用户选择了“忽略”
29}

2. 获取通知

获取已投递的通知

方法:

1Notification.getAllDelivereds(): Promise<NotificationInfo[]>

返回当前仍显示在通知中心中的所有已投递通知。

1type NotificationInfo = {
2  identifier: string            // 唯一标识符
3  deliveryTime: number          // 通知投递时间戳
4  title: string                 // 通知标题
5  subtitle: string              // 通知副标题
6  body: string                  // 通知内容
7  userInfo: Record<string, any> // 自定义数据
8  threadIdentifier: string      // 分组标识符
9}

获取待投递的通知

方法:

1Notification.getAllPendings(): Promise<NotificationInfo[]>

返回所有尚未投递的通知。

3. 移除通知

移除所有已投递的通知

方法:

1Notification.removeAllDelivereds(): Promise<void>

移除当前脚本在通知中心中的所有已投递通知。

移除所有待投递的通知

方法:

1Notification.removeAllPendings(): Promise<void>

移除当前脚本所有未投递的通知。

移除指定已投递通知

方法:

1Notification.removeDelivereds(identifiers: string[]): Promise<void>

根据 identifiers 来移除特定已投递的通知。

移除指定待投递通知

方法:

1Notification.removePendings(identifiers: string[]): Promise<void>

根据 identifiers 来移除特定待投递的通知。

4. 设置应用徽章数

方法:

1Notification.setBadgeCount(count: number): Promise<boolean>

更新 Scripting 应用的图标徽章数字。

示例:

1await Notification.setBadgeCount(5)

5. 在通知中展示自定义UI

若在 NotificationScheduleOptions 中将 customUI 设为 true，则通知会支持富文本界面。用户长按或下拉展开通知时，系统会加载并显示 notification.tsx 中定义的自定义组件。

方法:

1Notification.present(element: JSX.Element)

此方法在 notification.tsx 中使用。当用户展开通知时，您可以呈现自定义 UI 元素，以进行更多互动。

在 notification.tsx 中的示例:

1import { Notification, VStack, Text, Button } from 'scripting'
2
3function HydrationNotification() {
4  const handleDrinkWater = () => {
5    console.log("User drank water")
6  }
7
8  const handleIgnore = () => {
9    console.log("User ignored the reminder")
10  }
11
12  return (
13    <VStack>
14      <Text>Remember to stay hydrated!</Text>
15      <Button title="I Drank" action={handleDrinkWater} />
16      <Button title="Ignore" action={handleIgnore} />
17    </VStack>
18  )
19}
20
21Notification.present(<HydrationNotification />)

6. 在自定义UI中获取通知数据

属性:

1Notification.current

当通知打开脚本或者在渲染富通知UI时，您可以通过 Notification.current 获取通知信息。

示例:

1const notificationData = Notification.current
2if (notificationData != null) {
3  console.log(notificationData.title, notificationData.body)
4}

以上文档概述了如何在 Scripting 应用中使用 Notification 模块来发送、管理并自定义具有富交互内容的通知。祝您编码愉快！

大纲