API privées de macOS

Wails utilise par défaut les API publiques de macOS. L’unique balise de build Go private_mac_apis active les appels privés à WebKit et AppKit répertoriés sur cette page. Toutes les options et méthodes Go publiques restent disponibles dans les deux types de builds. Sans cette balise, les opérations exclusivement privées sont sans effet ; les fonctionnalités disposant de solutions publiques utilisent celles-ci.

Activer les API privées

# Build an application
wails3 build -tags private_mac_apis

# Run with live reload
EXTRA_TAGS=private_mac_apis wails3 dev

# Package an application
wails3 package GOOS=darwin EXTRA_TAGS=private_mac_apis

# Run a Go-only example from its directory
go run -tags private_mac_apis .

Pour un build de production direct, utilisez go build -tags production,private_mac_apis .. Pour les exemples de frontend, suivez leur README afin de générer les bindings et les ressources avant l’exécution. Les Taskfiles personnalisés ou anciens doivent transmettre EXTRA_TAGS au compilateur Go.

Inventaire des fonctionnalités

Transparence et arrière-plan de la vue web

Nécessite des API privées : la transparence de la vue web utilisée par MacBackdropTransparent, MacBackdropTranslucent, MacBackdropLiquidGlass et les fenêtres à encoche. En interne, Wails définit la clé privée drawsBackground de WebKit. Un arrière-plan HTML ou CSS transparent ne peut pas, à lui seul, rendre transparente une WKWebView native opaque.

Mac: application.MacWindow{
    // Requires -tags private_mac_apis for the blur to show through the webview.
    Backdrop: application.MacBackdropTranslucent,
},

L’opération privée de définition de la couleur d’arrière-plan de la vue web utilise la clé backgroundColor de WebKit. La configuration de Liquid Glass l’utilise pour effacer l’arrière-plan de la vue web. Sans la balise, cette opération interne utilise l’API publique underPageBackgroundColor sous macOS 12 ou version ultérieure, ou la couche de la vue sous les versions antérieures de macOS. Ces solutions ne rendent pas la vue web transparente.

WebviewWindowOptions.BackgroundColour et window.SetBackgroundColour() définissent sous macOS la couleur de la fenêtre native et ne nécessitent pas eux-mêmes d’API privées. De même, Frameless et Mac.TitleBar.AppearsTransparent utilisent des API AppKit publiques ; la dépendance privée concerne la transparence de la vue web, et non celle de la barre de titre. Pour les effets de fond sous macOS, configurez Mac.Backdrop au lieu de vous fier uniquement à BackgroundType.

Consultez les pages consacrées aux options de fenêtre, aux fenêtres sans cadre et aux fenêtres à encoche.

Valeurs de Liquid Glass

Lorsqu’un NSGlassEffectView natif est disponible (macOS 26 ou version ultérieure), les mappages suivants s’appliquent. Seules les valeurs de style natif 0 (normal) et 1 (transparent) sont documentées. Les constantes Go conservent leurs valeurs existantes dans les deux types de builds.

Automatic et Vibrant utilisent des valeurs de style natives documentées, mais un arrière-plan Liquid Glass couvrant toute la fenêtre nécessite toujours le tag pour la transparence de la webview. L’apparence de Light diffère entre les deux builds. Le mappage de style privé ne garantit pas qu’une future version de macOS produira le même effet.

Toujours privées : GroupID et GroupSpacing. Wails vérifie la présence des sélecteurs privés setGroupIdentifier:, setGroupName: et setGroupSpacing: avant de demander le regroupement. Sans le tag, ces opérations sont sans effet. L’activation du tag ne garantit pas que la version de macOS en cours d’exécution prend en charge ces sélecteurs.

MacLiquidGlass.Material, CornerRadius et TintColor ne nécessitent pas eux-mêmes d’API privées. Sur les versions de macOS dépourvues de prise en charge native de Liquid Glass, Wails configure une solution de repli translucide ; pour qu’elle soit visible à travers la webview, le tag reste nécessaire.

Inspecteur web

Nécessite des API privées : l’appel de OpenDevTools() ou la définition de OpenInspectorOnStartup: true pour ouvrir l’inspecteur de WebKit depuis l’application. Wails utilise le sélecteur privé _inspector. Sans private_mac_apis, ces opérations sont silencieusement sans effet.

La prise en charge de l’inspecteur doit également être intégrée lors de la compilation. Les tags production et devtools existants conservent leur signification :

Sous macOS 13.3+, Wails active l’inspection avec Safari à l’aide de l’API publique WKWebView.inspectable ; cela ne nécessite aucune API privée. Avant macOS 13.3, la solution de repli utilise la préférence privée developerExtrasEnabled et nécessite donc private_mac_apis ainsi que la prise en charge de l’inspecteur intégrée lors de la compilation.

# Production build with programmatic inspector support
go build -tags production,devtools,private_mac_apis .

Tenir cette liste à jour

Tous les appels natifs privés sont isolés dans v3/pkg/application/mac_private_api_darwin.go ; les builds par défaut sélectionnent mac_public_api_darwin.go. Cet inventaire couvre la transparence, la couleur d’arrière-plan de la webview, les styles de verre, le regroupement des effets de verre, l’ouverture de l’inspecteur et l’activation de l’ancien inspecteur. Toute modification de ces implémentations devrait s’accompagner d’une mise à jour conjointe de cette page et de la documentation des options concernées.