Affiche une icône de tray et un menu contextuel natif depuis Compose sur macOS, Windows et Linux.

L'API de tray système dessine une icône de tray et son menu contextuel natif depuis Compose sur macOS, Windows et Linux. L'icône est tout ce que Compose sait dessiner, le menu est un DSL Kotlin, et les deux réagissent à l'état Compose. Tray() est un composable unique qui remet l'icône et le menu rendus à l'API de tray native de l'OS courant.

Dépôt séparé — versionné indépendamment

Le tray système vient de NucleusFramework/ComposeNativeTray avec son propre cycle de release. Son numéro de version est indépendant de Nucleus — épinglez-le séparément. L'artefact est dev.nucleusframework:composenativetray.

Dernière version: 2.0.1

Ajouter la dépendance

dependencies {
    implementation("dev.nucleusframework:composenativetray:2.0.1")
}

Ajouter une icône de tray

Déclarez un composable Tray() avec une icône, une infobulle et une lambda de menu :

import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import dev.nucleusframework.tray.*

Tray(
    icon = Icons.Default.Favorite,
    tooltip = "Mon App",
    primaryAction = { showWindow() },
) {
    Item(label = "Afficher la fenêtre") { showWindow() }
    Divider()
    Item(label = "Quitter") { exitProcess(0) }
}

Fonctionnement

Tray() est un composable. Son icône est rastérisée depuis Compose à chaque changement d'état du slot, puis remise à l'API de tray native de l'OS courant. La lambda du menu tourne dans un scope DSL réévalué à chaque recomposition : ajouter, retirer ou renommer un item suit les règles de recomposition habituelles de Compose.

Le tray fait partie de votre arbre d'état Compose : il se met à jour par recomposition, sans appel de rebuild explicite ni fichiers .ico/.png/.icns distincts à maintenir.

Chaque plateforme s'appuie sur son mécanisme de tray natif :

Adossé à NSStatusItem dans la barre de menus. Les icônes vectorielles rendent au DPI natif, avec une teinte optionnelle via le paramètre tint.

Adossé à Shell_NotifyIcon. Le vectoriel est rastérisé en .ico 32×32 par facteur d'échelle. Passez un .ico fait main via windowsIcon pour un contrôle exact.

Utilise StatusNotifierItem (KStatusNotifierItem). Sous GNOME standard, cela requiert l'extension AppIndicator ; sous Ubuntu, cela fonctionne directement.

StatusNotifierItem est natif à Plasma. Les infobulles au survol et les badges fonctionnent là où Plasma les prend en charge.

Définir la source de l'icône

Le paramètre icon accepte un ImageVector, un Painter ou un DrawableResource de Compose Multiplatform. Pour un contrôle total, utilisez iconContent afin de dessiner l'icône avec n'importe quel composable :

// ImageVector
Tray(icon = Icons.Default.Notifications, tint = Color.White, tooltip = "App") { /* … */ }

// Painter
Tray(icon = painterResource("icon.png"), tooltip = "App") { /* … */ }

// Compose Multiplatform DrawableResource
Tray(icon = Res.drawable.app_icon, tooltip = "App") { /* … */ }

// Entièrement personnalisé — n'importe quel composable
Tray(
    iconContent = {
        Box(Modifier.size(24.dp).background(Color.Red, CircleShape)) {
            Text("3", color = Color.White, modifier = Modifier.align(Alignment.Center))
        }
    },
    tooltip = "3 notifications",
) { /* … */ }

Utiliser des icônes spécifiques par plateforme

Pour un .ico natif sous Windows et un vectoriel ailleurs, renseignez windowsIcon et macLinuxIcon :

Tray(
    windowsIcon = painterResource("icon.ico"),
    macLinuxIcon = Icons.Default.Notifications,
    tint = Color.White,
    tooltip = "Mon App",
) { /* menu */ }

Gérer l'action primaire

primaryAction se déclenche au clic gauche (macOS/Windows) ou au clic simple (Linux, selon le bureau). Sans elle, le menu s'ouvre à chaque clic.

Tray(
    icon = Icons.Default.Favorite,
    tooltip = "Mon App",
    primaryAction = { showWindow() },
) {
    Item(label = "Quitter") { exitProcess(0) }
}

Et ensuite

DSL du menu de tray — items, cases à cocher, sous-menus, séparateurs et composition réactive.
Tray apps — faites ouvrir une popup Compose par l'icône du tray.

System tray