CalvinBackup/tauri-plugins-workspace
1
0
Fork 0
mirror of https://github.com/tauri-apps/plugins-workspace.git synced 2026-09-22 21:30:44 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore: update documentation

Browse Source
This commit is contained in:
Lucas Nogueira
2026-09-22 11:30:47 -03:00
parent d869c162a7
commit a87a3c7d44
104 changed files with 4875 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/notification/guest-js/index.ts
+365 -5
View File
@@ -35,7 +35,7 @@ interface Options {
*/
channelId?: string
/**
* Notification title.
* The title displayed on the notification.
*/
title: string
/**
@@ -139,11 +139,28 @@ interface Options {
number?: number
}
/**
* The set of date fields a scheduled notification must match to be delivered.
*
* Fields that are not set match any value, so the notification fires on every date
* whose remaining components match.
*/
interface ScheduleInterval {
/**
* The year the notification fires on.
*/
year?: number
/**
* The month of the year the notification fires on.
*/
month?: number
/**
* The day of the month the notification fires on.
*/
day?: number
/**
* The day of the week the notification fires on.
*
* 1 - Sunday
* 2 - Monday
* 3 - Tuesday
@@ -153,26 +170,77 @@ interface ScheduleInterval {
* 7 - Saturday
*/
weekday?: number
/**
* The hour of the day the notification fires on, in the 24-hour clock.
*/
hour?: number
/**
* The minute of the hour the notification fires on.
*/
minute?: number
/**
* The second of the minute the notification fires on.
*/
second?: number
}
/**
* The unit of the repeating interval used by {@link Schedule.every}.
*/
enum ScheduleEvery {
/**
* The notification repeats every year.
*
* On Android a year is approximated as 52 weeks.
*/
Year = 'year',
/**
* The notification repeats every month.
*
* On Android a month is approximated as 30 days.
*/
Month = 'month',
/**
* The notification repeats every two weeks.
*/
TwoWeeks = 'twoWeeks',
/**
* The notification repeats every week.
*/
Week = 'week',
/**
* The notification repeats every day.
*/
Day = 'day',
/**
* The notification repeats every hour.
*/
Hour = 'hour',
/**
* The notification repeats every minute.
*/
Minute = 'minute',
/**
* Not supported on iOS.
* The notification repeats every second.
*
* Not supported on iOS, where repeating triggers must be at least a minute apart.
*/
Second = 'second'
}
/**
* Defines when a scheduled notification is delivered.
*
* Build one with the static {@link Schedule.at}, {@link Schedule.interval} and
* {@link Schedule.every} helpers, then pass it to the `schedule` option of a notification.
* Scheduling is only supported on mobile; desktop notifications are always shown immediately.
*
* @since 2.0.0
*/
class Schedule {
/**
* Set when the notification fires at a fixed date and time.
*/
at:
| {
date: Date
@@ -181,6 +249,9 @@ class Schedule {
}
| undefined
/**
* Set when the notification fires whenever the current date matches the given fields.
*/
interval:
| {
interval: ScheduleInterval
@@ -188,6 +259,9 @@ class Schedule {
}
| undefined
/**
* Set when the notification repeats on a fixed interval.
*/
every:
| {
interval: ScheduleEvery
@@ -196,6 +270,22 @@ class Schedule {
}
| undefined
/**
* Creates a schedule that fires the notification at the given date and time.
*
* @example
* ```typescript
* import { Schedule, sendNotification } from '@tauri-apps/plugin-notification';
* const schedule = Schedule.at(new Date(Date.now() + 60 * 1000));
* sendNotification({ title: 'Tauri', body: 'One minute later', schedule });
* ```
*
* @param date The date and time the notification fires at. It must be in the future.
* @param repeating Whether the notification keeps repeating, using the duration between the moment it is scheduled and `date` as the interval. The interval must be at least one minute on iOS.
* @param allowWhileIdle Whether the notification is allowed to fire while the device is in low-power idle (Doze) mode. Android only.
*
* @returns A schedule that can be assigned to the `schedule` option of a notification.
*/
static at(date: Date, repeating = false, allowWhileIdle = false): Schedule {
return {
at: { date, repeating, allowWhileIdle },
@@ -204,6 +294,23 @@ class Schedule {
}
}
/**
* Creates a schedule that fires the notification whenever the current date matches
* every field set on the given interval.
*
* @example
* ```typescript
* import { Schedule, sendNotification } from '@tauri-apps/plugin-notification';
* // fires every day at 9:00
* const schedule = Schedule.interval({ hour: 9, minute: 0 });
* sendNotification({ title: 'Tauri', body: 'Good morning', schedule });
* ```
*
* @param interval The date fields the current date must match for the notification to fire.
* @param allowWhileIdle Whether the notification is allowed to fire while the device is in low-power idle (Doze) mode. Android only.
*
* @returns A schedule that can be assigned to the `schedule` option of a notification.
*/
static interval(
interval: ScheduleInterval,
allowWhileIdle = false
@@ -215,6 +322,22 @@ class Schedule {
}
}
/**
* Creates a schedule that repeatedly fires the notification, once every `count` interval units.
*
* @example
* ```typescript
* import { Schedule, ScheduleEvery, sendNotification } from '@tauri-apps/plugin-notification';
* const schedule = Schedule.every(ScheduleEvery.Hour, 2);
* sendNotification({ title: 'Tauri', body: 'Every two hours', schedule });
* ```
*
* @param kind The unit of the repeating interval.
* @param count How many interval units elapse between each notification.
* @param allowWhileIdle Whether the notification is allowed to fire while the device is in low-power idle (Doze) mode. Android only.
*
* @returns A schedule that can be assigned to the `schedule` option of a notification.
*/
static every(
kind: ScheduleEvery,
count: number,
@@ -238,17 +361,53 @@ interface Attachment {
url: string
}
/**
* A button the user can tap on a notification, belonging to an {@link ActionType}.
*
* Only used on mobile. On Android only the identifier, the title and the input flag are used.
*/
interface Action {
/**
* The identifier of this action, reported back when the user triggers it.
*/
id: string
/**
* The text displayed on the action button.
*/
title: string
/**
* Whether the device must be unlocked for the action to run. iOS only.
*/
requiresAuthentication?: boolean
/**
* Whether the app is brought to the foreground when the action is triggered. iOS only.
*/
foreground?: boolean
/**
* Whether the action is displayed as destructive, usually in red. iOS only.
*/
destructive?: boolean
/**
* Whether triggering the action lets the user type a text response.
*/
input?: boolean
/**
* The text displayed on the button that submits the text input. iOS only.
*/
inputButtonTitle?: string
/**
* The placeholder displayed on the empty text input field. iOS only.
*/
inputPlaceholder?: string
}
/**
* A group of {@link Action}s a notification can display, referenced by the
* `actionTypeId` option of a notification.
*
* Register it with {@link registerActionTypes} before sending a notification that uses it.
* Only used on mobile.
*/
interface ActionType {
/**
* The identifier of this action type
@@ -258,58 +417,206 @@ interface ActionType {
* The list of associated actions
*/
actions: Action[]
/**
* The placeholder shown instead of the notification body when previews are hidden. iOS only.
*/
hiddenPreviewsBodyPlaceholder?: string
/**
* Whether the app is notified when the user dismisses the notification. iOS only.
*/
customDismissAction?: boolean
/**
* Whether the notification can be displayed in a CarPlay environment. iOS only.
*/
allowInCarPlay?: boolean
/**
* Whether the notification title is shown even when previews are hidden. iOS only.
*/
hiddenPreviewsShowTitle?: boolean
/**
* Whether the notification subtitle is shown even when previews are hidden. iOS only.
*/
hiddenPreviewsShowSubtitle?: boolean
}
/**
* A notification that was scheduled and has not been delivered yet.
*
* Returned by {@link pending}, which is only supported on mobile.
*/
interface PendingNotification {
/**
* The identifier of the notification.
*/
id: number
/**
* The title of the notification, if it was set.
*/
title?: string
/**
* The body of the notification, if it was set.
*/
body?: string
/**
* The schedule that determines when the notification is delivered.
*/
schedule: Schedule
}
/**
* A notification that was delivered and is still visible in the notification center.
*
* Returned by {@link active}, which is only supported on mobile. Which fields are
* populated depends on the platform, since Android and iOS expose different
* information about delivered notifications.
*/
interface ActiveNotification {
/**
* The identifier of the notification.
*/
id: number
/**
* The tag the notification was posted with. Android only.
*/
tag?: string
/**
* The title of the notification, if it was set.
*/
title?: string
/**
* The body of the notification, if it was set.
*/
body?: string
/**
* The identifier of the group the notification belongs to. Android only.
*/
group?: string
/**
* Whether the notification is the summary of its group. Android only.
*/
groupSummary: boolean
/**
* The platform extras attached to the notification, as string values. Android only.
*/
data: Record<string, string>
/**
* The extra payload that was stored in the notification.
*/
extra: Record<string, unknown>
/**
* The attachments of the notification. iOS only.
*/
attachments: Attachment[]
/**
* The identifier of the action type the notification was registered with. iOS only.
*/
actionTypeId?: string
/**
* The schedule the notification was delivered with, if it was scheduled.
*/
schedule?: Schedule
/**
* The sound resource name of the notification. iOS only.
*/
sound?: string
}
/**
* How much the notifications of a {@link Channel} interrupt the user.
*
* It maps to the Android `NotificationManager.IMPORTANCE_*` constants and is only used on Android.
*/
enum Importance {
/**
* The notifications are not shown.
*/
None = 0,
/**
* The notifications are only shown in the shade, below the fold, without a status bar icon.
*/
Min,
/**
* The notifications are shown without a sound.
*/
Low,
/**
* The notifications are shown and make a sound.
*
* This is the value used when the channel does not define an importance.
*/
Default,
/**
* The notifications are shown, make a sound and pop up as a heads-up notification.
*/
High
}
/**
* How much of a notification is shown on the lock screen.
*
* It maps to the Android `Notification.VISIBILITY_*` constants and is only used on Android.
*/
enum Visibility {
/**
* The notification is not shown on the lock screen at all.
*/
Secret = -1,
/**
* The notification is shown on the lock screen with its sensitive content hidden.
*
* This is the value used when the channel does not define a visibility.
*/
Private,
/**
* The notification is shown in full on the lock screen.
*/
Public
}
/**
* A notification channel, the category users configure notification behavior on.
*
* Notifications reference a channel through their `channelId` option and are not delivered
* when the channel does not exist. Channels are only supported on Android.
*/
interface Channel {
/**
* The identifier of this channel.
*/
id: string
/**
* The user visible name of this channel.
*/
name: string
/**
* The user visible description of this channel.
*/
description?: string
/**
* The name of the sound resource played by the notifications of this channel.
*
* The resource must be placed in the app's `res/raw` folder.
*/
sound?: string
/**
* Whether the notifications of this channel blink the device light.
*/
lights?: boolean
/**
* The color of the device light, as a color string such as `#ff0000`.
*/
lightColor?: string
/**
* Whether the notifications of this channel vibrate the device.
*/
vibration?: boolean
/**
* How much the notifications of this channel interrupt the user.
*/
importance?: Importance
/**
* How much of the notifications of this channel is shown on the lock screen.
*/
visibility?: Visibility
}
@@ -321,6 +628,8 @@ interface Channel {
* const permissionGranted = await isPermissionGranted();
* ```
*
* @returns A promise resolving to whether the permission to send notifications is granted.
*
* @since 2.0.0
*/
async function isPermissionGranted(): Promise<boolean> {
@@ -366,6 +675,8 @@ async function requestPermission(): Promise<NotificationPermission> {
* }
* ```
*
* @param options The notification content, or the notification title when a string is given.
*
* @since 2.0.0
*/
function sendNotification(options: Options | string): void {
@@ -391,6 +702,8 @@ function sendNotification(options: Options | string): void {
* }])
* ```
*
* @param types The action types to register.
*
* @returns A promise indicating the success or failure of the operation.
*
* @since 2.0.0
@@ -425,6 +738,8 @@ async function pending(): Promise<PendingNotification[]> {
* await cancel([-34234, 23432, 4311]);
* ```
*
* @param notifications The identifiers of the pending notifications to cancel.
*
* @returns A promise indicating the success or failure of the operation.
*
* @since 2.0.0
@@ -472,10 +787,12 @@ async function active(): Promise<ActiveNotification[]> {
*
* @example
* ```typescript
* import { cancel } from '@tauri-apps/plugin-notification';
* await cancel([-34234, 23432, 4311])
* import { removeActive } from '@tauri-apps/plugin-notification';
* await removeActive([{ id: -34234 }, { id: 23432 }, { id: 4311 }])
* ```
*
* @param notifications The active notifications to remove, identified by their id and, on Android, their optional tag.
*
* @returns A promise indicating the success or failure of the operation.
*
* @since 2.0.0
@@ -519,6 +836,8 @@ async function removeAllActive(): Promise<void> {
* });
* ```
*
* @param channel The channel to create.
*
* @returns A promise indicating the success or failure of the operation.
*
* @since 2.0.0
@@ -533,9 +852,11 @@ async function createChannel(channel: Channel): Promise<void> {
* @example
* ```typescript
* import { removeChannel } from '@tauri-apps/plugin-notification';
* await removeChannel();
* await removeChannel('new-messages');
* ```
*
* @param id The identifier of the channel to remove.
*
* @returns A promise indicating the success or failure of the operation.
*
* @since 2.0.0
@@ -561,12 +882,51 @@ async function channels(): Promise<Channel[]> {
return await invoke('plugin:notification|listChannels')
}
/**
* Listens to notifications that are delivered while the app is running.
*
* Only emitted on mobile.
*
* @example
* ```typescript
* import { onNotificationReceived } from '@tauri-apps/plugin-notification';
* const unlisten = await onNotificationReceived((notification) => {
* console.log(`received notification: ${notification.title}`);
* });
* ```
*
* @param cb The closure called with the notification that was delivered.
*
* @returns A promise resolving to a listener that can be used to stop listening for the event.
*
* @since 2.0.0
*/
async function onNotificationReceived(
cb: (notification: Options) => void
): Promise<PluginListener> {
return await addPluginListener('notification', 'notification', cb)
}
/**
* Listens to the actions the user performs on a notification.
*
* Only emitted on mobile, for notifications that reference an action type
* registered with {@link registerActionTypes}.
*
* @example
* ```typescript
* import { onAction } from '@tauri-apps/plugin-notification';
* const unlisten = await onAction((notification) => {
* console.log(`user acted on notification: ${notification.title}`);
* });
* ```
*
* @param cb The closure called with the notification the action was performed on.
*
* @returns A promise resolving to a listener that can be used to stop listening for the event.
*
* @since 2.0.0
*/
async function onAction(
cb: (notification: Options) => void
): Promise<PluginListener> {
plugins/notification/guest-js/init.ts
+11
View File
@@ -2,6 +2,17 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
/**
* Webview script injected by the notification plugin.
*
* It replaces `window.Notification` with an implementation backed by the plugin, so the
* standard Notification Web API sends OS notifications, and keeps
* `window.Notification.permission` and `window.Notification.requestPermission` in sync
* with the permission state reported by the plugin.
*
* @module
*/
import { invoke } from '@tauri-apps/api/core'
import type { PermissionState } from '@tauri-apps/api/core'
import type { Options } from './index'