Mobile Apps mit React und Capacitor erstellen

In diesem Tutorial beginnen wir mit einer neuen React Anwendung und wechseln zu nativen mobilen Entwicklungen mit Capacitor. Sie können auch Capgo Native Navigation und Transitions hinzufügen, um ein nativ mobil aussehendes Ergebnis zu erhalten, und tailwind-capacitor für sichere Bereiche verwenden.

Capacitor ermöglicht es Ihnen, Ihre React-Web-Anwendung leicht in eine native mobile App umzuwandeln, ohne bedeutende Änderungen oder das Erlernen einer neuen Fähigkeit wie React Native.

With nur wenigen einfachen Schritten können die meisten React-Anwendungen in mobile Apps umgewandelt werden.

Dieses Tutorial führt Sie durch den Prozess, beginnend mit einer neuen React-Anwendung und dann die Einbindung von Capacitor zur Eingabe in die Welt der nativen mobilen Apps. Sie können auch Capgo Native Navigation, Transitions und tailwind-capacitor für sichere Bereiche verwenden.

Über Capacitor

CapacitorJS ist ein Game-Changer! Sie können es problemlos in jede Web-Projekt einbinden und es wird Ihre Anwendung in eine native WebView einhüllen, wodurch die native Xcode- und Android Studio-Projekt generiert werden. Darüber hinaus bieten seine Plugins Zugriff auf native Gerätefeatures wie die Kamera über eine JS-Brücke.

Mit Capacitor erhalten Sie eine fantastische native mobile App ohne komplizierten Setup oder steilen Lernkurve. Sein schlanker API und gestreamtete Funktionalität machen es zu einem Kinderspiel, es in Ihr Projekt zu integrieren. Vertrauen Sie mir, Sie werden sich wundern, wie einfach es ist, eine voll funktionsfähige native App mit Capacitor zu erreichen!

Vorbereitung Ihrer React-Anwendung

Bei verschiedenen Methoden zur Initialisierung von React-Anwendungen gehen wir in diesem Tutorial für die einfachste Methode, die eine leere React-Anwendung bietet:

npx create-react-app my-app

Um eine native mobile App zu erstellen, benötigen wir ein export des Projekts. Daher fügen wir einen einfachen Skript in unserem package.json ein, das verwendet werden kann, um das React-Projekt zu bauen und zu exportieren:

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  }
}

Sie können jetzt ohne Sorgen ausführen und sollten ein frisches Ausgabeverzeichnis an der Wurzel Ihres Projekts erkennen. npm run build Ohne jegliche Sorgen ausführen und sollten Sie ein frisches Ausgabeverzeichnis an der Wurzel Ihres Projekts erkennen.

Dieses Verzeichnis wird später von Capacitor verwendet, aber für den Moment müssen wir es korrekt einrichten.

Capacitor in Ihrer React-Anwendung hinzufügen

Um jede Webanwendung in einen nativen mobilen Container zu packen, müssen wir einige erste Schritte befolgen, aber danach ist es so einfach wie die Ausführung eines einzigen sync Befehls.

Zuerst können wir das Capacitor CLI als Entwicklungszusammenhang installieren und dann innerhalb unseres Projekts einrichten. Während der Einrichtung können Sie auf "Enter" drücken, um die Standardwerte für Namen und Bundle-ID zu akzeptieren.

Als nächstes müssen wir das Kernpaket und die relevanten Pakete für die iOS- und Android-Plattformen installieren.

Schließlich können wir die Plattformen hinzufügen und Capacitor wird Verzeichnisse für jede Plattform an der Wurzel unseres Projekts erstellen:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your React project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

Bis zu diesem Punkt sollten Sie neue iOS und Android Ordner in Ihrem React-Projekt.

Das sind echte native Projekte!

Um auf das Android-Projekt später zuzugreifen, müssen Sie Android Studioinstallieren. Für iOS benötigen Sie einen Mac und sollten Xcode.

Darüber hinaus sollten Sie ein capacitor.config.ts Konfigurationsdatei in Ihrem Projekt finden, die einige grundlegende Capacitor-Einstellungen enthält, die während der Synchronisierung verwendet werden. Auf die einzige Sache sollten Sie achten: webVerzeichnis, das auf das Ergebnis Ihres Build-Befehls verweisen muss. Derzeit ist es ungenau.

Um dies zu korrigieren, öffnen Sie das capacitor.config.json Datei und aktualisieren Sie das webVerzeichnis:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "out",
  "bundledWebRuntime": false
}

Sie können es ausprobieren, indem Sie die folgenden Befehle ausführen:

npm run build
npx cap sync

Der erste Befehl npm run build wird einfach Ihr React-Projekt bauen und das statische Build-ergebnis exportieren.

Während der zweite Befehl npx cap sync synchronisiert alle Web code in die richtigen Orte der nativen Plattformen, damit sie in einer App angezeigt werden können.

Zusätzlich kann der Synchronisierungs-Befehl die nativen Plattformen aktualisieren und Plugins installieren, sodass bei der Installation eines neuen Capacitor Plugins Es ist Zeit, loszulegen npx cap sync wieder.

Ohne es zu merken, sind Sie jetzt tatsächlich fertig, also sehen wir mal das App auf einem Gerät!

Nativo-Apps erstellen und bereitstellen

Um iOS-Apps zu entwickeln, benötigen Sie Xcode installiert, und für Android-Apps benötigen Sie Android Studio installiert. Darüber hinaus müssen Sie, wenn Sie Ihre App im App Store verteilen möchten, sich im Apple Developer Programm für iOS und im Google Play Console für Android anmelden.

Wenn Sie neu bei der nativen mobilen Entwicklung sind, können Sie die Capacitor CLI verwenden, um beide nativen Projekte leicht zu öffnen:

npx cap open ios
npx cap open android

Einmal haben Sie Ihre nativen Projekte eingerichtet, ist es leicht, Ihre App auf einem verbundenen Gerät zu deployen. In Android Studio müssen Sie nur auf alles warten, bis alles bereit ist, und Sie können Ihre App auf einem verbundenen Gerät deployen, ohne dass Sie die Einstellungen ändern müssen. Hier ist ein Beispiel:

Um in Xcode eine Signierungsanmeldung einzurichten, um die App auf einem echten Gerät zu deployen, anstatt nur auf dem Simulator, müssen Sie die Signierungsanmeldung einrichten. Wenn Sie dies noch nicht getan haben, führt Xcode Sie durch den Prozess (aber wieder müssen Sie sich im Entwicklerprogramm angemeldet haben). Anschließend können Sie einfach auf 'Play' klicken, um die App auf Ihrem verbundenen Gerät auszuführen, das Sie oben auswählen können. Hier ist ein Beispiel:

Herzlichen Glückwunsch! Sie haben erfolgreich Ihre React-Web-App auf einem mobilen Gerät bereitgestellt. Hier ist ein Beispiel:

Aber warten Sie, es gibt auch eine schnellere Möglichkeit, dies während der Entwicklung zu tun…

Capacitor Live Reload

Bis jetzt sind Sie wahrscheinlich daran gewöhnt, Hot Reload mit allen modernen Frameworks zu haben, und die gute Nachricht ist, dass Sie die gleiche Funktionalität auf einem mobilen Gerät mit minimalen Anstrengungen haben können!

Zugriff auf Ihre lokal gehostete Anwendung mit Live Reload auf Ihrem Netzwerk durch das Laden des Capacitor-Apps von der spezifischen URL.

Der erste Schritt besteht darin, Ihre lokale IP-Adresse zu ermitteln. Wenn Sie einen Mac verwenden, können Sie dies herausfinden, indem Sie den folgenden Befehl in der Terminal-Anwendung ausführen:

ipconfig getifaddr en0

Führen Sie auf Windows : aus.

ipconfig

Suchen Sie dann nach der IPv4-Adresse.

Wir können Capacitor anweisen, das App direkt vom Server zu laden, indem wir eine weitere Eintrag in unserem capacitor.config.ts Datei hinzufügen.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'out',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:3000',
    cleartext: true
  }
};

export default config;

Stellen Sie sicher, dass Sie die richtige IP-Adresse und den Port verwendenIch habe in diesem Beispiel die Standard-React-Port verwendet.

Nun können wir diese Änderungen anwenden, indem wir sie in unser natives Projekt übertragen:

npx cap copy

Der copy Befehl ähnelt sich syncaber es wird nur die Änderungen im Web-Ordner und die Konfiguration, ohne die native Projekt zu aktualisieren.

Sie können Ihre App noch einmal über Android Studio oder Xcode bereitstellen. Anschließend, wenn Sie etwas in Ihrer React-App ändern, die App wird automatisch neu geladen und zeigt die Änderungen an!

Achten Sie darauf dass wenn Sie neue Plugins wie die Kamera installieren, ein Neubuild des native Projekts erforderlich ist. Dies liegt daran, dass native Dateien geändert werden und dies nicht auf der Fliege erfolgen kann.

Hinweis: Sie sollten die richtige IP-Adresse und den Port in Ihrer Konfiguration verwenden. Der code-Block oben zeigt die Standard-React-Port für Demonstrationszwecke an.

Mit Capacitor-Plugins

Schauen wir uns an, wie man ein Capacitor-Plugin in Aktion verwendet, von dem wir bereits mehrfach gesprochen haben. Um dies zu tun, können wir ein ziemlich einfaches Plugin installieren, indem wir folgendes ausführen:

npm i @capacitor/share

Es gibt nichts Besonderes an diesem Plugin teilen, aber es bringt dennoch die native Share-Dialgog auf! Für dies, müssen wir nun nur noch das Paket importieren und die share() Funktion in unserer App aufrufen. Lassen Sie uns das src/App.js in folgende ändern:

import React from 'react';
import { Share } from '@capacitor/share';

function App() {
  const share = async () => {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends'
    });
  };

  return (
    <div>
      <h1>Welcome to React and Capacitor!</h1>
      <p>
        <h2>Cool channel</h2>
        <button onClick={() => share()}>Share now!</button>
      </p>
    </div>
  );
}

export default App;

Als erwähnt, müssen wir bei der Installation neuer Plugins eine Synchronisierungsoperation durchführen und die App dann neu auf unserem Gerät bereitstellen. Dazu führen Sie bitte folgende Kommando aus:

npx cap sync

Nachdem Sie auf den Button geklickt haben, können Sie das schöne native Share-Dialgog in Aktion erleben!

Als nächstes können Sie die App mit Capgo Navigation und Übergängen noch nativer auf iOS und Android machen und häufige iOS-Anzeige-Probleme lösen, die zu horizontaler Überfluss oder gekürzten sicheren Bereichen führen.

Native-fühlende UI mit Capgo Native Navigation und Übergängen

Ich habe bereits seit Jahren mit Ionic um plattformübergreifende Anwendungen zu erstellen, aber die Integration mit React ist hackig und selten wertvoll, wenn Sie bereits haben Tailwind CSS.

Für ein nativ mobilartiges Gefühl in einer React + Capacitor-Anwendung verwenden Sie Capgo-Plugins anstatt web-only-UI-Kits wie Konsta UI:

• @capgo/capacitor-native-navigation — nativere Navigation, Liquid Glass-Tasteleiste auf iOS und eine verschwommene Tasteleiste-Style auf Android. Ihre React-Router behält die Routenstatus; der Plugin besitzt die native Chrome.
• @capgo/capacitor-transitions — Seitenübergänge im Ionic-Stil und iOS-Rückwärts-Schub auf der WebView-Ebene, ohne Ionic-UI zu übernehmen.

Installieren Sie beide:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Konfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit das Webinhalts die native Balken respektiert:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendern Sie eine Liquid Glass-Tasteleiste (iOS verwendet die Systemeigene Rendering; Android verwendet eine verschwommene WebView-Hintergrund):

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  navigate(`/${id}`);
});

Fügen Sie native Seitenübergänge in Ihrem App-Shell hinzu:

import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

export function AppShell() {
  const navigate = useNavigate();
  const outletRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (outletRef.current) {
      setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
    }
  }, []);

  const openSettings = () => {
    setDirection('forward');
    navigate('/settings');
  };

  return <cap-router-outlet ref={outletRef}>{/* routes */}</cap-router-outlet>;
}

Umgehen Sie die gerouteten Seiten in cap-router-outlet, cap-page, und cap-content, und aufrufen setDirection('forward') oder setDirection('back') Bevor Sie navigieren. Duplikate Web-Ober- und -Unterschriften, wenn native Navigation diese Ober- und Unterschriften besitzt.

