mirror of
https://github.com/wailsapp/wails.git
synced 2026-03-14 14:45:49 +01:00
update docs/changelog
This commit is contained in:
popaprozac
parent
1db65a84c3
commit
743882a9b9
2 changed files with 305 additions and 0 deletions
|
|
@ -76,6 +76,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
- Add cancellation support for query methods on `sqlite` service by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
|
||||
- Add prepared statement support to `sqlite` service with JS bindings by [@fbbdev](https://github.com/fbbdev) in [#4067](https://github.com/wailsapp/wails/pull/4067)
|
||||
- Add `SetMenu()` on window to allow for setting a menu on a window by [@leaanthony](https://github.com/leaanthony)
|
||||
- Add Notification support by [@popaprozac] in [#4098](https://github.com/wailsapp/wails/pull/4098)
|
||||
|
||||
### Fixed
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,304 @@
|
|||
---
|
||||
title: Notifications
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from "@astrojs/starlight/components";
|
||||
|
||||
## Introduction
|
||||
|
||||
Wails provides a comprehensive cross-platform notification system for desktop applications. This service allows you to display native system notifications, with support for interactive elements like action buttons and text input fields.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### Creating the Service
|
||||
|
||||
First, initialize the notifications service:
|
||||
|
||||
```go
|
||||
import "github.com/wailsapp/wails/v3/pkg/application"
|
||||
import "github.com/wailsapp/wails/v3/services/notifications"
|
||||
|
||||
// Create a new notification service
|
||||
notifier := notifications.New()
|
||||
|
||||
//Register the service with the application
|
||||
app := application.New(application.Options{
|
||||
Services: []application.Service{
|
||||
application.NewService(notifier),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Notification Authorization
|
||||
|
||||
Notifications on macOS require user authorization. Request and check authorization:
|
||||
|
||||
```go
|
||||
authorized, err := notifier.CheckNotificationAuthorization()
|
||||
if err != nil {
|
||||
// Handle authorization error
|
||||
}
|
||||
if authorized {
|
||||
// Send notifications
|
||||
} else {
|
||||
// Request authorization
|
||||
authorized, err = notifier.RequestNotificationAuthorization()
|
||||
}
|
||||
```
|
||||
On Windows and Linux this always returns `true`.
|
||||
|
||||
## Notification Types
|
||||
|
||||
### Basic Notifications
|
||||
|
||||
Send a basic notification with a unique id, title, optional subtitle (macOS and Linux), and body text to users:
|
||||
|
||||
```go
|
||||
notifier.SendNotification(notifications.NotificaionOptions{
|
||||
ID: "unique-id",
|
||||
Title: "New Calendar Invite",
|
||||
Subtitle: "From: Jane Doe", // Optional
|
||||
Body: "Tap to view the event"
|
||||
})
|
||||
|
||||
```
|
||||
|
||||
### Interactive Notifications
|
||||
Send a notification with action buttons and text inputs. These notifications require a notification category to be resgistered first:
|
||||
|
||||
```go
|
||||
// Define a unique category id
|
||||
categoryID := "unique-category-id"
|
||||
|
||||
// Define a category with actions
|
||||
category := notifications.NotificationCategory{
|
||||
ID: categoryID,
|
||||
Actions: []notifications.NotificationAction{
|
||||
{
|
||||
ID: "OPEN",
|
||||
Title: "Open",
|
||||
},
|
||||
{
|
||||
ID: "ARCHIVE",
|
||||
Title: "Archive",
|
||||
Destructive: true, /* macOS-specific */
|
||||
},
|
||||
},
|
||||
HasReplyField: true,
|
||||
ReplyPlaceholder: "message...",
|
||||
ReplyButtonTitle: "Reply",
|
||||
}
|
||||
|
||||
// Register the category
|
||||
notifier.RegisterNotificationCategory(category)
|
||||
|
||||
// Send an interactive notification with the actions registered in the provided category
|
||||
notifier.SendNotificationWithActions(notifications.NotificationOptions{
|
||||
ID: "unique-id",
|
||||
Title: "New Message",
|
||||
Subtitle: "From: Jane Doe",
|
||||
Body: "Are you able to make it?",
|
||||
CategoryID: categoryID,
|
||||
})
|
||||
```
|
||||
|
||||
## Notification Responses
|
||||
|
||||
Process user interactions with notifications:
|
||||
|
||||
```go
|
||||
notifier.OnNotificationResponse(func(result notifications.NotificationResult) {
|
||||
response := result.Response
|
||||
fmt.Printf("Notification %s was actioned with: %s\n", response.ID, response.ActionIdentifier)
|
||||
|
||||
if response.ActionIdentifier == "TEXT_REPLY" {
|
||||
fmt.Printf("User replied: %s\n", response.UserText)
|
||||
}
|
||||
|
||||
if data, ok := response.UserInfo["sender"].(string); ok {
|
||||
fmt.Printf("Original sender: %s\n", data)
|
||||
}
|
||||
|
||||
// Emit an event to the frontend
|
||||
app.EmitEvent("notification", result.Response)
|
||||
})
|
||||
```
|
||||
|
||||
## Notification Customisation
|
||||
|
||||
### Custom Metadata
|
||||
|
||||
Basic and interactive notifications can include custom data:
|
||||
|
||||
```go
|
||||
notifier.SendNotification(notifications.NotificaionOptions{
|
||||
ID: "unique-id",
|
||||
Title: "New Calendar Invite",
|
||||
Subtitle: "From: Jane Doe", // Optional
|
||||
Body: "Tap to view the event"
|
||||
Data: map[string]interface{}{
|
||||
sender: "jane.doe@example.com",
|
||||
timestamp: "2025-03-10T15:30:00Z",
|
||||
}
|
||||
})
|
||||
|
||||
```
|
||||
|
||||
## Platform Considerations
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="macOS" icon="fa-brands:apple">
|
||||
|
||||
On macOS, notifications:
|
||||
|
||||
- Require user authorization
|
||||
- Require the app to be notorized for distribution
|
||||
- Use system-standard notification appearances
|
||||
- Support `subtitle`
|
||||
- Support user text input
|
||||
- Support the `Destructive` action option
|
||||
- Automatically handle dark/light mode
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Windows" icon="fa-brands:windows">
|
||||
|
||||
On Windows, notifications:
|
||||
|
||||
- Use Windows system toast styles
|
||||
- Adapt to Windows theme settings
|
||||
- Support user text input
|
||||
- Support high DPI displays
|
||||
- Do not support `subtitle`
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Linux" icon="fa-brands:linux">
|
||||
|
||||
On Linux, dialog behaviour depends on the desktop environment:
|
||||
|
||||
- Use native notifications when available
|
||||
- Follow desktop environment theme
|
||||
- Position according to desktop environment rules
|
||||
- Support `subtitle`
|
||||
- Do not support user text input
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Check and request for authorization:
|
||||
- macOS requires user authorization
|
||||
|
||||
2. Provide clear and concise notifications:
|
||||
- Use descriptive titles, subtitles, text, and action titles
|
||||
|
||||
3. Handle dialog responses appropriately:
|
||||
- Check for errors in notification responses
|
||||
- Provide feedback for user actions
|
||||
|
||||
4. Consider platform conventions:
|
||||
- Follow platform-specific notification patterns
|
||||
- Respect system settings
|
||||
|
||||
## Examples
|
||||
|
||||
Explore this example:
|
||||
|
||||
- [Notifications](/examples/notifications)
|
||||
|
||||
## API Reference
|
||||
|
||||
### Service Management
|
||||
| Method | Description |
|
||||
|--------------------------------------------|-------------------------------------------------------|
|
||||
| `New()` | Creates a new notifications service |
|
||||
|
||||
### Notification Authorization
|
||||
| Method | Description |
|
||||
|----------------------------------------------|------------------------------------------------------------|
|
||||
| `RequestNotificationAuthorization()` | Requests permission to display notifications (macOS) |
|
||||
| `CheckNotificationAuthorization()` | Checks current notification authorization status (macOS) |
|
||||
|
||||
### Sending Notifications
|
||||
| Method | Description |
|
||||
|------------------------------------------------------------|---------------------------------------------------|
|
||||
| `SendNotification(options NotificationOptions)` | Sends a basic notification |
|
||||
| `SendNotificationWithActions(options NotificationOptions)` | Sends an interactive notification with actions |
|
||||
|
||||
### Notification Categories
|
||||
| Method | Description |
|
||||
|---------------------------------------------------------------|---------------------------------------------------|
|
||||
| `RegisterNotificationCategory(category NotificationCategory)` | Registers a reusable notification category |
|
||||
| `RemoveNotificationCategory(categoryID string)` | Removes a previously registered category |
|
||||
|
||||
### Managing Notifications
|
||||
| Method | Description |
|
||||
|-------------------------------------------------|---------------------------------------------------------------------|
|
||||
| `RemoveAllPendingNotifications()` | Removes all pending notifications (macOS and Linux only) |
|
||||
| `RemovePendingNotification(identifier string)` | Removes a specific pending notification (macOS and Linux only) |
|
||||
| `RemoveAllDeliveredNotifications()` | Removes all delivered notifications (macOS and Linux only) |
|
||||
| `RemoveDeliveredNotification(identifier string)`| Removes a specific delivered notification (macOS and Linux only) |
|
||||
| `RemoveNotification(identifier string)` | Removes a notification (Linux-specific) |
|
||||
|
||||
### Event Handling
|
||||
| Method | Description |
|
||||
|--------------------------------------------------------------------|-------------------------------------------------|
|
||||
| `OnNotificationResponse(callback func(result NotificationResult))` | Registers a callback for notification responses |
|
||||
|
||||
### Structs and Types
|
||||
|
||||
#### NotificationOptions
|
||||
```go
|
||||
type NotificationOptions struct {
|
||||
ID string // Unique identifier for the notification
|
||||
Title string // Main notification title
|
||||
Subtitle string // Subtitle text (macOS and Linux only)
|
||||
Body string // Main notification content
|
||||
CategoryID string // Category identifier for interactive notifications
|
||||
Data map[string]interface{} // Custom data to associate with the notification
|
||||
}
|
||||
```
|
||||
|
||||
#### NotificationCategory
|
||||
```go
|
||||
type NotificationCategory struct {
|
||||
ID string // Unique identifier for the category
|
||||
Actions []NotificationAction // Button actions for the notification
|
||||
HasReplyField bool // Whether to include a text input field
|
||||
ReplyPlaceholder string // Placeholder text for the input field
|
||||
ReplyButtonTitle string // Text for the reply button
|
||||
}
|
||||
```
|
||||
|
||||
#### NotificationAction
|
||||
```go
|
||||
type NotificationAction struct {
|
||||
ID string // Unique identifier for the action
|
||||
Title string // Button text
|
||||
Destructive bool // Whether the action is destructive (macOS-specific)
|
||||
}
|
||||
```
|
||||
|
||||
#### NotificationResponse
|
||||
```go
|
||||
type NotificationResponse struct {
|
||||
ID string // Notification identifier
|
||||
ActionIdentifier string // Action that was triggered
|
||||
CategoryID string // Category of the notification
|
||||
Title string // Title of the notification
|
||||
Subtitle string // Subtitle of the notification
|
||||
Body string // Body text of the notification
|
||||
UserText string // Text entered by the user
|
||||
UserInfo map[string]interface{} // Custom data from the notification
|
||||
}
|
||||
```
|
||||
|
||||
#### NotificationResult
|
||||
```go
|
||||
type NotificationResult struct {
|
||||
Response NotificationResponse // Response data
|
||||
Error error // Any error that occurred
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue