In diesem Tutorial beginnen wir mit einer neuen React App und wechseln zu nativen Mobilentwicklungen mit Capacitor. Sie können auch Capgo Native Navigation und Transitions für eine nativere Mobilanwendung hinzufügen und tailwind-capacitor für sichere Bereiche verwenden.
Capacitor ermöglicht Ihnen, Ihre React-Webanwendung leicht in eine nativere Mobilanwendung umzuwandeln, ohne signifikante Änderungen oder das Erlernen einer neuen Fähigkeit wie React Native.
Mit nur wenigen einfachen Schritten können die meisten React-Anwendungen in Mobilanwendungen umgewandelt werden.
Dieses Tutorial führt Sie durch den Prozess, beginnend mit einer neuen React-Anwendung und dann die Einbindung von Capacitor zur Erschließung des Bereichs nativer mobiler 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 jedes Web-Projekt einbinden und es wird Ihre Anwendung in eine native WebView einhüllen, wodurch die native Xcode- und Android Studio-Projekte 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
Während es verschiedene Methoden gibt, um React-Anwendungen zu initiieren, gehen wir in diesem Tutorial für die einfachste Methode, die eine leere React-Anwendung bietet:
npx create-react-app my-appUm eine native mobile App zu erstellen, benötigen wir ein export des Projekts. Daher lassen wir ein einfaches Skript in unserem package.json einbinden, 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 nun npm run build ohne jede Sorge und Sie sollten ein frisches Ausgabeverzeichnis an der Wurzel Ihres Projekts erkennen können.
Dieses Verzeichnis wird später von Capacitor verwendet, aber für den Moment müssen wir es korrekt einrichten.
Capacitor zu Ihrer React-App hinzufügen
Um jede Web-App 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 Befehls. sync command.
Zuerst können wir das Capacitor CLI 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 __CAPGO_KEEP_0__ wird Verzeichnisse für jede Plattform an der Wurzel unseres Projekts erstellen:
Schließlich können wir die Plattformen hinzufügen, und Capacitor wird für jede Plattform einen Ordner am Root 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 androidBis zu diesem Punkt sollten Sie neue ios und Android Ordner in Ihrem React-Projekt.
Diese sind echte native Projekte!
Um auf das Android-Projekt später zuzugreifen, müssen Sie Android Studio. Für iOS benötigen Sie einen Mac und sollten Xcode.
Darüber hinaus sollten Sie ein capacitor.Konfigurationsdatei file in your project, which contains some fundamental Capacitor settings utilized during the sync. The only thing you need to pay attention to is the webDirdie muss auf das Ergebnis Ihres Build-Befehls verweisen. Derzeit ist sie ungenau.
Um dies zu korrigieren, öffnen Sie das capacitor.config.json Datei und aktualisieren Sie die webDir:
{
"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 syncDer erste Befehl npm run build wird einfach Ihr React-Projekt erstellen und den statischen Build exportieren.
Während der zweite Befehl npx cap sync alle Web code werden synchronisiert und in die richtigen Bereiche der nativen Plattformen platziert, damit sie in einer App angezeigt werden können.
werden alle Web-__CAPGO_KEEP_0__ in die richtigen Orte der nativen Plattformen synchronisieren, damit sie in einer App angezeigt werden können. Zusätzlich kann der Synchronisierungs-Befehl die nativen Plattformen aktualisieren und Plugins installieren, sodass, wenn Sie ein neues Capacitor-Plugin installieren, Es ist Zeit, loszulaufen. npx cap sync Wieder.
Ohne es zu merken, sind Sie jetzt tatsächlich fertig, also sehen wir das App auf einem Gerät!
Erstellen und Bereitstellen von nativen Apps
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 für iOS im Apple Developer Programm und für Android im Google Play Console anmelden.
Wenn Sie neu bei der nativen mobilen Entwicklung sind, können Sie die Capacitor CLI verwenden, um beide native Projekte leicht zu öffnen:
npx cap open ios
npx cap open androidEinmal Ihre native Projekte eingerichtet, ist die Bereitstellung Ihrer App auf einem verbundenen Gerät einfach. In Android Studio müssen Sie nur auf alles warten, und Sie können Ihre App auf einem verbundenen Gerät bereitstellen, ohne Einstellungen zu ändern. Hier ist ein Beispiel:
In Xcode müssen Sie Ihr Signierkonto einrichten, um Ihre App auf einem echten Gerät zu deployen, anstatt nur auf dem Simulator. Wenn Sie dies noch nicht getan haben, führt Xcode Sie durch den Prozess (aber wiederum 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
Sie sind wahrscheinlich bereits an Hot Reload mit allen modernen Frameworks gewöhnt und die gute Nachricht ist, dass Sie dasselbe 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 erhalten, indem Sie die Capacitor App laden, die den Inhalt von der spezifischen URL lädt.
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 im Terminal ausführen:
ipconfig getifaddr en0Laufen Sie auf Windows :
ipconfigDann suchen Sie nach der IPv4-Adresse.
Wir können Capacitor anweisen, die App direkt vom Server zu laden, indem wir eine weitere Eintrag in unserem capacitor.config.ts file:
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 verwenden, ich habe in diesem Beispiel die Standard-React-Port verwendet.
Jetzt können wir diese Änderungen anwenden, indem wir sie in unsere native Projekt kopieren:
npx cap copyDer copy Der Befehl ähnelt sich sync, aber er wird nur Die Änderungen im Web-Ordner übernehmen Sie und die Konfiguration, ohne das native Projekt zu aktualisieren.
Sie können Ihre App nun noch einmal über Android Studio oder Xcode bereitstellen. Anschließend, wenn Sie etwas in Ihrer React-App ändern, wird die App automatisch neu geladen und zeigt die Änderungen an!
Achten Sie darauf dass, wenn Sie neue Plugins wie die Kamera installieren, ein Neubuild Ihres native Projekts erforderlich ist. Dies liegt daran, dass native Dateien geändert werden und dies nicht auf der Fliege erfolgen kann.
Hinweis: Verwenden Sie bitte die richtige IP-Adresse und den Port in Ihrer Konfiguration. Der code-Block oben zeigt die Standard-React-Port für Demonstrationszwecke an.
Verwendung von Capacitor-Plugins
Schauen wir uns nun an, wie man ein Capacitor-Plugin in Aktion verwendet, das wir vorher mehrfach erwähnt haben. Um dies zu tun, können wir ein ziemlich einfaches Plugin installieren, indem wir Folgendes ausführen:
npm i @capacitor/shareEs ist nichts Besonderes an dem Teilen-PluginAber es öffnet den native Share Dialog trotzdem! Für dies, müssen wir nur das Paket importieren und die Funktion aufrufen. share() Die Funktion aus unserer App. src/App.js zu diesem:
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;Wie bereits erwähnt, müssen wir bei der Installation neuer Plugins eine Synchronisierungsoperation durchführen und die App dann auf unserem Gerät neu bereitstellen. Dazu führen Sie bitte folgende Kommando aus:
npx cap syncNachdem Sie auf den Button geklickt haben, können Sie den schönen native Share Dialog 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 Überflutung oder gekürzten sicheren Bereichen führen.
Mit natürlicher UI durch Capgo Native Navigation und Übergänge
Ich habe bereits seit Jahren mit Ionic Um cross-plattform-Anwendungen zu erstellen, aber die Integration mit React ist umständlich und selten lohnenswert, wenn Sie bereits eine Lösung haben Tailwind CSS.
Für ein nativ anführendes Mobile-Gefühl in einer React + Capacitor-App verwenden Sie Capgo-Plugins anstatt web-only UI-Kits wie Konsta UI:
- @capgo/capacitor-native-Navigation — nativere Leiste, Liquid Glass-Tasteleiste auf iOS und eine getönte Tasteleiste-Style auf Android. Ihr React-Router behält die Routenstatus; der Plugin besitzt die native Chrome.
- @capgo/capacitor-Übergänge — Seitenübergänge im Ionic-Stil und iOS-Rück-Edge-Swipe in der WebView-Schicht, ohne Ionic-UI zu übernehmen.
Installieren Sie beide:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit web-Content die native Leisten 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 getönte 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-pageund cap-contentund rufen Sie an setDirection('forward') oder setDirection('back') vor der Navigation. Duplizieren Sie Web-Überschriften oder -Fußzeilen nicht, wenn native Navigation diese Oberflächen besitzt.
Siehe die vollständigen Anleitungen: Mit @capgo/capacitor-native-Navigation und Mit @capgo/capacitor-Übergängen.
Sichere Bereiche mit Tailwind
Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (publikiert als) tailwind-capacitor auf npm veröffentlicht. Es bietet safe-areas Utilities und andere Capacitor-freundliche Tailwind-Plugins:
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Verwenden Sie Utilities wie pt-safe, pb-safe, und px-safe anstatt von überall env(safe-area-inset-*) manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre React-Einrichtung fehlt, Öffnen Sie ein PR auf GitHub.
Fixing iOS Layout Issues (Viewport, Safe Area, und Horizontal Overflow)
Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr overflow-x: hidden oder passen Sie die Viewport-Tags an, um es normalerweise nicht zu beheben. Arbeiten Sie durch diese Kontrollen in der Reihenfolge.
Stellen Sie sicher, dass der Viewport-Meta-Tag korrekt angewendet wird
Fügen Sie den Viewport-Meta-Tag in index.html inside <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />iOS-Sicherheitsbereich von einem einzigen Root-Wrapper behandeln
Erstellen Sie ein einzelnes App-Shell und fügen Sie dort die Sicherheitsbereich-Pufferung hinzu — 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);
}Alle Seite-Inhalte innerhalb .app-shell. Doppelte Sicherheitsbereich-Pufferung in Kopfzeilen, Modalen und Layout-Wrappern macht die UI oft gekürzt oder zu groß aussehen.
Mit @capgo/tailwind-capacitorkönnen Sie denselben Puffer mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf diesem einzelnen Shell ausdrücken.
Capacitor iOS contentInset auf never first
In capacitor.config.ts, bevorzugt native inset disabled und lasse CSS (oder Native Navigation’s) contentInsetMode: 'css') die sichere Fläche besitzen:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mischen Sie Capacitor’s automatische Inhaltsabstand mit CSS env(safe-area-inset-*) padding ist eine häufige Ursache für doppelten Abstand.
Finden Sie das überlaufende Element
Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, eine feste Pixelbreite oder eine große min-width.
In Safari Web Inspector, führen Sie aus:
[...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 durch w-full Wenn möglich. Viele horizontalen Überschreitungsprobleme kommen von 100vw / w-screendoppeltem sicheren Bereichs-Padding oder einem festsitzenden Container — nicht von der Viewport-Meta-Tags selbst.
Zusammenfassung
Capacitor ist eine hervorragende Option für die Erstellung von nativen Anwendungen auf der Basis eines bestehenden Web-Projekts, die eine einfache Möglichkeit bietet, code zu teilen und eine konsistente Benutzeroberfläche zu erhalten.
Und mit der Einführung von Capgo, ist es sogar einfacher, Live-Updates in Ihre App hinzuzufügen, um sicherzustellen, dass Ihre Benutzer immer Zugriff auf die neuesten Funktionen und Fehlerbehebungen haben.
Wenn Sie gerne erfahren 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 zum Planen der CI/CD-Automatisierung, mit ihm verbinden Capgo CI/CD zur Produktworkflow in Capgo CI/CD Capgo native Builds zur Produktworkflow in Capgo Native Builds Capgo Integrations zur Produktworkflow in Capgo Integrations CI/CD-Integration zur Implementierungsdetail in CI/CD-Integration und GitHub Aktionen-Integration zur Implementierungsdetail in GitHub Actions Integration