Siehe die vollständigen Anleitungen: Verwenden Sie @capgo/capacitor-native-Navigation und Verwenden Sie @capgo/capacitor-Übergänge.

Sichere Bereiche mit Tailwind

Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (als tailwind-capacitor auf npm). Es bietet safe-areas Nutzungshilfen und andere Capacitor-freundliche Tailwind-Plugins:

bun add -D tailwind-capacitor

In src/index.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Verwenden Sie Nutzungsanleitungen wie pt-safe, pb-safe, und px-safe anstatt sie env(safe-area-inset-*) manuell hinzuzufügen. Das Projekt wird aktiv weiterentwickelt – wenn etwas für Ihre React-Konfiguration fehlt, Öffnen Sie ein Pull-Request auf GitHub.

iOS-Layoutprobleme beheben (Viewport, Safe Area und horizontale Überschreitung)

Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, overflow-x: hidden Hinzufügen oder Anpassen des Viewport-Tags allein löst das Problem normalerweise nicht. Arbeiten Sie durch diese Kontrollen in der Reihenfolge.

Stellen Sie sicher, dass die Viewport-Metatag korrekt angewendet wird

Fügen Sie die viewport-Metatag hinzu index.html innerhalb <head>:

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

Behandeln Sie den sicheren Bereich von iOS aus einer einzigen Root-Wrapper

Erstellen Sie ein einzelnes App-Shell und fügen Sie dort den sicheren Bereich ein — nicht in mehreren verschachtelten Komponenten:

html,
body,
#root {
  width: 100%;
  min-height: 100%;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

* {
  box-sizing: border-box;
}

.app-shell {
  min-height: 100dvh;
  width: 100%;
  padding-top: env(safe-area-inset-top);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
}

Umgeben Sie alle Seiteninhalte innerhalb .app-shellDoppelte sichere Bereichsabstände in Kopfzeilen, Modalen und Layout-Wrapper sehen oft gekürzt oder zu groß aus.

Mit @capgo/tailwind-capacitor, können Sie denselben Abstand mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf diesem einzelnen Shell.

Setzen Sie Capacitor iOS contentInset auf never erste

In capacitor.config.ts, bevorzugt native inset deaktiviert und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css') das sichere Bereich besitzen:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'dist',
  ios: {
    contentInset: 'never',
  },
};

Mischen Sie Capacitor’s automatische Inhalts-Einrastung mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelte Abstände.

Finden Sie das überlaufende Element

Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, einen fixen Pixel-Breite oder eine große min-width.

In Safari Web Inspector, ausführen Sie:

[...document.querySelectorAll('*')]
  .filter(el => el.scrollWidth > document.documentElement.clientWidth)
  .map(el => ({
    el,
    tag: el.tagName,
    class: el.className,
    scrollWidth: el.scrollWidth,
    clientWidth: document.documentElement.clientWidth,
  }));

Mit Tailwind ersetzen Sie w-screen With w-full Wenn möglich. Viele horizontale Überschreitung von Problemen kommen von 100vw / w-screen, Duplizierte sichere Bereichsabstand oder ein fester Breitencontainer — nicht von der Viewport Meta-Tag selbst.

Zusammenfassung

Capacitor ist eine hervorragende Option für die Erstellung von nativen Anwendungen auf der Grundlage eines bestehenden Web-Projekts, die eine einfache Möglichkeit bietet, code zu teilen und eine konsistente Benutzeroberfläche zu erhalten.

Und mit der Zugabe von Capgo, ist es sogar einfacher, live Aktualisierungen in Ihre App hinzuzufügen, sodass Ihre Benutzer immer Zugriff auf die neuesten Funktionen und Fehlerbehebungen haben.

Wenn Sie gerne wissen möchten, wie Sie Capgo in Ihre React-App hinzufügen können, nehmen Sie einen Blick auf das nächste Artikel:

Fortsetzen Sie von Building Mobile Apps with React und Capacitor

Wenn Sie mit Building Mobile Apps with React und Capacitor für die Automatisierung von CI/CD zu planen, mit ihm verbunden Capgo CI/CD für den Produktworkflow in Capgo CI/CD Capgo Native Builds für den Produktworkflow in Capgo Native Builds Capgo Integrations für den Produktworkflow in Capgo Integrations CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration und GitHub Actions-Integration für die Implementierungsdetails in GitHub Actions-Integration