SF Symbols

sf-symbols fournit les noms des SF Symbols d'Apple sous forme de constantes Kotlin typées. Les API macOS qui dessinent un symbole prennent son nom sous forme de chaîne ; au lieu d'écrire "scissors" à la main, vous référencez SFSymbolObjectsAndTools.SCISSORS et le compilateur le vérifie. Les autres modules macOS de Nucleus acceptent ces constantes partout où ils attendent une icône.

Ajouter la dépendance

dependencies {
    implementation("dev.nucleusframework:nucleus.sf-symbols:2.0.5")
}

Référencer un symbole

Chaque symbole est une valeur de l'interface scellée SFSymbol. Choisissez une constante dans l'enum de catégorie qui correspond au contexte du symbole :

import dev.nucleusframework.sfsymbols.SFSymbolGeneral
import dev.nucleusframework.sfsymbols.SFSymbolMedia
import dev.nucleusframework.sfsymbols.SFSymbolObjectsAndTools

val gear = SFSymbolGeneral.GEAR
val play = SFSymbolMedia.PLAY
val scissors = SFSymbolObjectsAndTools.SCISSORS

Chaque constante porte son nom SF Symbols dans symbolName. Passez la constante directement à une API macOS qui attend un symbole — par exemple l'icône d'un élément de menu natif :

import dev.nucleusframework.menu.macos.NsMenuItemImage
import dev.nucleusframework.sfsymbols.SFSymbolObjectsAndTools

val icon = NsMenuItemImage.SystemSymbol(SFSymbolObjectsAndTools.SCISSORS)

Pour un nom non couvert par les constantes, ou pour viser un symbole d'une version plus récente de SF Symbols, utilisez SFSymbol.Custom :

import dev.nucleusframework.sfsymbols.SFSymbol

val custom = SFSymbol.Custom("my.custom.symbol")

Fonctionnement

Chaque constante expose une chaîne symbolName qui contient son nom SF Symbols — GEAR donne "gear", PLAY donne "play". Custom enveloppe une chaîne arbitraire dans le même type, si bien qu'un SFSymbol est toujours un nom que macOS peut résoudre avec NSImage.imageWithSystemSymbolName.

Quand vous passez un SFSymbol à un module macOS, seul le symbolName atteint la couche native. Le système résout ce nom en glyphe SF Symbols installé au moment du rendu, donc le symbole suit l'apparence système de l'utilisateur sans embarquer aucun asset image.

Les constantes sont de simples chaînes, donc le module compile sur toutes les plateformes. Les SF Symbols eux-mêmes requièrent macOS 11 ou une version ultérieure ; sur un macOS antérieur ou un autre système d'exploitation, un nom ne produit rien.

Référence de l'API

Catégories

SFSymbol est une interface scellée. Chaque catégorie est un enum dont les entrées correspondent à des noms SF Symbols ; Custom est une value class pour tout le reste. Les 21 enums de catégorie implémentent SFSymbol, donc n'importe quelle constante est utilisable là où un SFSymbol est attendu.

Construire un symbole custom

SFSymbol.Custom(symbolName: String) est une value class inline. Son symbolName est utilisé tel quel ; utilisez-le pour les symboles hors des constantes prédéfinies ou issus d'une version plus récente de SF Symbols :

SFSymbol.Custom("bird.fill")
SFSymbol.Custom("my.custom.symbol")

Utiliser un symbole avec menu-macos

NsMenuItemImage.SystemSymbol a une surcharge qui prend directement un SFSymbol, si bien qu'une constante devient l'icône d'un élément de menu sans toucher à son symbolName :

import dev.nucleusframework.menu.macos.NsMenuItemImage
import dev.nucleusframework.sfsymbols.SFSymbolGeneral

NsMenuItemImage.SystemSymbol(SFSymbolGeneral.GEAR)

Et ensuite

• Barre de menus native — associez des icônes SystemSymbol aux éléments de menu.
• Icônes FreeDesktop — l'équivalent des constantes d'icônes typées pour Linux.
• Intégration OS — le reste des modules d'intégration système desktop.