In questo tutorial, inizieremo con una nuova React app e passeremo alla sviluppo mobile nativo utilizzando Capacitor. Puoi anche aggiungere Capgo di navigazione e transizioni nativa per un'esperienza mobile nativa, e utilizzare tailwind-capacitor per aree sicure.
Capacitor ti 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 può essere trasformata in app mobili.
Questo tutorial ti guiderà attraverso il processo, iniziando con una nuova app React e poi incorporando Capacitor per passare nel mondo degli app mobili native. Puoi anche utilizzare Capgo di navigazione, transizioni e tailwind-capacitor per aree sicure.
Su Capacitor
CapacitorJS è un vero cambiamento! Puoi incorporarlo facilmente in qualsiasi progetto web, e lo renderà avvolto in una view web nativa, generando il progetto Xcode e Android Studio nativo per te. Inoltre, i suoi plugin ti danno accesso alle funzionalità del dispositivo nativo come la fotocamera tramite un ponte JS.
Con Capacitor, ottieni una fantastica app mobile nativa senza alcun setup complesso o curva di apprendimento ripida. La sua API sottile e la sua funzionalità streamlinata rendono facile da integrare nel tuo progetto. Sono sicuro che sarai ammirato dalla facilità con cui puoi ottenere un'app mobile nativa completa con Capacitor!
Preparazione della tua app React
Mentre ci sono varie metodi per avviare le applicazioni React, andiamo per il 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"
}
}Puoi eseguire npm run build senza preoccupazioni, e dovresti riuscire a vedere un cartella fresca all'interno della root del tuo progetto.
Questa cartella verrà utilizzata da Capacitor in seguito, ma per ora dobbiamo configurarla correttamente.
Aggiungere Capacitor alla tua App React
Per pacchettare qualsiasi app web in un contenitore mobile nativo, dobbiamo seguire alcuni passaggi iniziali, ma dopo di che è semplice come eseguire un solo sync command.
In primo luogo, possiamo installare il Capacitor CLI come dipendenza di sviluppo, e quindi configurarlo all'interno del 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 androidIn questo punto, dovresti essere in grado di osservare nuove ios e android cartelle nel tuo progetto React.
Sono progetti nativi reali!
Per accedere al progetto Android in seguito, è necessario installare targetLanguageItalian protectedTokens.
Cloudflare 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 Capgocode
API capacitor.config.json CLI npm","bun","texts","Android Studio","Per iOS, hai bisogno di un Mac e dovresti installare","Xcode","Inoltre, dovresti trovare un file","__CAPGO_KEEP_0__.config.ts","che contiene alcune impostazioni fondamentali __CAPGO_KEEP_0__ utilizzate durante la sincronizzazione. L'unica cosa a cui dovresti prestare attenzione è il","webDir",", che deve puntare al risultato del tuo comando di build. Attualmente, è inesatto.""Per correggere questo, apri il","__CAPGO_KEEP_0__.config.json","file e aggiorna il","webDir"]}:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Esegui i seguenti comandi per provare:
npm run build
npx cap syncLa prima riga di comando npm run build costruirà semplicemente il tuo progetto React e esporterà la costruzione statica.
Mentre il secondo comando npx cap sync syncronizzerà tutte le web code nei posti giusti delle piattaforme native affinché possano essere visualizzate in un'app.
Inoltre, il comando di sincronizzazione potrebbe aggiornare le piattaforme native e installare plugin, quindi quando installi un nuovo Capacitor plugin è il momento di eseguire npx cap sync nuovamente.
Senza accorgersene, sei ora effettivamente pronto, quindi vediamo l'app sul dispositivo!
Sviluppa e distribuisce app native
Per sviluppare app iOS, hai bisogno di avere Xcode installato e per le app Android, è necessario avere Android Studio installato. Inoltre, se pianifichi di distribuire la tua app sul negozio di app, è necessario iscriversi al Apple Developer Program per iOS e al Google Play Console per Android.
Se sei nuovo alla creazione di app mobili native, puoi utilizzare il Capacitor CLI per aprire facilmente entrambi i progetti nativi:
npx cap open ios
npx cap open androidUna volta impostati i progetti nativi, il deployment dell'app su un dispositivo connesso è facile. In Android Studio, basta attendere che tutto sia pronto, e puoi deployare l'app su un dispositivo connesso senza modificare alcun impostazione. Ecco un esempio:
In Xcode, è necessario configurare il tuo account di firma per deployare l'app su un dispositivo reale al posto del simulatore. Se non hai fatto ciò prima, Xcode ti guida attraverso il processo (ma di nuovo, è necessario essere iscritti al Programma per sviluppatori). Dopo di che, puoi semplicemente premere play per eseguire l'app sul dispositivo connesso, che puoi selezionare in alto. Ecco un esempio:
Congratulazioni! Hai con successo deployato la tua app web React su un dispositivo mobile. Ecco un esempio:
Ma aspetta, c'è anche un modo più veloce di fare ciò durante lo sviluppo…
Capacitor Live Reload
Ora probabilmente sei 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 sul tuo network avendo l'app Capacitor caricare il contenuto dalla specifica URL.
Il primo passo è capire l'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.
Possiamo istruire Capacitor a caricare l'app direttamente dal server aggiungendo un'altra voce al nostro 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 la porta corretti, ho utilizzato la porta predefinita di React in questo esempio.
Ora, possiamo applicare queste modifiche copiandole nel nostro progetto nativo:
npx cap copyIl copy comando è simile a sync, ma copierà solo le modifiche apportate al folder web e la configurazione, senza aggiornare il progetto nativo.
Puoi ora distribuire nuovamente il tuo app tramite Android Studio o Xcode. Dopo di che, se cambi qualcosa nel tuo app React, l'app si ricaricherà automaticamente e mostrerà le modifiche!
Tenete presente che se installate nuovi plugin come la camera, è comunque necessario un rebuild del vostro progetto nativo. Ciò è dovuto al fatto che i file nativi sono stati modificati e non è possibile farlo in modo dinamico.
Nota che dovete utilizzare l'indirizzo IP e il port corretti nella vostra configurazione. Il blocco code sopra mostra il porto predefinito React per scopi dimostrativi.
Utilizzo dei Capacitor Plugins
Ecco un esempio di come utilizzare un Capacitor plugin in azione, di cui abbiamo parlato in precedenza. Per farlo, possiamo installare un plugin abbastanza semplice eseguendo:
npm i @capacitor/shareNon c'è nulla di particolarmente complesso nel plugin di condivisione, ma 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 in questo modo:
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;Come abbiamo menzionato in precedenza, quando installate nuovi plugin, è necessario eseguire un'operazione di sincronizzazione e poi ri-deployare l'app sul nostro dispositivo. Per farlo, eseguite il seguente comando:
npx cap syncAfter premere il pulsante, potrai assistere alla splendida finestra di condivisione nativa in azione!
Successivamente, puoi rendere l'app più nativa su iOS e Android con la Capgo navigazione e le transizioni, e risolvere i problemi di layout comuni di iOS che causano overflow orizzontale o aree sicure tagliate.
Interfaccia utente con un aspetto nativo con Capgo Navigazione e Transizioni native
Lavoro da anni con Ionic per costruire applicazioni cross-platform, ma integrarla con React è un processo complicato e raramente vale la pena quando già hai Tailwind CSS.
Per un aspetto mobile nativo in un'app React + Capacitor utilizza i plugin Capgo al posto di kit UI web come Konsta UI:
- @capgo/capacitor-native-navigation – barra di navigazione nativa, Liquid Glass barra dei tab su iOS, e uno stile di barra dei tab sfocato su Android. Il tuo router React mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
- @capgo/capacitor-transitions — Passaggi di transizione dello stile Ionic e swipe indietro di iOS nell' layer WebView, senza adottare l'interfaccia utente di Ionic.
Installare sia:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigurare la navigazione nativa con il modello CSS inset per far rispettare il contenuto web le barre native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Visualizzare una barra dei tab di vetro liquido (iOS utilizza la rendering di proprietà del sistema; Android utilizza un sfondo 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 routing in cap-router-outlet, cap-page, e cap-content, e chiamare setDirection('forward') o setDirection('back') prima di navigare. Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa possiede quelle superfici.
Vedi le guide complete: Utilizzare @capgo/capacitor-navigazione-nativa e Usando @capgo/capacitor-transizioni.
Aree sicure con Tailwind
Per aree sicure del dispositivo in Tailwind CSS, utilizza @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Fornisce safe-areas utilità e altri plugin Tailwind amichevoli con Capacitor:
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Usa utilità come pt-safe, pb-safe, e px-safe invece di spargere env(safe-area-inset-*) con le proprie mani. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione React, apri una PR su GitHub.
I Problemi di Layout iOS (Viewport, Area di Sicurezza e Sovraffollamento Orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o modificare solo il tag viewport non risolve 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 unico wrapper radice
Creare un unico contenitore dell'app e applicare la spaziatura di sicurezza dell'area 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 tutta il contenuto della pagina all'interno .app-shellLa spaziatura di sicurezza dell'area duplicata nei titoli, nei modali e nei wrapper di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi esprimere la stessa spaziatura con utility come pt-safe pb-safe px-safe su quella singola shell.
Imposta Capacitor iOS contentInset su never primo
In capacitor.config.ts, preferisci l'inserimento nativo disabilitato e lascia che CSS (o la navigazione nativa ') contentInsetMode: 'css') gestisca l'area sicura:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Il mixaggio di Capacitor’s automatico contenuto insetto con CSS env(safe-area-inset-*) spaziatura è una causa comune di doppia spaziatura.
Trova l'elemento che sta effettivamente sovraffollando
Il solito colpevole è un elemento che utilizza 100vwTailwind w-screenuna larghezza in pixel fisse, o un 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 sovraffollamento orizzontale derivano da 100vw / w-screenduplicati padding di area sicura, o un contenitore di larghezza fissata — non dal tag meta viewport stesso.
Conclusioni
Capacitor è un'ottima scelta per costruire applicazioni native basate su un progetto web esistente, offrendo un modo semplice per condividere code e mantenere un'interfaccia utente coerente.
E con l'aggiunta di CapgoE' ancora più facile aggiungere aggiornamenti in tempo reale all'applicazione, assicurando che i tuoi utenti abbiano sempre accesso alle ultime funzionalità e correzioni di bug.
Se desideri imparare a aggiungere Capgo alla tua app React, consulta l'articolo successivo:
Continua a procedere da Building Mobile Apps con React e Capacitor
Se stai utilizzando Building Mobile Apps con React e Capacitor per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Native Builds per il flusso di lavoro del prodotto in Capgo Native Builds, Capgo Integrations per il flusso di lavoro del prodotto in Capgo Integrations, Integrazione CI/CD per la dettaglio di implementazione in Integrazione CI/CD, e GitHub Azioni di integrazione per la dettaglio di implementazione in GitHub Azioni di integrazione.
