Ihre erste mobile App

In dieser Anleitung führen Sie eine standardmäßige Wails-Desktop-App im iOS-Simulator oder Android-Emulator aus. Sie müssen Ihren Go-Code nicht ändern. Derselbe main.go wird für alle Zielplattformen erstellt.

Benötigte Zeit: 15–30 Minuten (der Großteil davon entfällt beim ersten Durchlauf auf die Installation der Toolchain)

Mit einem Desktop-Projekt beginnen

Falls Sie noch keines haben, erstellen Sie ein neues Projekt:

wails3 init -n mymobileapp
cd mymobileapp

Prüfen Sie zunächst, ob die Desktop-App funktioniert:

wails3 dev

Sobald sie geöffnet ist, beenden Sie sie und fahren Sie fort. Alles, was auf dem Desktop läuft, läuft auch auf Mobilgeräten — für diese Anleitung müssen Sie weder main.go noch anderen Go-Code ändern.

Plattform auswählen

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

Was ist geschehen?

Ihr main.go wurde überhaupt nicht geändert. Wails hat alles übernommen:

• Build-System — Taskfile.yml in Ihrem Projekt enthält die Tasks ios:* und android:*, die die plattformspezifische Toolchain steuern.
• Go-Cross-Kompilierung — GOOS=ios oder GOOS=android mit dem passenden GOARCH und Sysroot.
• Nativer Host — ein generiertes Xcode-Projekt (iOS) oder Gradle-Projekt (Android), das Ihren kompilierten Go-Code einbettet und die WebView hostet.
• Bereitstellung von Assets — Ihr frontend/dist/ wird in die Go-Binärdatei eingebettet und innerhalb des Prozesses bereitgestellt. Ein localhost-Server ist nicht erforderlich.

Ihre App für Mobilgeräte optimieren

Ihre App funktioniert bereits, sieht auf einem Smartphone-Bildschirm aber wie eine Desktop-App aus. Einige kleine Änderungen bewirken viel.

Responsives CSS

Bildschirme von Mobilgeräten sind schmaler und verwenden andere Eingabemuster. In frontend/public/style.css (oder einer entsprechenden Datei):

/* 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);
}

Plattform in Go erkennen

Verwenden Sie Build-Tags, um plattformspezifisches Verhalten hinzuzufügen, ohne den gemeinsam genutzten Code unübersichtlich zu machen.

Erstellen Sie mobile_ios.go für Code, der ausschließlich unter iOS verwendet wird:

//go:build ios

package main

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

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

Erstellen Sie mobile_android.go für Code, der ausschließlich unter Android verwendet wird:

//go:build android

package main

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

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

Erstellen Sie mobile_desktop.go als Stub, damit der gemeinsam genutzte Code auch für Desktop-Plattformen kompiliert wird:

//go:build !ios && !android

package main

type mobileOptions struct{}

func platformOptions() mobileOptions { return mobileOptions{} }

Plattform in JavaScript erkennen und ausschließlich mobile Benutzeroberflächen gezielt aktivieren

Die Runtime-Objekte IOS.* und Android.* sind jeweils nur auf der entsprechenden Plattform vorhanden. Wenn Sie sie auf einer Desktop-Plattform aufrufen, wird eine Exception ausgelöst. Das richtige, auch vom Kitchen Sink verwendete Muster besteht darin, die Plattform einmal zu erkennen und ausschließlich für Mobilgeräte bestimmte Steuerelemente vollständig auszublenden:

// 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';
});

Anschließend in Ihrem HTML:

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

So werden ausschließlich für Mobilgeräte bestimmte Schaltflächen auf Desktop-Plattformen nie gerendert, und Sie müssen nicht jeden einzelnen Aufruf durch eine if (isMobile)-Prüfung absichern.

Kombinieren Sie dies auf der Go-Seite mit einem Build-Tag-Stub, damit die Event-Handler nur auf den Plattformen registriert werden, die sie benötigen:

//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
}

Genau dieses Muster verwendet der Kitchen Sink — siehe native_features_stub.go, native_features_ios.go und native_features_android.go.

Haptisches Feedback hinzufügen (iOS)

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

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

Vibration hinzufügen (Android)

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

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

Für den Produktivbetrieb bauen

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

Fehlerbehebung

wails3 task ios:run schlägt mit “no iOS SDKs found” fehl

Die vollständige Xcode-Version muss installiert und ausgewählt sein:

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

wails3 task android:run schlägt mit “SDK not found” fehl

Stellen Sie sicher, dass ANDROID_HOME festgelegt und exportiert ist. Überprüfen Sie dies mit:

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

Simulator startet nicht

Listen Sie die verfügbaren Simulatoren auf und starten Sie einen davon manuell:

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

chrome://inspect zeigt keine Ziele an

Die WebView muss sich im Debug-Modus befinden (der Standard für android:run). Stellen Sie sicher, dass Sie einen Debug-Build und keinen Produktions-Build ausführen. Prüfen Sie außerdem, ob adb devices den Emulator als verbunden anzeigt.

Safe-Area-Abstände werden nicht angewendet

Stellen Sie sicher, dass Ihr HTML das Viewport-Meta-Tag enthält:

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

Kitchen Sink erkunden

Sobald Ihre erste App läuft, ist das Beispiel Kitchen Sink der schnellste Weg, weitere Möglichkeiten kennenzulernen. Es ist eine vollständige Wails-App, die mit einer einzigen Codebasis unter iOS, Android und auf Desktop-Systemen läuft und unter anderem Haptik, Geolokalisierung, Biometrie, lokale Benachrichtigungen und sichere Speicherung abdeckt:

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

Sehen Sie sich den Quellcode unter v3/examples/mobile an. Insbesondere die Dateien native_features_ios.go und native_features_android.go eignen sich als Ausgangspunkte zum Kopieren und Einfügen für plattformspezifische Funktionen.

Wie geht es weiter?