Toast Notifications WinRT en Kotlin — layouts adaptatifs, images héros, boutons, saisie texte, barres de progression, en-têtes, snooze / dismiss.

Les toasts Windows 10/11 portent images, barres de progression, sélecteurs, champs de saisie, en-têtes — bien au-delà du DSL cross-plateforme. notification-windows enveloppe toute l'API ToastNotificationManager dans un DSL Kotlin.

En bref

ToastNotificationManager WinRT via un pont JNI C++/WRL — pas de JNA, pas de réflexion.
Apps MSIX packagées et non packagées (EXE/MSI) prises en charge.
DSL adaptatif : image héros, app logo, attribution, groupes / sous-groupes, barres de progression, sélecteurs.
Listener pour activation, rejet, échec.

Installation

dependencies {
    implementation("dev.nucleusframework:nucleus.notification-windows:<version>")
}

Démarrage rapide

import dev.nucleusframework.notification.windows.*

WindowsNotificationCenter.initialize()

WindowsNotificationCenter.send(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")
    }
})

Fonctionnement

Sous Windows, un toast est un payload XML dispatché par ToastNotificationManager et identifié par un AUMID (Application User Model ID). Le module gère les deux cas, packagé et non packagé :

Gestion de l'AUMID

MSIX / APPX : l'AUMID est récupéré depuis l'identité du package.
Non packagé (EXE/MSI/dev) : Nucleus dérive l'AUMID depuis NucleusApp.appId et l'enregistre sur le process via SetCurrentProcessExplicitAppUserModelID.
Passe un AUMID explicite avec WindowsNotificationCenter.initialize(aumid = "Vendor.App") si l'on veut forcer une valeur.

Raccourci Menu Démarrer requis (non packagé)

Les apps non packagées ont besoin d'un raccourci .lnk dans le menu Démarrer dont la propriété AUMID correspond à celle utilisée à l'exécution. Sans ça, les toasts peuvent ne pas s'afficher ou disparaître de l'Action Center. Le plugin Gradle Nucleus le configure pour soi quand on produit un installeur Windows.

Référence

Contenu adaptatif

toast {
    visual {
        text("Synchronisation en cours")
        appLogo("logo.png", crop = AdaptiveImageCrop.Circle)
        progressBar(
            title = "report.pdf",
            valueStringOverride = "3 sur 5 fichiers",
            value = 0.6,
            status = "Upload",
        )
    }
    actions {
        button("Pause", arguments = "pause")
        snoozeButton()
        dismissButton()
    }
    scenario = ToastScenario.Reminder
}

Listener

WindowsNotificationCenter.setListener(object : ToastNotificationListener {
    override fun onActivated(args: ToastActivatedEventArgs) { /* … */ }
    override fun onDismissed(args: ToastDismissedEventArgs) { /* … */ }
    override fun onFailed(args: ToastFailedEventArgs) { /* … */ }
})

Mettre à jour un toast existant

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

Historique

WindowsNotificationCenter.history().forEach { entry ->
    println("${entry.tag}: ${entry.dateTime}")
}

Notes

Garde l'AUMID cohérent entre le raccourci Menu Démarrer, la config Gradle nucleus { } (packageName) et l'exécution — un décalage cause des toasts qui apparaissent une fois puis plus jamais.
Les images héros et logos acceptent des URL http(s):// distantes pour les apps non packagées tant qu'elles répondent vite ; pour un comportement offline-safe, embarque un fichier local via ms-appx:/// (MSIX) ou file:/// (non packagé).

Notifications sur Windows