In diesem Tutorial beginnen wir mit einer neuen React app and transition to native mobile development using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.
Mit Capacitor können Sie Ihre React-Web-Anwendung leicht in eine native mobile App umwandeln, 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 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, die native Xcode- und Android Studio-Projekte generiert. 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 ein Kinderspiel, es in Ihr Projekt zu integrieren. Vertrauen Sie mir, Sie werden sich wundern, wie leicht es ist, eine voll funktionsfähige native App mit Capacitor zu erreichen!
Vorbereitung Ihrer React-Anwendung
Während es verschiedene Methoden gibt, 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 ein, das verwendet werden kann, um das React-Projekt zu erstellen 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 weitermachen und sollten ein frisches Ausgabefolder an der Wurzel Ihres Projekts erkennen. npm run build Ohne weitere Sorgen sollten Sie ein frisches Ausgabefolder an der Wurzel Ihres Projekts erkennen.
This folder will be used by Capacitor later on, but for now, we must set it up correctly.
Adding Capacitor to Your React App
Um jede Web-App in einen nativen mobilen Container zu packen, müssen wir einige Schritte ausführen, aber danach ist es so einfach wie die Ausführung eines einzigen Befehls. sync Zuerst können wir das Capgo und das Capacitor als Entwicklungszusammenhänge 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. Capacitor CLI Bis zu diesem Punkt sollten Sie neue
Felder an der Wurzel Ihres Projekts erkennen.
Finally, we can add the platforms, and Capacitor will create folders for each platform at the root of our project:
# 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 Ordner an der Wurzel Ihres Projekts erkennen. 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 Studio. Für iOS benötigen Sie einen Mac und sollten Xcode.
Darüber hinaus sollten Sie ein capacitor.config.ts Datei in Ihrem Projekt finden, die einige grundlegende Capacitor-Einstellungen enthält, die während der Synchronisierung verwendet werden. Die einzige Sache, auf die Sie achten sollten, ist das webDir, welches auf das Ergebnis Ihres Befehls zur Erstellung verweist. Aktuell ist dies ungenau.
Um dies zu korrigieren, öffnen Sie das capacitor.config.json Datei und aktualisieren Sie das 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 baut einfach Ihr React-Projekt und exportiert die statische Ausgabe.
Während der zweite Befehl npx cap sync synchonisiert alle Web-code in die richtigen Orte der nativen Plattformen, damit sie in einer App angezeigt werden können.
Zusätzlich kann der Sync-Befehl die nativen Plattformen aktualisieren und Plugins installieren, sodass Sie ein neues Capacitor Plugins 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 ändern zu müssen. Hier ist ein Beispiel:
Um in Xcode Ihr Zertifikat zu konfigurieren, um Ihre App auf einem echten Gerät zu deployen, anstatt nur auf dem Simulator, müssen Sie Ihr Zertifikat einrichten. 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
Mit diesem Trick können Sie die gleiche Funktionalität wie Hot Reload mit allen modernen Frameworks auf einem mobilen Gerät haben, mit minimalen Anstrengungen! auf einem mobilen Gerät mit minimalen Anstrengungen
Zugriff auf Ihre lokal gehostete Anwendung mit Live Reload auf Ihrem lokalen Netzwerk indem die Capacitor-App 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 in der Terminal-Anwendung ausführen:
ipconfig getifaddr en0On Windows, führen Sie :
ipconfigDann suchen Sie nach der IPv4-Adresse.
Wir können Capacitor anweisen, die App direkt vom Server zu laden, indem wir eine weitere Eintragung in unsere 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 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 Befehl ähnelt sich sync, aber es wird nur die Änderungen im Web-Ordner übernehmen und die Konfiguration, ohne die native Projekt zu aktualisieren.
Sie können Ihr App nun 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!
Beachten Sie 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: 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.
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 der Plugin teilen, aber es bringt dennoch die native Share-Dialgog auf! Dafür müssen wir nun nur noch das Paket importieren und die share() Funktion in unserer App aufrufen. Lassen Sie uns die src/App.js ändern 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 Synchronisation durchführen und die App dann neu auf unserem Gerät bereitstellen. Dazu führen Sie bitte folgenden Befehl aus:
npx cap syncNachdem Sie auf den Button geklickt haben, können Sie den schönen native Share-Dialgog in Aktion erleben!
Als nächstes können Sie die App auf iOS und Android mit Capgo-Navigation und Übergängen noch nativer anfühlen lassen und häufige iOS-Anzeigefehler beheben, die zu horizontaler Überschreitung oder gekürzten sicheren Bereichen führen.
Natürlicher Anblick mit Capgo-Native-Navigation und -Übergängen
Ich habe bereits seit Jahren mit Ionic Um cross-plattform-Anwendungen zu erstellen, aber die Integration mit React ist hackig und selten wertvoll, wenn Sie bereits haben Tailwind CSS.
Für ein nativ mobil-gespür in einer React + Capacitor-Anwendung verwenden Sie stattdessen 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. Ihr React-Router behält die Routenstatus; der Plugin besitzt die native Chrome.
- @capgo/capacitor-transitions — Ionic-Style-Seitenübergänge und iOS-Rückblättern mit der Swipe-Technik 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 Balken respektiert:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Rendern Sie eine verschwommene 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 mit cap-router-outlet, cap-pageund, und cap-contentund anrufen setDirection('forward') oder setDirection('back') oder Sie rufen an
vor der Navigation. Duplizieren Sie keine Web-Überschriften oder -Fußzeilen, wenn native Navigation diese Oberflächen besitzt. Using @capgo/capacitor-native-navigation Mit @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-Navigation Using @capgo/capacitor-transitions.
Mit @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-Übergänge
Sichere Bereiche mit Tailwind @capgo/tailwind-capacitor @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ (als tailwind-capacitor On npm). Es bietet safe-areas Unterstützungs- 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 Unterstützungen wie pt-safe, pb-safe, und px-safe anstatt sie manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt – wenn etwas für Ihre React-Einrichtung fehlt, env(safe-area-inset-*) Öffnen Sie ein PR auf __CAPGO_KEEP_0__ open a PR on GitHub.
Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr
oder passen Sie die Viewport-Tags alleine an, um es normalerweise nicht zu beheben. Arbeiten Sie durch diese Kontrollen in der Reihenfolge. overflow-x: hidden Stellen Sie sicher, dass die Viewport-Metatag korrekt angewendet wird
iOS Layout Issues (Viewport, Safe Area, und Horizontal Overflow)
Die Ansicht fügen Sie die Meta-Tags Viewport hinzu index.html innerhalb <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Verwenden Sie iOS-Sicherheitsbereich nur von einem Root-Wrapper aus
Erstellen Sie eine einzelne App-Shell und fügen Sie dort Sicherheitsbereich-Padding zu — 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 Seite-Inhalte innerhalb .app-shellViele Duplikate von Sicherheitsbereich-Padding in Kopfzeilen, Modalen und Layout-Wrapper machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen.
Mit @capgo/tailwind-capacitorkönnen Sie denselben Padding mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzelnen Hülle ausdrücken.
Setzen Sie Capacitor iOS contentInset auf "__CAPGO_KEEP_1__" never In der Regel
Vorziehen Sie native Einstellungen, deaktivieren Sie und lassen Sie CSS (oder Native Navigation’s) capacitor.config.tseigenen sicheren Bereich: contentInsetMode: 'css'Mischen Sie __CAPGO_KEEP_0__’s automatische Inhaltseinstellung mit CSS
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Finden Sie das überlaufende Element
Der übliche Täter ist ein Element, das
, Tailwind 100vw, eine feste Pixelbreite oder eine große w-screenIn Safari Web Inspector, führen Sie aus: min-width.
Mit Tailwind ersetzen 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 mit w-full wenn möglich. Viele horizontalen Überschreitungsprobleme kommen von 100vw / w-screen, dupliziertem sicheren Bereichsabstand oder einem festsitzenden Container — nicht von der Viewport-Meta-Tags selbst.
Zusammenfassung
Capacitor ist eine hervorragende Option für die Erstellung nativer 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 Einfügung von CapgoKontext: HTML-Textfragment aus einem längeren Capgo-UI-String (Mutter-Schlüssel `submitting_a_pr_to_capgo`). Seite/Bereich: Capgo-Marketing-Website. Rolle: Website-Kopie-Satz. Gesehen in: Seite contributing.astro. Erhalte Capgo-Produkt-/Marken- und Entwicklertitel genau.
If you would like to learn how to add Capgo to your React app, take a look at the next article:
Wenn Sie gerne wissen möchten, wie Sie Capacitor 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 __CAPGO_KEEP_0__ Wenn Sie Capacitor verwenden um die CI/CD-Automatisierung zu planen, mit ihr zu 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 Actions Integration zur Implementierungsdetail in GitHub Actions Integration
