Ваше первое мобильное приложение

В этом руководстве показано, как запустить обычное настольное приложение Wails в iOS Simulator или Android Emulator. Изменять код Go не нужно. Один и тот же main.go используется для сборки под все целевые платформы.

Время выполнения: 15–30 минут (бо́льшая часть этого времени при первом запуске уходит на установку инструментов)

Начните с настольного проекта

Если у вас ещё нет проекта, создайте новый:

wails3 init -n mymobileapp
cd mymobileapp

Сначала убедитесь, что настольное приложение работает:

wails3 dev

Когда приложение откроется, закройте его и продолжайте. Всё, что работает на настольной платформе, работает и на мобильной — в рамках этого руководства вам не придётся изменять main.go или какой-либо код Go.

Выберите платформу

wails3 task ios:run

wails3 task ios:logs:dev

wails3 task ios:xcode

sdkmanager "platform-tools" \
           "platforms;android-35" \
           "build-tools;35.0.0" \
           "ndk;26.3.11579264" \
           "emulator" \
           "system-images;android-35;google_apis;arm64-v8a"

avdmanager create avd \
  --name wails \
  --package "system-images;android-35;google_apis;arm64-v8a" \
  --device pixel_7

export ANDROID_HOME=~/android-sdk
export ANDROID_SDK_ROOT=~/android-sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin

# macOS
brew install openjdk@21
export JAVA_HOME=$(brew --prefix openjdk@21)

# Ubuntu/Debian
sudo apt install openjdk-21-jdk
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

# Windows (scoop)
scoop install openjdk21

wails3 task android:run

wails3 task android:logs

Что произошло

Ваш main.go совсем не изменился. Wails выполнил всё необходимое:

• Система сборки — файл Taskfile.yml в вашем проекте содержит задачи ios:* и android:*, которые запускают набор инструментов для соответствующей платформы.
• Кросс-компиляция Go — с помощью GOOS=ios или GOOS=android с подходящими значениями GOARCH и sysroot.
• Нативное хост-приложение — сгенерированный проект Xcode (iOS) или Gradle (Android), который включает скомпилированный код Go и размещает WebView.
• Предоставление ресурсов — содержимое frontend/dist/ встраивается в двоичный файл Go и предоставляется внутри процесса. Локальный сервер не требуется.

Адаптируйте приложение для мобильных устройств

Приложение уже работает, но на экране телефона выглядит как настольное. Несколько небольших изменений заметно улучшат результат.

Адаптивный CSS

Экраны мобильных устройств уже и используют другие способы ввода. В файле frontend/public/style.css (или его аналоге):

/* Prevent horizontal scrolling */
body {
  overflow-x: hidden;
}

/* Touch-friendly tap targets */
button {
  min-height: 44px;
  min-width: 44px;
}

/* Respect the iOS safe area (notch, home indicator) */
body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

Определение платформы в Go

Используйте теги сборки, чтобы добавить поведение для конкретной платформы, не загромождая общий код.

Создайте mobile_ios.go для кода, предназначенного только для iOS:

//go:build ios

package main

import "github.com/wailsapp/wails/v3/pkg/application"

func platformOptions() application.IOSOptions {
    return application.IOSOptions{
        DisableBounce: true,
    }
}

Создайте mobile_android.go для кода, предназначенного только для Android:

//go:build android

package main

import "github.com/wailsapp/wails/v3/pkg/application"

func platformOptions() application.AndroidOptions {
    return application.AndroidOptions{}
}

Создайте mobile_desktop.go как заглушку, чтобы общий код компилировался и для настольных платформ:

//go:build !ios && !android

package main

type mobileOptions struct{}

func platformOptions() mobileOptions { return mobileOptions{} }

Определение платформы в JavaScript и отображение интерфейса только для мобильных платформ

Объекты среды выполнения IOS.* и Android.* существуют только на соответствующих платформах. Их вызов на настольной платформе приводит к исключению. Правильный подход, используемый в Kitchen Sink, — один раз определить платформу и полностью скрыть элементы управления, предназначенные только для мобильных платформ:

// Detect platform from the bridge the host injects into the WebView
const platform = (() => {
  if (typeof window.wails?.platform === 'function') return window.wails.platform(); // Android
  if (window.webkit?.messageHandlers?.external) return 'ios';
  return 'desktop';
})();

const isIOS     = platform === 'ios';
const isAndroid = platform === 'android';
const isMobile  = isIOS || isAndroid;

