Mitwirken

Diese Dokumentation bearbeiten

Übersetzen Sie die Dokumentation oder öffnen Sie das vollständige Projekt auf Ihrem Computer.

Es wird nichts veröffentlicht, bevor Sie Ihre Arbeit zur Übermittlung freigeben.

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:

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:

go
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:

go
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:

go
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:

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,
})

Reaktionen auf Benachrichtigungen

Verarbeiten Sie Benutzerinteraktionen mit Benachrichtigungen:

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.Event.Emit("notification", result.Response)
})

Benachrichtigungen anpassen

Benutzerdefinierte Metadaten

Einfache und interaktive Benachrichtigungen können benutzerdefinierte Daten enthalten:

go
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.

go
// Silent
notifier.SendNotification(notifications.NotificationOptions{
    ID:    "silent-id",
    Title: "Background sync complete",
    Sound: &notifications.NotificationSound{Silent: true},
})

// Named sound
notifier.SendNotification(notifications.NotificationOptions{
    ID:    "named-id",
    Title: "New message",
    Body:  "Tap to read",
    Sound: &notifications.NotificationSound{Name: "Ping"},
})

So wird Name auf den einzelnen Plattformen aufgelöst:

  • macOS — Name wird an [UNNotificationSound soundNamed:] übergeben. Die Audiodatei muss sich im Library/Sounds-Verzeichnis Ihres App-Bundles befinden.
  • Windows — wenn Name bereits mit ms-winsoundevent: oder ms-appx: beginnt, wird der Wert unverändert verwendet. Andernfalls wird er zur Verwendung als Name eines integrierten Toast-Ereignisses in ms-winsoundevent: eingeschlossen (siehe Microsofts Dokumentation zum Toast-Schema <audio>).
  • Linux — der Wert wird als freedesktop-Hinweis sound-name weitergeleitet. 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.

go
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:

go
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.

go
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:

go
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.interruptionLevel fest. critical erfordert macOS 12+ und die Berechtigung für kritische Hinweise.
  • Windows — wird dem Toast-Attribut <toast scenario="..."> zugeordnet.
  • Linux — wird dem freedesktop-Hinweis urgency zugeordnet.

Geplante Zustellung

Schedule verzögert die Zustellung. Legen Sie genau eine der Optionen DelaySeconds (Sekunden ab jetzt) oder At (Unix-Sekunden, UTC) fest.

go
// Deliver in 60 seconds
notifier.SendNotification(notifications.NotificationOptions{
    ID:       "reminder-id",
    Title:    "Stand up and stretch",
    Schedule: &notifications.NotificationSchedule{DelaySeconds: 60},
})

// Deliver at an absolute time
notifier.SendNotification(notifications.NotificationOptions{
    ID:       "alarm-id",
    Title:    "Meeting in 5 minutes",
    Schedule: &notifications.NotificationSchedule{At: time.Now().Add(time.Hour).Unix()},
})

Benachrichtigungen aktualisieren

UpdateNotification ersetzt eine bereits laufende Benachrichtigung mit demselben ID:

go
notifier.UpdateNotification(notifications.NotificationOptions{
    ID:    "download-id",
    Title: "Download complete",
    Body:  "report.pdf is ready",
})

Plattformspezifisches Verhalten:

  • macOS — UNUserNotificationCenter dedupliziert 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ür tag/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 Attachments beliebiger Medientypen (Bilder, Audio, Video)
  • Unterstützen ThreadID zur Gruppierung in der Mitteilungszentrale
  • Unterstützen alle InterruptionLevel-Werte (critical erfordert die Berechtigung für kritische Hinweise)
  • Unterstützen native geplante Zustellung, die über App-Neustarts hinweg erhalten bleibt
  • Deduplizieren UpdateNotification-Aufrufe automatisch anhand von ID
  • Berücksichtigen den dunklen und hellen Modus automatisch

Bewährte Verfahren

  1. Berechtigung prüfen und anfordern:
  • macOS erfordert die Berechtigung des Benutzers
  1. Klare und prägnante Benachrichtigungen bereitstellen:
  • Aussagekräftige Titel, Untertitel, Texte und Aktionsbezeichnungen verwenden
  1. Benachrichtigungsantworten angemessen verarbeiten:
  • Benachrichtigungsantworten auf Fehler prüfen
  • Rückmeldung zu Benutzeraktionen geben
  1. Plattformkonventionen berücksichtigen:
  • Plattformspezifische Benachrichtigungsmuster befolgen
  • Systemeinstellungen berücksichtigen
  1. Unter Linux die Abhängigkeit vom Daemon berücksichtigen:
  • Den von SendNotification zurü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

go
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

go
type NotificationSound struct {
    Silent bool   // If true, no sound is played
    Name   string // Named/bundled sound (see "Custom Sound" above)
}

NotificationAttachment

go
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

go
// 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

go
const (
    InterruptionLevelPassive       = "passive"
    InterruptionLevelActive        = "active" // default
    InterruptionLevelTimeSensitive = "timeSensitive"
    InterruptionLevelCritical      = "critical"
)

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
}
Seite bearbeiten

Zuletzt aktualisiert: