APIs privadas do macOS

Por padrão, o Wails usa APIs públicas do macOS. A única tag de build do Go, private_mac_apis, habilita as chamadas privadas do WebKit e do AppKit listadas nesta página. Todas as opções e todos os métodos públicos do Go permanecem disponíveis em ambos os builds. Sem a tag, as operações exclusivas de APIs privadas não realizam nenhuma ação; os recursos com alternativas públicas usam essas alternativas.

Habilitar APIs privadas

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

Para um build de produção direto, use go build -tags production,private_mac_apis .. Para os exemplos de frontend, siga o README correspondente para compilar os bindings e os assets antes da execução. Taskfiles personalizados ou antigos devem encaminhar EXTRA_TAGS ao compilador Go.

Inventário de recursos

Transparência e plano de fundo da webview

Requer APIs privadas: a transparência da webview usada por MacBackdropTransparent, MacBackdropTranslucent, MacBackdropLiquidGlass e janelas de notch. Internamente, o Wails define a chave privada drawsBackground do WebKit. Um plano de fundo HTML ou CSS transparente, por si só, não pode tornar transparente uma WKWebView nativa opaca.

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

A operação privada de cor do plano de fundo da webview usa a chave backgroundColor do WebKit. A configuração do Liquid Glass usa essa operação para limpar o plano de fundo da webview. Sem a tag, essa operação interna usa underPageBackgroundColor público no macOS 12+ ou a camada da view em versões anteriores do macOS. Essas alternativas não tornam a webview transparente.

WebviewWindowOptions.BackgroundColour e window.SetBackgroundColour() definem a cor da janela nativa no macOS e, por si só, não requerem APIs privadas. Da mesma forma, Frameless e Mac.TitleBar.AppearsTransparent usam APIs públicas do AppKit; a dependência privada é a transparência da webview, não a transparência da barra de título. Para aplicar efeitos de pano de fundo no macOS, configure Mac.Backdrop em vez de depender apenas de BackgroundType.

Consulte opções de janela, janelas sem moldura e janelas de notch.

Valores do Liquid Glass

Quando um NSGlassEffectView nativo está disponível (macOS 26+), aplicam-se os mapeamentos a seguir. Somente os valores de estilo nativo 0 (regular) e 1 (clear) estão documentados. As constantes Go mantêm os valores existentes em ambos os builds.

Automatic e Vibrant usam valores de estilo nativo documentados, mas um plano de fundo Liquid Glass que ocupe toda a janela ainda precisa da tag para a transparência da webview. A aparência de Light difere entre as duas compilações. O mapeamento de estilo privado não garante que uma versão futura do macOS renderize o mesmo efeito.

Sempre privados: GroupID e GroupSpacing. Antes de solicitar o agrupamento, o Wails verifica os seletores privados setGroupIdentifier:, setGroupName: e setGroupSpacing:. Sem a tag, essas operações não têm efeito. Habilitar a tag não garante que a versão do macOS em execução seja compatível com esses seletores.

MacLiquidGlass.Material, CornerRadius e TintColor não exigem APIs privadas por si só. Em versões do macOS sem suporte nativo a Liquid Glass, o Wails configura uma alternativa translúcida; para que ela fique visível através da webview, a tag ainda é necessária.

Inspetor da Web

Requer APIs privadas: chamar OpenDevTools() ou definir OpenInspectorOnStartup: true para abrir o inspetor do WebKit a partir do aplicativo. O Wails usa o seletor privado _inspector. Sem private_mac_apis, essas operações não têm efeito e não exibem nenhuma mensagem.

O suporte ao inspetor também precisa ser incluído na compilação. As tags production e devtools existentes mantêm seus significados:

No macOS 13.3 ou posterior, o Wails habilita a inspeção pelo Safari usando a API pública WKWebView.inspectable; isso não requer APIs privadas. Antes do macOS 13.3, o mecanismo alternativo usa a preferência privada developerExtrasEnabled e, portanto, requer private_mac_apis, além de o suporte ao inspetor ter sido incluído na compilação.

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

Manutenção desta lista

Todas as chamadas nativas privadas ficam isoladas em v3/pkg/application/mac_private_api_darwin.go; as compilações padrão selecionam mac_public_api_darwin.go. Este inventário abrange transparência, cor de fundo da webview, estilos de vidro, agrupamento de vidro, abertura do inspetor e habilitação do inspetor legado. Alterações nessas implementações devem atualizar esta página e, ao mesmo tempo, a documentação das opções afetadas.