Private macOS-APIs

Wails verwendet standardmäßig öffentliche macOS-APIs. Das einzelne Go-Build-Tag private_mac_apis aktiviert die auf dieser Seite aufgeführten privaten WebKit- und AppKit-Aufrufe. Alle öffentlichen Go-Optionen und -Methoden bleiben in beiden Builds verfügbar. Ohne das Tag haben ausschließlich private Operationen keine Wirkung; Funktionen mit öffentlichen Alternativen verwenden diese Alternativen.

Private APIs aktivieren

# 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 .

Verwenden Sie für einen direkten Produktions-Build go build -tags production,private_mac_apis .. Befolgen Sie bei Frontend-Beispielen deren README, um Bindings und Assets vor der Ausführung zu erstellen. Benutzerdefinierte oder ältere Taskfiles müssen EXTRA_TAGS an den Go-Compiler weiterleiten.

Funktionsübersicht

Transparenz und Hintergrund der Webview

Erfordert private APIs: die von MacBackdropTransparent, MacBackdropTranslucent, MacBackdropLiquidGlass und Notch-Fenstern verwendete Webview-Transparenz. Intern setzt Wails den privaten WebKit-Schlüssel drawsBackground. Ein transparenter HTML- oder CSS-Hintergrund allein kann ein undurchsichtiges natives WKWebView nicht transparent machen.

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

Die private Operation für die Hintergrundfarbe der Webview verwendet den WebKit-Schlüssel backgroundColor. Die Einrichtung von Liquid Glass verwendet ihn, um den Webview-Hintergrund zu leeren. Ohne das Tag verwendet diese interne Operation unter macOS 12+ das öffentliche underPageBackgroundColor oder unter älteren macOS-Versionen die Ebene der Ansicht. Diese Alternativen machen die Webview nicht transparent.

WebviewWindowOptions.BackgroundColour und window.SetBackgroundColour() legen unter macOS die Farbe des nativen Fensters fest und erfordern selbst keine privaten APIs. Ebenso verwenden Frameless und Mac.TitleBar.AppearsTransparent öffentliche AppKit-APIs; die private Abhängigkeit ist die Webview-Transparenz, nicht die Transparenz der Titelleiste. Konfigurieren Sie für macOS-Hintergrundeffekte Mac.Backdrop, statt sich allein auf BackgroundType zu verlassen.

Siehe Fensteroptionen, rahmenlose Fenster und Notch-Fenster.

Liquid-Glass-Werte

Wenn ein natives NSGlassEffectView verfügbar ist (macOS 26+), gelten die folgenden Zuordnungen. Dokumentiert sind nur die nativen Stilwerte 0 (regulär) und 1 (transparent). Die Go-Konstanten behalten in beiden Builds ihre bestehenden Werte.

Automatic und Vibrant verwenden dokumentierte native Stilwerte, für einen fensterfüllenden Liquid-Glass-Hintergrund ist das Tag jedoch weiterhin für die Transparenz der Webview erforderlich. Das Erscheinungsbild von Light unterscheidet sich zwischen den beiden Builds. Die Zuordnung des privaten Stils garantiert nicht, dass eine zukünftige macOS-Version denselben Effekt rendert.

Immer privat: GroupID und GroupSpacing. Wails prüft vor dem Anfordern der Gruppierung, ob die privaten Selektoren setGroupIdentifier:, setGroupName: und setGroupSpacing: vorhanden sind. Ohne das Tag bewirken diese Operationen nichts. Das Aktivieren des Tags garantiert nicht, dass die ausgeführte macOS-Version diese Selektoren unterstützt.

MacLiquidGlass.Material, CornerRadius und TintColor erfordern selbst keine privaten APIs. Auf macOS-Versionen ohne native Liquid-Glass-Unterstützung konfiguriert Wails eine transluzente Ausweichdarstellung; damit sie durch die Webview sichtbar ist, ist das Tag weiterhin erforderlich.

Web-Inspector

Erfordert private APIs: der Aufruf von OpenDevTools() oder das Setzen von OpenInspectorOnStartup: true, um den Inspector von WebKit aus der Anwendung heraus zu öffnen. Wails verwendet den privaten Selektor _inspector. Ohne private_mac_apis bewirken diese Operationen stillschweigend nichts.

Die Inspector-Unterstützung muss außerdem einkompiliert sein. Die vorhandenen Tags production und devtools behalten ihre Bedeutung:

Unter macOS 13.3+ aktiviert Wails die Safari-Inspektion über die öffentliche API WKWebView.inspectable; dafür sind keine privaten APIs erforderlich. Vor macOS 13.3 verwendet die Ausweichlösung die private Einstellung developerExtrasEnabled und erfordert daher neben einkompilierter Inspector-Unterstützung auch private_mac_apis.

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

Diese Liste pflegen

Alle privaten nativen Aufrufe sind in v3/pkg/application/mac_private_api_darwin.go isoliert; Standard-Builds wählen mac_public_api_darwin.go aus. Diese Übersicht umfasst Transparenz, die Hintergrundfarbe der Webview, Glass-Stile, Glass-Gruppierung, das Öffnen des Inspectors und die Aktivierung des Legacy-Inspectors. Bei Änderungen an diesen Implementierungen sollten diese Seite und die Dokumentation der betroffenen Optionen gemeinsam aktualisiert werden.