Приватные API macOS
Все функции и параметры Wails, зависящие от приватных API macOS, а также команды для их включения и альтернативы для публичных сборок.
По умолчанию Wails использует публичные API macOS. Единый тег сборки Go private_mac_apis включает перечисленные на этой странице вызовы приватных API WebKit и AppKit. Все публичные параметры и методы Go остаются доступными в обеих сборках. Без этого тега операции, доступные только через приватные API, ничего не делают, а функции с публичными альтернативами используют эти альтернативы.
Включение приватных API
# 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 .
Для непосредственной производственной сборки используйте go build -tags production,private_mac_apis .. Для примеров с фронтендом перед запуском соберите привязки и ресурсы согласно соответствующему файлу README. Пользовательские или устаревшие файлы Taskfile должны передавать EXTRA_TAGS компилятору Go.
Перечень функций
| Функция или значение | Что включает private_mac_apis |
Без тега |
|---|---|---|
Mac.Backdrop: MacBackdropTransparent |
Прозрачный WKWebView поверх нативного окна | Нативное окно настраивается, но веб-представление остаётся непрозрачным |
Mac.Backdrop: MacBackdropTranslucent |
Прозрачный WKWebView, сквозь который виден нативный эффект размытия | Эффект размытия настраивается за непрозрачным веб-представлением |
Mac.Backdrop: MacBackdropLiquidGlass |
Прозрачный WKWebView поверх стеклянного слоя с управлением фоном веб-представления через приватный API | Стеклянный слой настраивается за непрозрачным веб-представлением; для оформления используются публичные альтернативы |
| Очистка фона веб-представления при настройке Liquid Glass | Приватное средство управления WebKit backgroundColor |
Публичный underPageBackgroundColor в macOS 12+ либо цвет слоя в более ранних версиях macOS; веб-представление при этом не становится прозрачным |
app.Window.NewNotchWindow(...) |
Прозрачное веб-представление внутри фигурной панели выреза | Панель продолжает работать, включая позиционирование и анимацию, но её веб-представление остаётся непрозрачным |
Mac.LiquidGlass.Style |
Существующее в Wails сопоставление с нативными стилями, включая недокументированное значение тёмного стиля | Используются публичные обычный и прозрачный стили, а также светлое и тёмное оформление; см. таблицу значений ниже |
Mac.LiquidGlass.GroupID |
Запрашивает приватную группировку стеклянных элементов для непустого идентификатора | Игнорируется; группировка не запрашивается |
Mac.LiquidGlass.GroupSpacing |
Запрашивает приватную настройку группового интервала при значении больше нуля | Игнорируется |
window.OpenDevTools() и JavaScript Window.OpenDevTools() |
Программно открывает инспектор WebKit в macOS 12+ | Ничего не делает |
WebviewWindowOptions.OpenInspectorOnStartup: true |
Запрашивает программное открытие инспектора при первом отображении окна в macOS 12+ | Ничего не делает |
| Устаревший способ включения инспектора до macOS 13.3 | Включает дополнительные средства разработчика WebKit, если поддержка инспектора включена при компиляции | Ничего не делает; для публичного инспектирования через Safari требуется macOS 13.3+ |
Прозрачность и фон веб-представления
Требует приватных API: прозрачность веб-представления, используемая MacBackdropTransparent, MacBackdropTranslucent, MacBackdropLiquidGlass и окнами с вырезом. Внутри Wails задаёт приватный ключ WebKit drawsBackground. Одного лишь прозрачного фона HTML или CSS недостаточно, чтобы сделать непрозрачный нативный WKWebView прозрачным.
Mac: application.MacWindow{
// Requires -tags private_mac_apis for the blur to show through the webview.
Backdrop: application.MacBackdropTranslucent,
},Приватная операция изменения цвета фона веб-представления использует ключ WebKit backgroundColor. При настройке Liquid Glass с её помощью очищается фон веб-представления. Без тега эта внутренняя операция использует публичный underPageBackgroundColor в macOS 12+ либо слой представления в более ранних версиях macOS. Эти альтернативы не делают веб-представление прозрачным.
WebviewWindowOptions.BackgroundColour и window.SetBackgroundColour() задают в macOS цвет нативного окна и сами по себе не требуют приватных API. Аналогично, Frameless и Mac.TitleBar.AppearsTransparent используют публичные API AppKit; зависимость от приватного API связана с прозрачностью веб-представления, а не строки заголовка. Для эффектов заднего фона в macOS настраивайте Mac.Backdrop, а не полагайтесь только на BackgroundType.
См. параметры окна, безрамочные окна и окна с вырезом.
Значения Liquid Glass
Если доступен нативный NSGlassEffectView (macOS 26+), применяются следующие сопоставления. Документированы только значения нативного стиля 0 (обычный) и 1 (прозрачный). Константы Go сохраняют существующие значения в обеих сборках.
Значение MacLiquidGlassStyle |
С private_mac_apis |
Без тега |
|---|---|---|
LiquidGlassStyleAutomatic (0) |
Нативный обычный стиль (0) |
Нативный обычный стиль (0) |
LiquidGlassStyleLight (1) |
Существующее сопоставление с нативным стилем (1, прозрачный) |
Нативный обычный стиль (0) с оформлением Aqua |
LiquidGlassStyleDark (2) |
Недокументированное значение нативного стиля 2 |
Обычный нативный стиль (0) с оформлением Dark Aqua |
LiquidGlassStyleVibrant (3) |
Соответствует существующему светлому нативному прозрачному стилю (1) |
Нативный прозрачный стиль (1) |
Automatic и Vibrant используют документированные значения нативных стилей, однако для фона Liquid Glass на всё окно по-прежнему требуется тег, обеспечивающий прозрачность webview. Внешний вид Light различается в этих двух сборках. Сопоставление с закрытым стилем не гарантирует, что в будущей версии macOS эффект будет отображаться так же.
Всегда требуют закрытых API: GroupID и GroupSpacing. Перед запросом группировки Wails проверяет наличие закрытых селекторов setGroupIdentifier:, setGroupName: и setGroupSpacing:. Без тега эти операции не выполняют никаких действий. Включение тега не гарантирует, что запущенная версия macOS поддерживает эти селекторы.
Для MacLiquidGlass.Material, CornerRadius и TintColor сами по себе закрытые API не требуются. В версиях macOS без нативной поддержки Liquid Glass Wails настраивает полупрозрачный резервный вариант; чтобы он был виден через webview, тег по-прежнему необходим.
Веб-инспектор
Требуют закрытых API: вызов OpenDevTools() или установка OpenInspectorOnStartup: true для открытия инспектора WebKit из приложения. Wails использует закрытый селектор _inspector. Без private_mac_apis эти операции не выполняют никаких действий и не выводят сообщений.
Поддержка инспектора также должна быть включена при компиляции. Существующие теги production и devtools сохраняют своё значение:
| Теги сборки | Программное открытие инспектора | Публичное инспектирование через Safari в macOS 13.3+ |
|---|---|---|
| Нет | Не выполняет никаких действий | Включено |
private_mac_apis |
Включено в macOS 12+ | Включено |
production |
Не выполняет никаких действий | Отключено |
production,private_mac_apis |
Не выполняет никаких действий | Отключено |
production,devtools |
Не выполняет никаких действий | Включено |
production,devtools,private_mac_apis |
Включено в macOS 12+ | Включено |
В macOS 13.3+ Wails включает инспектирование через Safari с помощью публичного WKWebView.inspectable; для этого закрытые API не требуются. В версиях до macOS 13.3 резервный вариант использует закрытую настройку developerExtrasEnabled, поэтому наряду со встроенной при компиляции поддержкой инспектора требуется private_mac_apis.
# Production build with programmatic inspector support
go build -tags production,devtools,private_mac_apis .
Поддержание списка в актуальном состоянии
Все закрытые нативные вызовы изолированы в v3/pkg/application/mac_private_api_darwin.go; в сборках по умолчанию выбирается mac_public_api_darwin.go. Этот перечень охватывает прозрачность, цвет фона webview, стили стекла, группировку стеклянных элементов, открытие инспектора и включение устаревшего механизма инспектора. При изменении этих реализаций следует одновременно обновлять эту страницу и документацию по затронутым параметрам.