Benachrichtigungen
Native Systembenachrichtigungen mit Aktionsschaltflächen und Texteingabe anzeigen
Einführung
Wails bietet ein umfassendes plattformübergreifendes Benachrichtigungssystem für Desktopanwendungen. Mit diesem Dienst können Sie native Systembenachrichtigungen mit folgenden Funktionen anzeigen:
- Einfache Benachrichtigungen mit Titel, Untertitel und Nachrichtentext
- Interaktive Benachrichtigungen mit Aktionsschaltflächen und Textantworten
- Wiederverwendbare Benachrichtigungskategorien für Aktionen
- Benutzerdefinierte Töne (Standard, stumm oder benannt)
- Anhänge (Bilder auf allen Plattformen; Audio und Video unter macOS)
- Gruppieren zusammengehöriger Benachrichtigungen anhand von
ThreadID - Priorität über
InterruptionLevel(passive/active/timeSensitive/critical) - Geplante Zustellung (nativ unter macOS; prozessinterner Timer unter Windows und Linux)
- Aktualisieren einer bereits versendeten Benachrichtigung anhand ihrer ID
Für jedes neue optionale Feld greift ein geeignetes Rückfallverhalten, wenn eine Plattform es nicht unterstützen kann. Die Unterstützungsmatrix für die einzelnen Funktionen finden Sie unter Plattformhinweise.
Grundlegende Verwendung
Dienst erstellen
Initialisieren Sie zuerst den Benachrichtigungsdienst:
import "github.com/wailsapp/wails/v3/pkg/application"
import "github.com/wailsapp/wails/v3/pkg/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),
},
})Autorisierung von Benachrichtigungen
Unter macOS erfordern Benachrichtigungen die Zustimmung des Benutzers. Fordern Sie die Autorisierung an und prüfen Sie sie:
authorized, err := notifier.CheckNotificationAuthorization()
if err != nil {
// Handle authorization error
}
if authorized {
// Send notifications
} else {
// Request authorization
authorized, err = notifier.RequestNotificationAuthorization()
}Unter Windows und Linux wird immer true zurückgegeben.
Benachrichtigungstypen
Einfache Benachrichtigungen
Senden Sie Benutzern eine einfache Benachrichtigung mit eindeutiger ID, Titel, optionalem Untertitel (macOS und Linux) und Nachrichtentext:
notifier.SendNotification(notifications.NotificationOptions{
ID: "unique-id",
Title: "New Calendar Invite",
Subtitle: "From: Jane Doe", // Optional
Body: "Tap to view the event",
})
Interaktive Benachrichtigungen
Senden Sie eine Benachrichtigung mit Aktionsschaltflächen und Texteingabefeldern. Für diese Benachrichtigungen muss zuerst eine Benachrichtigungskategorie registriert werden:
// 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,
})Reaktionen auf Benachrichtigungen
Verarbeiten Sie Benutzerinteraktionen mit Benachrichtigungen:
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.Event.Emit("notification", result.Response)
})Benachrichtigungen anpassen
Benutzerdefinierte Metadaten
Einfache und interaktive Benachrichtigungen können benutzerdefinierte Daten enthalten:
notifier.SendNotification(notifications.NotificationOptions{
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",
}
})Benutzerdefinierter Ton
Steuern Sie mit Sound, welcher Ton bei der Zustellung einer Benachrichtigung wiedergegeben wird. Wenn Sie das Feld auf nil belassen, wird der Standardton der Plattform wiedergegeben. Mit Silent: true unterdrücken Sie den Ton, mit Name geben Sie einen benannten oder gebündelten Ton wieder.
// Silent
notifier.SendNotification(notifications.NotificationOptions{
ID: "silent-id",
Title: "Background sync complete",
Sound: ¬ifications.NotificationSound{Silent: true},
})
// Named sound
notifier.SendNotification(notifications.NotificationOptions{
ID: "named-id",
Title: "New message",
Body: "Tap to read",
Sound: ¬ifications.NotificationSound{Name: "Ping"},
})So wird Name auf den einzelnen Plattformen aufgelöst:
- macOS —
Namewird an[UNNotificationSound soundNamed:]übergeben. Die Audiodatei muss sich imLibrary/Sounds-Verzeichnis Ihres App-Bundles befinden. - Windows — wenn
Namebereits mitms-winsoundevent:oderms-appx:beginnt, wird der Wert unverändert verwendet. Andernfalls wird er zur Verwendung als Name eines integrierten Toast-Ereignisses inms-winsoundevent:eingeschlossen (siehe Microsofts Dokumentation zum Toast-Schema<audio>). - Linux — der Wert wird als freedesktop-Hinweis
sound-nameweitergeleitet. Ob der Ton wiedergegeben wird, hängt vom aktiven Benachrichtigungsdienst und Klangthema ab.
Anhänge
Mit Attachments werden einer Benachrichtigung Mediendateien hinzugefügt. macOS unterstützt mehrere Anhänge beliebiger Medientypen. Windows und Linux berücksichtigen den ersten als Bild typisierten Anhang.
notifier.SendNotification(notifications.NotificationOptions{
ID: "image-id",
Title: "Photo uploaded",
Body: "Tap to view",
Attachments: []notifications.NotificationAttachment{
{
ID: "preview",
Path: "/absolute/path/to/image.png",
// Type hint:
// macOS: UTI like "public.png" / "public.audio" (often inferred)
// Windows: "hero" | "appLogoOverride" | "inline" (default "inline")
// Linux: ignored
Type: "inline",
},
},
})Path muss ein absoluter Dateisystempfad sein. macOS akzeptiert zusätzlich file://-URLs.
Eine mit Ihrer App ausgelieferte Datei anhängen
Das Betriebssystem liest den Anhang bei der Zustellung der Benachrichtigung vom Datenträger. Daher muss Path auf eine tatsächlich vorhandene Datei auf dem Rechner des Endbenutzers verweisen. Für eine Ressource, die Sie mit der Anwendung bündeln, etwa ein mit go:embed eingebettetes Symbol oder Bild, können Sie keinen festen absoluten Pfad hartcodieren: Die Datei befindet sich innerhalb der Binärdatei und nicht an einem bekannten Speicherort auf dem Datenträger. Schreiben Sie sie beim Start einmalig in ein beschreibbares Verzeichnis und übergeben Sie diesen Pfad:
import (
_ "embed"
"os"
"path/filepath"
)
//go:embed assets/preview.png
var previewPNG []byte
// Materialise the embedded asset to a stable path the OS can read.
previewPath := filepath.Join(os.TempDir(), "myapp-preview.png")
if err := os.WriteFile(previewPath, previewPNG, 0o644); err != nil {
// handle error
}
notifier.SendNotification(notifications.NotificationOptions{
ID: "image-id",
Title: "Photo uploaded",
Body: "Tap to view",
Attachments: []notifications.NotificationAttachment{
{ID: "preview", Path: previewPath, Type: "inline"},
},
})Eine vom Benutzer bereitgestellte oder heruntergeladene Datei besitzt bereits einen tatsächlichen Pfad auf dem Datenträger. Sie können ihn daher ohne diesen Schritt direkt an Path übergeben. Die Übergabe von Anhangsdaten als Bytes im Arbeitsspeicher wird möglicherweise in einer zukünftigen Version ergänzt.
Zusammenfassen und Gruppieren
ThreadID gruppiert zusammengehörige Benachrichtigungen, sodass das Betriebssystem sie in der Mitteilungszentrale bzw. im Info-Center zusammenfassen kann.
notifier.SendNotification(notifications.NotificationOptions{
ID: "msg-42",
Title: "Jane Doe",
Body: "Are you free for lunch?",
ThreadID: "chat:jane.doe",
})Unterbrechungsstufe
InterruptionLevel steuert die Priorität der Benachrichtigung. Verwenden Sie eine der exportierten Konstanten:
notifier.SendNotification(notifications.NotificationOptions{
ID: "alert-id",
Title: "Server down",
Body: "Investigate immediately",
InterruptionLevel: notifications.InterruptionLevelTimeSensitive,
})| Konstante | Wert | Bedeutung |
|---|---|---|
InterruptionLevelPassive |
"passive" |
Unauffällige Zustellung; der Bildschirm wird nicht aktiviert und kein Standardton wiedergegeben |
InterruptionLevelActive |
"active" |
Standardstufe |
InterruptionLevelTimeSensitive |
"timeSensitive" |
Umgeht den Fokusmodus bzw. „Nicht stören“, sofern zulässig |
InterruptionLevelCritical |
"critical" |
Umgeht Fokusmodus und Klingelton- bzw. Stummschaltungseinstellungen; unter macOS ist die Berechtigung für kritische Hinweise erforderlich (ohne sie erfolgt stillschweigend eine Herabstufung) |
Plattformspezifische Zuordnung:
- macOS — legt
UNNotificationContent.interruptionLevelfest.criticalerfordert macOS 12+ und die Berechtigung für kritische Hinweise. - Windows — wird dem Toast-Attribut
<toast scenario="...">zugeordnet. - Linux — wird dem freedesktop-Hinweis
urgencyzugeordnet.
Geplante Zustellung
Schedule verzögert die Zustellung. Legen Sie genau eine der Optionen DelaySeconds (Sekunden ab jetzt) oder At (Unix-Sekunden, UTC) fest.
// Deliver in 60 seconds
notifier.SendNotification(notifications.NotificationOptions{
ID: "reminder-id",
Title: "Stand up and stretch",
Schedule: ¬ifications.NotificationSchedule{DelaySeconds: 60},
})
// Deliver at an absolute time
notifier.SendNotification(notifications.NotificationOptions{
ID: "alarm-id",
Title: "Meeting in 5 minutes",
Schedule: ¬ifications.NotificationSchedule{At: time.Now().Add(time.Hour).Unix()},
})Benachrichtigungen aktualisieren
UpdateNotification ersetzt eine bereits laufende Benachrichtigung mit demselben ID:
notifier.UpdateNotification(notifications.NotificationOptions{
ID: "download-id",
Title: "Download complete",
Body: "report.pdf is ready",
})Plattformspezifisches Verhalten:
- macOS —
UNUserNotificationCenterdedupliziert automatisch anhand der Kennung, sodass die vorhandene Benachrichtigung direkt aktualisiert wird. - Linux — verwendet den D-Bus-Parameter
replaces_id, um die vorherige Benachrichtigung zu ersetzen. - Windows — stellt die Benachrichtigung derzeit erneut als neue Benachrichtigung zu. Ein echtes direktes Ersetzen erfordert vorgelagerte
wintoast-Unterstützung fürtag/group.
Plattformspezifische Aspekte
Unter macOS gelten für Benachrichtigungen folgende Punkte:
- Erfordern die Autorisierung durch den Benutzer
- Erfordern, dass die App paketiert und signiert ist (für die Verteilung notarisiert)
- Verwenden das systemübliche Erscheinungsbild für Benachrichtigungen
- Unterstützen
Subtitle - Unterstützen Texteingaben des Benutzers (Antworten)
- Unterstützen die Aktionsoption
Destructive - Unterstützen mehrere
Attachmentsbeliebiger Medientypen (Bilder, Audio, Video) - Unterstützen
ThreadIDzur Gruppierung in der Mitteilungszentrale - Unterstützen alle
InterruptionLevel-Werte (criticalerfordert die Berechtigung für kritische Hinweise) - Unterstützen native geplante Zustellung, die über App-Neustarts hinweg erhalten bleibt
- Deduplizieren
UpdateNotification-Aufrufe automatisch anhand vonID - Berücksichtigen den dunklen und hellen Modus automatisch
Unter Windows gelten für Benachrichtigungen folgende Punkte:
- Verwenden über das
wintoast-Backend die Windows-systemeigenen Toast-Stile - Passen sich an die Windows-Designeinstellungen an
- Unterstützen Texteingaben des Benutzers (Antworten)
- Unterstützen Anzeigen mit hoher DPI-Dichte
- Unterstützen
Subtitlenicht - Unterstützen ein einzelnes Bild-
Attachmentmit dem Platzierungshinweishero,appLogoOverrideoderinline(Standard:inline) - Unterstützen
ThreadIDzur Gruppierung im Info-Center - Unterstützen
InterruptionLevelüber das Toast-Attributscenario - Unterstützen geplante Zustellung über einen prozessinternen Timer — geplante Benachrichtigungen gehen verloren, wenn die App vor der Zustellung beendet wird
UpdateNotificationstellt die Benachrichtigung derzeit erneut als neue Benachrichtigung zu (echtes direktes Ersetzen steht aus, bis die vorgelagertewintoast-Unterstützung fürtag/groupverfügbar ist)
Unter Linux verwenden Benachrichtigungen die D-Bus-Schnittstelle org.freedesktop.Notifications. Damit Benachrichtigungen funktionieren, muss ein kompatibler Benachrichtigungs-Daemon ausgeführt werden.
Unter Linux gelten für Benachrichtigungen folgende Punkte:
- Übernehmen das Design der Desktopumgebung
- Werden gemäß den Regeln der Desktopumgebung positioniert
- Unterstützen
Subtitle(wird bei Daemons, die es nicht separat darstellen, mit dem Textkörper verkettet) - Unterstützen keine Texteingaben des Benutzers (nicht Bestandteil der freedesktop-Spezifikation)
- Unterstützen ein einzelnes Bild-
Attachmentüber den Hinweisimage-path - Unterstützt
ThreadID(wird, sofern unterstützt, vom Daemon verarbeitet) Sound.Namewird als Hinweissound-nameweitergeleitet; ob der Sound abgespielt wird, hängt vom aktiven Daemon und Soundthema ab- Ordnet
InterruptionLeveldem freedesktop-Hinweisurgencyzu - Unterstützt die geplante Zustellung über einen prozessinternen Timer – geplante Benachrichtigungen gehen verloren, wenn die App vor der Zustellung beendet wird
UpdateNotificationverwendet den D-Bus-Parameterreplaces_id, um die vorherige Benachrichtigung direkt zu ersetzen
Bewährte Verfahren
- Berechtigung prüfen und anfordern:
- macOS erfordert die Berechtigung des Benutzers
- Klare und prägnante Benachrichtigungen bereitstellen:
- Aussagekräftige Titel, Untertitel, Texte und Aktionsbezeichnungen verwenden
- Benachrichtigungsantworten angemessen verarbeiten:
- Benachrichtigungsantworten auf Fehler prüfen
- Rückmeldung zu Benutzeraktionen geben
- Plattformkonventionen berücksichtigen:
- Plattformspezifische Benachrichtigungsmuster befolgen
- Systemeinstellungen berücksichtigen
- Unter Linux die Abhängigkeit vom Daemon berücksichtigen:
- Den von
SendNotificationzurückgegebenen Fehler prüfen – ein fehlender Daemon verursacht einen D-Bus-Fehler - In der Paketdokumentation oder README-Datei der App sollte darauf hingewiesen werden, dass ein freedesktop-Benachrichtigungs-Daemon erforderlich ist
Beispiele
Dieses Beispiel ansehen:
API-Referenz
Dienstverwaltung
| Methode | Beschreibung |
|---|---|
New() |
Erstellt einen neuen Benachrichtigungsdienst |
Benachrichtigungsberechtigung
| Methode | Beschreibung |
|---|---|
RequestNotificationAuthorization() |
Fordert die Berechtigung zum Anzeigen von Benachrichtigungen an (macOS) |
CheckNotificationAuthorization() |
Prüft den aktuellen Status der Benachrichtigungsberechtigung (macOS) |
Benachrichtigungen senden
| Methode | Beschreibung |
|---|---|
SendNotification(options NotificationOptions) |
Sendet eine einfache Benachrichtigung |
SendNotificationWithActions(options NotificationOptions) |
Sendet eine interaktive Benachrichtigung mit Aktionen |
UpdateNotification(options NotificationOptions) |
Aktualisiert eine noch nicht abgeschlossene Benachrichtigung anhand von ID (siehe Benachrichtigungen aktualisieren) |
Benachrichtigungskategorien
| Methode | Beschreibung |
|---|---|
RegisterNotificationCategory(category NotificationCategory) |
Registriert eine wiederverwendbare Benachrichtigungskategorie |
RemoveNotificationCategory(categoryID string) |
Entfernt eine zuvor registrierte Kategorie |
Benachrichtigungen verwalten
| Methode | Beschreibung |
|---|---|
RemoveAllPendingNotifications() |
Entfernt alle ausstehenden Benachrichtigungen (nur macOS und Linux) |
RemovePendingNotification(identifier string) |
Entfernt eine bestimmte ausstehende Benachrichtigung (nur macOS und Linux) |
RemoveAllDeliveredNotifications() |
Entfernt alle zugestellten Benachrichtigungen (nur macOS und Linux) |
RemoveDeliveredNotification(identifier string) |
Entfernt eine bestimmte zugestellte Benachrichtigung (nur macOS und Linux) |
RemoveNotification(identifier string) |
Entfernt eine Benachrichtigung (Linux-spezifisch) |
Ereignisverarbeitung
| Methode | Beschreibung |
|---|---|
OnNotificationResponse(callback func(result NotificationResult)) |
Registriert eine Callback-Funktion für Benachrichtigungsantworten |
Strukturen und Typen
NotificationOptions
type NotificationOptions struct {
ID string // Unique identifier for the notification (required)
Title string // Main notification title (required)
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
// Sound controls the sound played on delivery. nil = platform default.
Sound *NotificationSound
// Attachments are media files shown alongside the notification.
// macOS supports multiple attachments of any media type;
// Windows and Linux honour the first image-typed attachment.
Attachments []NotificationAttachment
// ThreadID groups related notifications together in
// Notification Center / Action Center / the Linux notification daemon.
ThreadID string
// InterruptionLevel controls priority. One of "passive",
// "active" (default), "timeSensitive", "critical".
InterruptionLevel string
// Schedule defers delivery. macOS uses a native trigger that survives
// restarts; Windows and Linux use an in-process timer that does NOT.
Schedule *NotificationSchedule
}NotificationSound
type NotificationSound struct {
Silent bool // If true, no sound is played
Name string // Named/bundled sound (see "Custom Sound" above)
}NotificationAttachment
type NotificationAttachment struct {
ID string // Optional identifier
Path string // Absolute filesystem path (macOS also accepts file:// URLs)
// Type is an optional placement/UTI hint:
// macOS: UTI like "public.png" / "public.audio" (often inferred)
// Windows: "hero" | "appLogoOverride" | "inline" (default "inline")
// Linux: ignored (always image-path hint)
Type string
}NotificationSchedule
// Exactly one of DelaySeconds or At must be set. At is Unix seconds (UTC).
type NotificationSchedule struct {
DelaySeconds int // Seconds from now until delivery
At int64 // Absolute Unix timestamp (seconds, UTC)
}InterruptionLevel-Konstanten
const (
InterruptionLevelPassive = "passive"
InterruptionLevelActive = "active" // default
InterruptionLevelTimeSensitive = "timeSensitive"
InterruptionLevelCritical = "critical"
)NotificationCategory
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
type NotificationAction struct {
ID string // Unique identifier for the action
Title string // Button text
Destructive bool // Whether the action is destructive (macOS-specific)
}NotificationResponse
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
type NotificationResult struct {
Response NotificationResponse // Response data
Error error // Any error that occurred
}