// Hide any element marked as mobile-only
document.querySelectorAll('.mobile-only').forEach(el => {
  el.style.display = isMobile ? '' : 'none';
});

Затем добавьте в HTML:

<section class="mobile-only">
  <button id="btnHaptic">Haptic feedback</button>
</section>

При таком подходе кнопки, предназначенные только для мобильных платформ, никогда не отрисовываются на настольных платформах, и вам не приходится защищать каждый отдельный вызов проверкой if (isMobile).

На стороне Go дополните это заглушкой с тегом сборки, чтобы обработчики событий регистрировались только на тех платформах, где они нужны:

//go:build !ios && !android

package main

import "github.com/wailsapp/wails/v3/pkg/application"

// No-op on desktop — mobile tabs are hidden in the frontend so these
// events are never emitted.
func registerNativeFeatures(app *application.App) {}

//go:build ios

package main

import "github.com/wailsapp/wails/v3/pkg/application"

func registerNativeFeatures(app *application.App) {
    app.Event.On("common:haptic", func(e *application.CustomEvent) {
        // only compiled and called on iOS
        application.IOS.Haptic("medium")
    })
    // ... other handlers
}

Именно этот подход используется в примере Kitchen Sink — см. native_features_stub.go, native_features_ios.go и native_features_android.go.

Добавление тактильной обратной связи (iOS)

import { IOS } from '@wailsio/runtime';

async function onButtonTap() {
  if (isIOS) {
    await IOS.Haptics.Impact({ style: 'medium' });
  }
  // ... rest of your handler
}

Добавление вибрации (Android)

import { Android } from '@wailsio/runtime';

async function onButtonTap() {
  if (isAndroid) {
    await Android.Haptics.Vibrate(50); // 50ms
  }
}

Сборка для промышленной эксплуатации

wails3 task ios:package
wails3 task ios:deploy-simulator

wails3 task ios:package \
  IOS_PLATFORM=device \
  CODESIGN_IDENTITY="Apple Development: You (TEAMID)" \
  PROVISIONING_PROFILE=path/to/profile.mobileprovision

wails3 task ios:deploy-device   # installs via xcrun devicectl

wails3 task ios:package:ipa IOS_PLATFORM=device \
  CODESIGN_IDENTITY="..." \
  PROVISIONING_PROFILE=path/to/distribution.mobileprovision

wails3 task android:package
wails3 task android:deploy-emulator

ANDROID_KEYSTORE_FILE=/path/to/release.jks \
ANDROID_KEYSTORE_PASSWORD=yourpassword \
ANDROID_KEY_ALIAS=youralias \
ANDROID_KEY_PASSWORD=yourkeypassword \
  wails3 task android:package

wails3 task android:package:fat

Устранение неполадок

Ошибка «no iOS SDKs found» при выполнении wails3 task ios:run

Необходимо установить полную версию Xcode и выбрать её:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p  # should print the Xcode path

Ошибка «SDK not found» при выполнении wails3 task android:run

Убедитесь, что переменная ANDROID_HOME задана и экспортирована. Проверьте это с помощью:

echo $ANDROID_HOME
ls $ANDROID_HOME/platform-tools/adb

Симулятор не загружается

Выведите список доступных симуляторов и вручную запустите один из них:

xcrun simctl list devices available
xcrun simctl boot "iPhone 16"

В chrome://inspect не отображаются объекты для отладки

WebView должен работать в режиме отладки (этот режим по умолчанию используется для android:run). Убедитесь, что запущена отладочная, а не промышленная сборка. Также проверьте, что adb devices показывает эмулятор как подключённый.

Отступы безопасной области не применяются

Убедитесь, что HTML содержит метатег viewport:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

Изучите Kitchen Sink

Когда ваше первое приложение заработает, пример Kitchen Sink позволит быстрее всего узнать о других возможностях. Это полноценное приложение Wails, которое запускается на iOS, Android и настольных платформах из единой кодовой базы и демонстрирует тактильную обратную связь, геолокацию, биометрию, локальные уведомления, защищённое хранилище и многое другое:

git clone https://github.com/wailsapp/wails.git
cd wails/v3/examples/mobile

wails3 task ios:run        # iOS Simulator
wails3 task android:run    # Android Emulator
wails3 task run            # Desktop

Просмотрите исходный код по адресу v3/examples/mobile — файлы native_features_ios.go и native_features_android.go особенно удобны как заготовки для копирования и вставки при реализации функций, специфичных для отдельных платформ.

Что дальше