Notifications sur Windows

notification-windows vous permet d'envoyer des toasts Windows 10/11 depuis Kotlin. Le module enveloppe l'API WinRT ToastNotificationManager dans un DSL qui couvre le texte adaptatif, les images, les barres de progression, les sélecteurs, les champs de saisie et les en-têtes, et fonctionne aussi bien pour les apps packagées MSIX que pour les apps non packagées (EXE/MSI).

Ajouter la dépendance

dependencies {
    implementation("dev.nucleusframework:nucleus.notification-windows:2.0.7")
}

Envoyer une notification

Appelez initialize() une fois avant d'afficher un toast, puis construisez le contenu avec le DSL toast { } et passez-le à show :

import dev.nucleusframework.notification.windows.*

WindowsNotificationCenter.initialize()

WindowsNotificationCenter.show(
    toast {
        visual {
            text("Build terminé")
            text("artifact-2.0.0.zip uploadé")
            heroImage("https://example.com/hero.png")
        }
        actions {
            button("Ouvrir", arguments = "open")
            button("Afficher dans le dossier", arguments = "folder")
        }
    },
)

Chaque méthode est sans effet sur les plateformes autres que Windows. Vérifiez WindowsNotificationCenter.isAvailable avant l'appel si vous partagez du code entre systèmes d'exploitation.

Fonctionnement

Sous Windows, un toast est un payload XML dispatché par ToastNotificationManager et identifié par un AUMID (Application User Model ID). Le module résout l'AUMID pour vous selon le mode de packaging de l'app.

Référence de l'API

Construire un contenu adaptatif

Le builder toast { } expose les blocs visual, actions, audio et header. Les valeurs d'enum sont en UPPER_SNAKE_CASE.

toast {
    visual {
        text("Synchronisation en cours")
        appLogo("logo.png", crop = AdaptiveImageCrop.CIRCLE)
        progressBar(
            status = "Upload",
            title = "report.pdf",
            valueStringOverride = "3 sur 5 fichiers",
            value = 0.6,
        )
    }
    actions {
        button("Pause", arguments = "pause")
        button("Annuler", arguments = "cancel", activationType = ActivationType.BACKGROUND)
    }
    audio(ToastAudioSource.REMINDER)
    scenario = ToastScenario.REMINDER
}

ToastActionsBuilder fournit textBox, selectionBox, button et contextMenuItem. La chaîne status est le seul argument obligatoire de progressBar.

Écouter les événements

Enregistrez un listener avec addListener. Les callbacks reçoivent des paramètres à plat, pas des objets d'arguments d'événement :

WindowsNotificationCenter.addListener(object : ToastNotificationListener {
    override fun onActivated(
        tag: String,
        group: String,
        arguments: String,
        userInputs: Map<String, String>,
    ) { /* ... */ }

    override fun onDismissed(tag: String, group: String, reason: DismissalReason) { /* ... */ }

    override fun onFailed(tag: String, group: String, errorCode: Int) { /* ... */ }
})

Retirez un listener avec WindowsNotificationCenter.removeListener(listener).

Mettre à jour un toast existant

Affichez un toast avec un tag et un group, puis poussez de nouvelles valeurs liées aux données avec update. C'est ce qui fait avancer une barre de progression sans remplacer le toast :

WindowsNotificationCenter.update(
    tag = "upload",
    group = "transfers",
    data = ToastNotificationData(
        sequenceNumber = 1,
        values = mapOf("progressValue" to "0.8"),
    ),
)

ToastNotificationData prend d'abord sequenceNumber (un numéro croissant qui évite les courses), puis la map values.

Lire l'historique de l'Action Center

getHistory livre les toasts actuellement dans l'Action Center via un callback. Chaque HistoryEntry expose tag et group :

WindowsNotificationCenter.getHistory { entries, error ->
    entries.forEach { entry -> println("${entry.tag} / ${entry.group}") }
}

Retirer des toasts

• remove(tag, group) retire un toast précis.
• removeGroup(group) retire tous les toasts d'un groupe.
• clearAll() vide les entrées de l'app dans l'Action Center.
• uninitialize() libère les ressources natives à l'arrêt.

Notes

• Gardez l'AUMID cohérent entre le raccourci Menu Démarrer, votre config Gradle nucleus { } et l'exécution. Un décalage est la cause habituelle d'un toast qui apparaît une fois puis plus jamais.
• tag et group sont limités à 16 caractères chacun.
• Les images héros et les logos acceptent des URL http(s):// distantes pour les apps non packagées tant qu'elles répondent vite. Pour un comportement fiable hors ligne, embarquez un fichier local via ms-appx:/// (MSIX) ou file:/// (non packagé).

Et ensuite

• Vue d'ensemble des notifications — le DSL de notification cross-plateforme.
• Notifications sur macOS — UNUserNotificationCenter depuis Kotlin.
• Notifications sur Linux — les notifications Freedesktop via D-Bus.