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 einem nativen mobilen Gefühl zu entsprechen, 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 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 Umstellung 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 leicht in jedes Web-Projekt einbinden, und es wird Ihre Anwendung in eine native WebView einhüllen, die native Xcode- und Android Studio-Projekte generiert. Zudem 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 komplizierte Einrichtung oder steile Lernkurve. Sein schlanker API und gestreamlinertes Funktionsdesign machen es ein 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!
Ihre React-App vorbereiten
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 unseres Projekts. Daher fügen 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 npm run build ohne Sorgen ausführen, und Sie sollten ein frisches Verzeichnis in 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 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 sync Befehls.
Zunächst 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 Ordner für jede Plattform 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 beobachten können.
Dies sind echte native Projekte!
Um später auf das Android-Projekt zuzugreifen, müssen Sie Android Studioinstallieren. Für iOS benötigen Sie einen Mac und sollten Xcode.
installieren. Zusätzlich sollten Sie ein capacitor.config.ts 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 __CAPGO_KEEP_0__-Einstellungen enthält, die während der Synchronisierung verwendet werden. Die einzige Sache, auf die Sie achten sollten, ist die
webDir 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 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, wenn Sie ein neues Capacitor-Plugin installieren es Zeit ist, npx cap sync wieder zu laufen.
Ohne es zu merken, sind Sie jetzt tatsächlich fertig, also sehen wir uns das App auf einem Gerät an!
native Apps entwickeln 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 benötigen Sie, wenn Sie Ihre App im App Store verteilen möchten, eine Registrierung im Apple Developer Programm für iOS und im Google Play Console für Android.
Wenn Sie mit der Entwicklung nativer mobiler Apps neu sind, können Sie die Capacitor CLI verwenden, um beide native Projekte leicht zu öffnen:
npx cap open ios
npx cap open androidSobald Sie Ihre native Projekte eingerichtet haben, ist die Bereitstellung Ihrer App auf einem verbundenen Gerät einfach. 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 bereitstellen, ohne dass Sie Einstellungen ändern müssen. Hier ist ein Beispiel:
In Xcode müssen Sie Ihre Signierungsaccount einrichten, um Ihre App auf einem realen Gerät bereitzustellen, anstatt nur auf dem Simulator. Wenn Sie das noch nicht getan haben, führt Xcode Sie durch den Prozess (aber wiederum benötigen Sie eine Registrierung im Developer Programm). 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 halt die Sache, es gibt auch eine schnellere Möglichkeit, dies während der Entwicklung zu tun…
Capacitor Live Reload
Bis jetzt bist du wahrscheinlich daran gewöhnt, dass du bei allen modernen Frameworks Hot Reload hast, und die gute Nachricht ist, dass du die gleiche Funktionalität auf einem mobilen Gerät mit minimalen Anstrengungen haben kannst!
Zugriff auf deine lokal gehostete Anwendung mit Live Reload auf deinem Netzwerk erhalten, indem du die Capacitor App so einrichtest, dass sie den Inhalt von der spezifischen URL lädt.
Der erste Schritt besteht darin, deine lokale IP-Adresse zu ermitteln. Wenn du einen Mac verwendest, kannst du dies herausfinden, indem du den folgenden Befehl in der Terminal-Anwendung ausführst:
ipconfig getifaddr en0Auf Windows ausführen:
ipconfigDann such nach der IPv4-Adresse.
We können Capacitor anweisen, die App direkt vom Server zu laden, indem wir ein weiteres Eintrag in unsere capacitor.config.ts Datei:
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;Achten Sie darauf, die richtige IP-Adresse und den richtigen Port zu verwenden Ich habe in diesem Beispiel den Standard-React-Port verwendet.Jetzt können wir diese Änderungen anwenden, indem wir sie in unser natives Projekt übernehmen:
Der
npx cap copyBefehl ähnelt sich copy , aber er wird nur syncdie Änderungen in der Web-Folder und Konfiguration übernehmen, ohne das natives 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 Änderungen werden automatisch in Ihr natives Projekt übernommen.
Sie können Ihre App jetzt noch einmal über Android Studio oder Xcode bereitstellen. Anschließend, wenn Sie etwas in Ihrer React-App ändern, The App wird automatisch neu geladen und zeigt die Änderungen!
Beachten Sie dass Sie, wenn Sie neue Plugins wie die Kamera installieren, immer noch eine Neuverteilung Ihres nativen Projekts durchführen müssen. Dies liegt daran, dass native Dateien geändert werden und dies nicht auf der Flugschneise 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 an, wie man ein Capacitor-Plugin in Aktion verwendet, das wir bereits mehrfach erwähnt haben. Dazu können wir ein ziemlich einfaches Plugin installieren, indem wir Folgendes ausführen:
npm i @capacitor/shareEs ist nichts Besonderes an dem Teilen-Plugin, aber es bringt trotzdem den native Teilen-Dialog auf! share() Für dies benötigen wir jetzt nur noch die Pakete zu importieren und die Funktion in unserer App aufzurufen. Lassen Sie uns die Datei "src/App.js" ändern. To 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;Wenn Sie neue Plugins installieren, müssen Sie eine Synchronisierungsoperation durchführen und dann die App auf Ihrem Gerät neu bereitstellen. Um dies zu tun, führen Sie bitte folgende Befehl aus:
npx cap syncNachdem Sie auf den Button geklickt haben, können Sie das schöne native Share-Dialog in Aktion sehen!
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-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 in den letzten Jahren mit Capacitor gearbeite, um cross-plattformische Anwendungen zu bauen, aber die Integration mit React ist hackig und selten wertvoll, wenn Sie bereits Tailwind CSS.
For a native mobile feel in a React + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- Für einen nativen mobilen Look in einer React + capgo-App verwenden Sie stattdessen capacitor-Plugins anstelle von web-only UI-Kits wie Konsta UI: — native Navbar, Liquid Glass Tabbar auf iOS und eine verschwommene Tabbar-Stil auf Android. Ihre React-Router-Route-Status bleibt erhalten; der Plugin besitzt die native Chrome.
- @capgo/capacitor-Übergänge — Seitenübergänge im Ionic-Stil und iOS-Rückblättern am Rand 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 Webinhalte die native Balken respektieren:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Rendern Sie einen Liquid Glass Tabbar (iOS verwendet die Systemeigene Rendering; Android verwendet einen verschwommenen 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>;
}Umfasst die gerouteten Seiten in cap-router-outlet, cap-page, und cap-content, und rufen Sie setDirection('forward') oder setDirection('back') vor der Navigation auf. Duplizieren Sie Web-Über- oder Fußzeilen nicht, wenn die native Navigation diese Oberflächen besitzt.
Siehe die vollständigen Anleitungen: Mit @capgo/capacitor-native-navigation und Mit @capgo/capacitor-transitions.
Sichere Bereiche mit Tailwind
Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (veröffentlicht als tailwind-capacitor auf npm). Es bietet safe-areas Hilfsfunktionen 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 Hilfsfunktionen wie pt-safe, pb-safeund px-safe anstatt, dass man es env(safe-area-inset-*) von Hand. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre React-Einrichtung fehlt, Öffnen Sie einen PR auf GitHub.
iOS-Layoutprobleme beheben (Viewport, Safe Area und horizontale Überschuss)
Wenn Inhalte auf iOS gekürzt, verschoben oder horizontal scrollbar aussehen, fügen Sie mehr overflow-x: hidden oder passen Sie den Viewport-Tag allein normalerweise nicht aus. 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 innerhalb <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Behandeln Sie das iOS-Safe-Area nur von einem Root-Wrapper aus
Erstellen Sie ein einzelnes App-Shell und fügen Sie dort Safe-Area-Padding 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 Seiteninhalte innerhalb einhüllen .app-shellDoppelte sichere Bereichsabstände in Kopfzeilen, Modalen und Layout-Wrappern machen die Benutzeroberfläche oft gekürzt oder zu groß aussehen.
Mit @capgo/tailwind-capacitor, können Sie denselben Abstand mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf dieser einzelnen Shell.
Setzen Sie Capacitor iOS contentInset auf never erst
In capacitor.config.ts, bevorzugt native inset disabled und lassen Sie CSS (oder Native Navigation’s contentInsetMode: 'css') den sicheren Bereich besitzen:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mischen Sie Capacitor’s automatische Inhaltsabstände mit CSS env(safe-area-inset-*) Ein zu großes 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, eine fixe 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 mit w-full wenn möglich. Viele horizontale Überlaufprobleme kommen von 100vw / w-screen, dupliziertem sicherem Abstand oder einem festen Breitencontainer — nicht von der Viewport-Metatag selbst.
Zusammenfassung
Capacitor ist eine hervorragende Option für die Erstellung nativer 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 Hinzufügung von Capgo, ist es sogar einfacher, Live-Updates in Ihrer App hinzuzufügen, sodass Ihre Benutzer immer Zugriff auf die neuesten Funktionen und Fehlerbehebungen haben.
Wenn Sie gerne erfahren möchten, wie Sie Capgo in Ihrer React-App hinzufügen können, nehmen Sie einen Blick auf das nächste Artikel:
Fortsetzen Sie von Building Mobile Apps mit React und Capacitor
Wenn Sie "Building Mobile Apps mit React und __CAPGO_KEEP_0__" verwenden, um die CI/CD-Automatisierung zu planen, verbinden Sie es mit Capacitor CI/CD für den Produktworkflow in __CAPGO_KEEP_0__ CI/CD, Capgo Native Builds Capgo ist eine großartige Möglichkeit, native Apps zu erstellen, indem Sie auf bestehende Web-Projekte zurückgreifen, und bietet eine einfache Möglichkeit, __CAPGO_KEEP_1__ zu teilen und eine konsistente Benutzeroberfläche zu erhalten. Capgo ermöglicht Ihnen, Live-Updates in Ihrer App hinzuzufügen, sodass Ihre Benutzer immer Zugriff auf die neuesten Funktionen und Fehlerbehebungen haben. für das Produktworkflow in Capgo Native Builds, Capgo Integrations für das Produktworkflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetail in CI/CD-Integration, und GitHub Actions-Integration für die Implementierungsdetail in GitHub Actions-Integration.
