In questo tutorial, inizieremo con un nuovo 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.
Capacitor consente di convertire facilmente la tua applicazione web React in un'app mobile nativa senza modifiche significative o l'apprendimento di una nuova abilità come React Native.
Con solo pochi passaggi semplici, la maggior parte delle applicazioni React possono essere trasformate in app mobili.
Questo tutorial ti guiderà attraverso il processo, iniziando con una nuova app React e poi incorporando Capacitor per entrare nel mondo degli app mobili native. Puoi anche utilizzare Capgo per la navigazione nativa, le transizioni e tailwind-capacitor per aree sicure.
About Capacitor
CapacitorJS è un vero cambiamento! Puoi incorporarlo facilmente in qualsiasi progetto web, e lo renderà in un webview nativo, generando automaticamente il progetto Xcode e Android Studio per te. Inoltre, i suoi plugin forniscono accesso alle funzionalità di dispositivo nativo come la fotocamera tramite un ponte JS.
Con Capacitor, ottieni un'app mobile nativa fantastica senza alcuna configurazione complessa o curva di apprendimento impegnativa. La sua API sottile e la sua funzionalità ottimizzata rendono facile integrarla nel tuo progetto. Sono sicuro che sarai impressionato dalla facilità con cui puoi ottenere un'app nativa funzionale completa con Capacitor.
Preparazione dell'App React
Mentre ci sono varie modalità per avviare le applicazioni React, scegliamo la più semplice in questo tutorial che fornisce un'applicazione React vuota:
npx create-react-app my-appPer creare un'app mobile nativa, abbiamo bisogno di un export del nostro progetto. Quindi, aggiungiamo uno script semplice nel nostro package.json che possiamo utilizzare per costruire e esportare il progetto React:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Potete eseguire npm run build senza preoccupazioni, e dovreste essere in grado di vedere un nuovo cartella out al root del progetto.
Questo folder verrà utilizzato da Capacitor in un secondo momento, ma per ora dobbiamo configurarlo correttamente.
Aggiungere Capacitor all'App React
Per pacchettizzare qualsiasi app web in un contenitore mobile nativo, dobbiamo seguire alcuni passaggi iniziali, ma dopo di che è semplice come eseguire un singolo sync comando.
Per prima cosa, possiamo installare il Capacitor CLI come dipendenza di sviluppo, e quindi configurarlo nel nostro progetto. Durante la configurazione, puoi premere “invio” per accettare i valori predefiniti per nome e ID bundle.
Successivamente, dobbiamo installare il pacchetto di base e i pacchetti pertinenti per le piattaforme iOS e Android.
Infine, possiamo aggiungere le piattaforme, e Capacitor creerà cartelle per ogni piattaforma nella radice del nostro progetto:
# 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 androidDa questo punto, dovresti essere in grado di osservare nuove ios e android cartelle nella tua progetto React.
Sono progetti nativi reali!
To accedere al progetto Android in seguito, dovrai installare Android Studio. Per iOS, hai bisogno di un Mac e dovresti installare Xcode.
Inoltre, dovresti trovare un 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 webDir, che deve puntare al risultato della tua comando di build. Attualmente, è inesatto.
contexto: frammento di testo HTML da una stringa di Capgo UI più lunga (chiave genitoriale `solutions_cordova_to_capacitor_ai_step2_body`). Pagina/area: Pagina di marketing delle soluzioni di Capgo. Ruolo: Copia del sito web. Visto in: pagine solutions/cordova-to-capacitor-ai.astro. Chiave di messaggio `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body). capacitor.config.json file e aggiorna il webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Puoi provare eseguendo i seguenti comandi:
npm run build
npx cap syncIl primo comando npm run build costruirà il tuo progetto React e esporterà la build statica.
Mentre il secondo comando npx cap sync Sincronizzerà tutte le web code nei posti giusti delle piattaforme native affinché possano essere visualizzate nell'app.
Inoltre, il comando di sincronizzazione potrebbe aggiornare le piattaforme native e installare plugin, quindi quando installi un nuovo Capacitor plugin è ora di eseguirlo npx cap sync di nuovo.
Ora, senza accorgersi, si è completato il processo, quindi vediamo l'applicazione su un dispositivo!
Costruisci e distribuisci app native
To sviluppare app iOS, hai bisogno di avere Xcode installato, e per le app Android, hai bisogno di avere Android Studio installato. Inoltre, se pianifichi di distribuire la tua app sul negozio di app, hai bisogno di iscriverti al Apple Developer Program per iOS e al Google Play Console per Android.
Se sei nuovo alla sviluppo mobile nativo, puoi utilizzare il Capacitor CLI per aprire facilmente entrambi i progetti nativi:
npx cap open ios
npx cap open androidUna volta impostati i tuoi progetti nativi, distribuire la tua app su un dispositivo connesso è facile. In Android Studio, basta aspettare che tutto sia pronto, e puoi distribuire la tua app su un dispositivo connesso senza modificare alcun impostazione. Ecco un esempio:
In Xcode, hai bisogno di impostare il tuo account di firma per distribuire la tua app su un dispositivo reale invece che solo sul simulatore. Se non hai fatto questo prima, Xcode ti guida attraverso il processo (ma di nuovo, hai bisogno di essere iscritto al Programma di sviluppo). Dopo di che, puoi semplicemente premere play per eseguire l'app sul tuo dispositivo connesso, che puoi selezionare in alto. Ecco un esempio:
Congratulazioni! Hai distribuito con successo la tua app web React su un dispositivo mobile. Ecco un esempio:
Ma aspetta, ci sono anche metodi più veloci per farlo durante lo sviluppo…
Capacitor Ricostruzione in tempo reale
Da adesso, sei probabilmente abituato a avere il live reload con tutti i framework moderni, e la buona notizia è che puoi avere la stessa funzionalità su un dispositivo mobile con sforzo minimo!
Abilita l'accesso alla tua applicazione ospitata localmente con live reload su il tuo network avendo l'app Capacitor caricare il contenuto dalla specifica URL.
La prima cosa da fare è capire il tuo indirizzo IP locale. Se stai utilizzando un Mac, puoi scoprire questo eseguendo il seguente comando nel terminale:
ipconfig getifaddr en0Su Windows, esegui :
ipconfigPoi cerca l'indirizzo IPv4.
Potremmo istruire Capacitor a caricare l'app direttamente dal server aggiungendo un'altra voce ai nostri 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;Assicurati di utilizzare l'indirizzo IP e il porto corretti, ho utilizzato il porto predefinito di React in questo esempio.
Ora possiamo applicare queste modifiche copiandole nel nostro progetto nativo:
npx cap copyLa copy questa istruzione è simile a sync, ma copierà solo le modifiche apportate al folder web e alla configurazione, senza aggiornare il progetto nativo. copia le modifiche apportate alla cartella web and configuration, without updating the native project.
Ora puoi distribuire nuovamente la tua app tramite Android Studio o Xcode. Dopo di che, se modifichi qualcosa nella tua app React, L'applicazione si ricaricherà automaticamente e mostrare le modifiche!
Tenere a mente se infatti installi nuovi plugin come la fotocamera, è comunque necessario ricostruire il progetto nativo. Ciò è dovuto al fatto che i file nativi sono stati modificati, e ciò non può essere fatto in tempo reale.
Nota che dovresti utilizzare l'IP e il port corretti nella tua configurazione. Il blocco code sopra mostra il porto React di default per scopi dimostrativi.
Utilizzo dei Capacitor Plugins
Vediamo come utilizzare un Capacitor plugin in azione, di cui abbiamo parlato prima. Per farlo, possiamo installare un plugin abbastanza semplice eseguendo:
npm i @capacitor/shareNon c'è nulla di particolarmente complesso nel plugin di condivisionema comunque apre il dialogo di condivisione nativo! Per questo, adesso dobbiamo solo importare il pacchetto e chiamare la share() funzione dal nostro app. Modifichiamo il src/App.js a questo:
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;As menzionato in precedenza, quando si installano nuovi plugin, è necessario eseguire un'operazione di sincronizzazione e poi ri-deployare l'app sul dispositivo. Per farlo, esegui il seguente comando:
npx cap syncDopo aver premuto il pulsante, puoi assistere alla bella finestra di condivisione nativa in azione!
Successivamente, puoi rendere l'app più nativa su iOS e Android con Capgo di navigazione e transizioni, e risolvere i problemi di layout comuni di iOS che causano un sovraccarico orizzontale o aree sicure tagliate.
Interfaccia utente con un aspetto nativo con Capgo Navigazione e transizioni native
L'ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarlo con React è un processo complicato e raramente vale la pena quando già si dispone di Tailwind CSS.
Per un aspetto mobile nativo in un'app React + Capacitor, utilizza i plugin Capgo al posto delle kit di interfaccia utente web-only come Konsta UI:
- @capgo/capacitor-navigazione-nativa — barra di navigazione nativa, Liquid Glass barra dei tab su iOS e uno stile di barra dei tab sfocato su Android. Il router React mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
- @capgo/capacitor-transizioni Transizioni di pagina stile Ionic e swipe indietro su iOS nel layer WebView, senza adottare l'interfaccia utente di Ionic.
Installate sia:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con modalità CSS inset affinché il contenuto web rispetti le barre native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Rendere una barra di tab di vetro liquido (iOS utilizza la rendering di sistema; Android utilizza un sfondo di WebView sfocato):
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}`);
});Aggiungere le transizioni di pagina native nel contenitore dell'app:
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>;
}Avvolgere le pagine di destinazione in cap-router-outlet, cap-page, e cap-content, e chiamare setDirection('forward') o setDirection('back') Prima di navigare. Non duplicare intestazioni o piè di pagina web quando la navigazione nativa gestisce questi elementi.
Vedi le guide complete: Utilizzando @capgo/capacitor-navigazione nativa e Utilizzando @capgo/capacitor-transizioni.
Aree sicure con Tailwind
Per le aree sicure del dispositivo in Tailwind CSS, utilizzare @capgo/tailwind-capacitor (pubblicato su tailwind-capacitor su di npm). Fornisce safe-areas utilità e altri plugin Tailwind compatibili con Capacitor.
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Usa strumenti come pt-safe, pb-safe, and px-safe al posto di diffondere env(safe-area-inset-*) manualmente. Il progetto è attivamente sviluppato — se qualcosa manca per la tua impostazione React, apri un PR su GitHub.
Risolvere Problemi di Layout iOS (Viewport, Area di Sicurezza e Flusso Orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o regolare il tag viewport da solo non risolve di solito il problema. Esegui questi controlli in ordine.
Assicurati che il tag meta viewport sia applicato correttamente
Aggiungi il tag meta viewport in index.html all'interno <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gestisci l'area di sicurezza di iOS da un solo wrapper radice
Creare un unico contenitore dell'applicazione e applicare il padding dell'area di sicurezza lì — non in componenti nidificati multipli:
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);
}Avvolgi tutto il contenuto della pagina all'interno .app-shell. Aggiungi spaziatura di area sicura in intestazioni, modali e wrapper di layout spesso fa sì che l'interfaccia utente sembri tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi esprimere la stessa spaziatura con utilità come pt-safe pb-safe px-safe su quella singola shell.
Imposta Capacitor iOS contentInset su never primo
In capacitor.config.ts, preferisci l'inserzione nativa disabilitata e lascia che CSS (o Native Navigation’s contentInsetMode: 'css') gestisca l'area sicura:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Miscela Capacitor's automatico contenuto insetto con CSS env(safe-area-inset-*) La spaziatura è una causa comune di doppia spaziatura.
Trova l'elemento sovrapposto reale
L'elemento colpevole è spesso un elemento che utilizza 100vw, Tailwind w-screenuna larga dimensione fisso in pixel, o una grande min-width.
In Safari Web Inspector, esegui:
[...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,
}));Con Tailwind, sostituisci w-screen con w-full quando possibile. Molti problemi di sovrascrittura orizzontale derivano da 100vw / w-screen, padding di area sicura duplicato, o un contenitore a larghezza fissata — non dal tag meta viewport stesso.
Conclusioni
Capacitor è un'ottima scelta per creare applicazioni native basate su un progetto web esistente, offrendo un modo semplice per condividere code e mantenere un'interfaccia utente coerente.
And con l'aggiunta di CapgoE' ancora più facile aggiungere aggiornamenti in tempo reale all'applicazione, assicurando che gli utenti abbiano sempre accesso alle ultime funzionalità e correzioni di bug.
Se desiderate imparare a aggiungere Capgo all'applicazione React, guardate l'articolo successivo:
Continuate da Building Mobile Apps con React e Capacitor
Se utilizzate Building Mobile Apps con React e Capacitor per pianificare l'automazione CI/CD, connettetelo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD Capgo Build Nativi per il flusso di lavoro del prodotto in Capgo Build Nativi Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e GitHub Azioni Integrazione per i dettagli di implementazione in GitHub Azioni Integrazione.
