Questa guida ti guiderà nella creazione di un'applicazione mobile utilizzando React e Capacitor. Alla fine, saprai come trasformare un'app web React.js in un'applicazione mobile nativa con Capacitor, e aggiungere un tocco di realismo con Capgo Navigazione e Transizioni nativi.
Capacitor consente una trasformazione facile della tua app web React.js in un'applicazione mobile nativa, richiedendo nessuna sostanziale modifica o apprendimento di nuove strategie come React Native.
Il processo coinvolge pochi passaggi semplici, e prima di rendersene conto, la tua app React.js sarà un'applicazione mobile funzionante. Quindi, rimani con noi mentre ti guideremo in questo viaggio.
Panoramica di Capacitor
CapacitorJS è un vero cambiamento. Può integrarsi facilmente con qualsiasi progetto web e avvolgere la tua app in un view web nativo mentre genera il progetto Xcode e Android Studio nativo. Inoltre, attraverso i suoi plugin, puoi accedere alle funzionalità del dispositivo nativo come la fotocamera tramite un ponte JS.
Capacitor offre una via d'accesso diretta alla creazione di un'applicazione mobile nativa senza alcun problema o curva di apprendimento ripida. La sua semplice API e funzionalità streamlinata rendono facile l'integrazione nel tuo progetto.
Configurazione dell'app React.js
Vediamo il metodo più semplice per avviare un'app React. Utilizzeremo il package manager npm per creare una nuova app React:
npx create-react-app my-appPer trasformare il nostro progetto in un'app mobile nativa, è necessario un export del nostro app.
Ritorneremo a questo momento. Prima, capiamo come integrare Capacitor nella nostra app React.
Integrazione di Capacitor nel tuo App React.js
I passaggi di configurazione iniziali potrebbero essere un po' dettagliati, ma dopo di essi, aggiornare il wrapper di app nativa diventa semplice come eseguire un sync comando.
In primo luogo, installeremo il Capacitor CLI come dipendenza di sviluppo e lo configureremo nel nostro progetto. Durante la configurazione, accetta i valori predefiniti per nome e ID bundle premendo “invio.”
Successivamente, installeremo il pacchetto di base e i pacchetti pertinenti per le piattaforme iOS e Android.
Infine, aggiungeremo le piattaforme e Capacitor creerà cartelle per ogni piattaforma nel nostro progetto root:
# 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 androidLe directory iOS e directory
Android Studio Android. Per iOS, hai bisogno di un Mac e dovresti installare Xcode.
Successivamente, aggiorna il tuo webDir configurazione del file capacitor.config.json in il tuo file
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Run the build command and sync your project with Capacitor:
npm run build
npx cap syncLa npm run build comanderà costruire il tuo progetto React.js, mentre npx cap sync si allinea il web code nei posti precisi delle piattaforme native affinché possano essere eseguiti in un'app.
Now, con un po' di fortuna e nessun errore, il tuo app React.js dovrebbe essere pronta per il lancio su un dispositivo!
Costruire e distribuire le tue app native
Sviluppare app iOS richiede Xcode, e le app Android hanno bisogno di Android Studio. Se hai in programma di distribuire la tua app sul negozio di app, devi iscriverti al Apple Developer Program per iOS e al Google Play Console per Android.
La Capacitor CLI semplifica il processo di apertura di entrambi i progetti nativi:
npx cap open ios
npx cap open androidUna volta che i progetti nativi sono configurati, distribuire l'app sul dispositivo collegato è un processo lineare.
Per Android Studio, attendi che tutto si carichi e poi distribuisci l'app sul dispositivo collegato.
Per Xcode, stabilisci il tuo account di firma per distribuire l'app sul dispositivo reale invece che solo sul simulatore. Dopo aver fatto ciò, basta cliccare su 'Esegui' per eseguire l'app sul tuo dispositivo collegato, che puoi scegliere in alto.
Se tutto è andato bene, avrai convertito la tua app web React.js in un'applicazione mobile nativa!
Capacitor Live Reload
Il framework di sviluppo moderno solitamente include il ricollegamento in tempo reale, e fortunatamente, puoi avere lo stesso con Capacitor ma su il tuo dispositivo mobile!
Puoi rendere il tuo'applicazione ospitata localmente accessibile con il ricollegamento in tempo reale sul tuo rete di rete facendo in modo che l'app Capacitor carichi il contenuto da una specifica URL.
Prima, determina l'indirizzo IP locale. Su Mac, puoi farlo eseguendo ipconfig getifaddr en0 in terminale. Su Windows, esegui ipconfig e cerca l'indirizzo IPv4.
Dopo di ciò, istruisci Capacitor a caricare l'app direttamente dal server aggiungendo un altro parametro al tuo capacitor.config.ts file:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'build',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Assicurati di utilizzare l'indirizzo IP e il porto precisi. Esegui npx cap copy per applicare queste modifiche al nostro progetto nativo.
Una volta che hai distribuito l'app un'altra volta tramite Android Studio o Xcode, qualsiasi modifica all'app React verrà automaticamente ricaricata e visualizzata sul tuo'app!
Tenete presente che se vengono installati nuovi plugin, come ad esempio la camera, è necessario ricostruire il tuo progetto nativo. Ciò è dovuto al fatto che i file nativi saranno stati modificati e non possono essere aggiornati in tempo reale.
Utilizzo dei Capacitor Plugins
Ecco un esempio di come utilizzare un Capacitor plugin. Installiamo un plugin semplice, il plugin di condivisione, che sollecita il dialogo di condivisione nativo:
npm i @capacitor/sharePer utilizzarlo, importa il pacchetto e chiama la rispettiva share() funzione dal nostro app. Considera il file App.js:
import { Share } from '@capacitor/share';
function ShareButton() {
const share = async () => {
await Share.share({
title: 'React App',
text: 'Visit this React App',
url: 'http://localhost:3000',
dialogTitle: 'Share with...'
});
};
return (
<button onClick={share}>
Share
</button>
);
}
export default ShareButton;Dopo aver installato un nuovo plugin, ricorda di sincronizzare nuovamente il tuo progetto React utilizzando npx cap sync.
Successivamente, puoi rendere l'app più nativa su iOS e Android con Capgo navigazione e transizioni, e risolvere i problemi di layout comuni su iOS che causano overflow orizzontale o aree sicure tagliate.
Interfaccia utente nativa con Capgo Navigazione e Transizioni Nativa
Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarlo con React è un po' un trucco e non vale la pena quando già hai Tailwind CSS.
Per un aspetto nativo su 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 bar delle schede su iOS e stile di barra delle schede sfocata su Android. Il tuo router React mantiene lo stato delle rotte; il plugin gestisce la barra di navigazione nativa.
- @capgo/capacitor-transitions — transizioni di pagina dello stile Ionic e swipe indietro su iOS nell' layer WebView, senza adottare l'interfaccia utente di Ionic.
Installate entrambi:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con modalità CSS inset per far rispettare i barre native al contenuto web:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Rendi una barra delle schede di vetro liquido (su iOS si utilizza la rendering di sistema; su Android si utilizza un sfondo sfocato di WebView):
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}`);
});Aggiungi 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 gestisce queste superfici.
Vedi le guide complete: Utilizzare @capgo/capacitor-navigazione-nativa e Utilizzare @capgo/capacitor-transizioni.
Aree sicure con Tailwind
Per le aree sicure del dispositivo in Tailwind CSS, utilizzare @capgo/tailwind-capacitor (pubblicato come) tailwind-capacitor su npm). Fornisce safe-areas strumenti 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";Utilizza strumenti come pt-safe, pb-safe, e px-safe invece di aggiungerli env(safe-area-inset-*) manualmente. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione React, apri un PR su GitHub.
Risolvere problemi di layout iOS (Viewport, Area sicura, e sovrapposizione orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o modificare il tag viewport da solo non risolve di solito il problema. Passa attraverso 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 sicura di iOS da un wrapper radice solo
Crea un unico contenitore dell'applicazione e applica il padding dell'area sicura 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-shelldi. Il duplicato del padding dell'area sicura nei titoli, nei modali e nei wrapper di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande.
Con @capgo/tailwind-capacitorpuoi esprimere lo stesso padding con utilità come pt-safe pb-safe px-safe su quel singolo contenitore.
Imposta Capacitor iOS contentInset a never primo
In capacitor.config.ts, preferisci l'ingombro nativo disabilitato e lascia che CSS (o la navigazione nativa) gestisca l'area sicura: contentInsetMode: 'css'Mettere insieme l'ingombro automatico di contenuto di __CAPGO_KEEP_0__ con CSS
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Trova l'elemento che sta effondando realmente
Il solito colpevole è un elemento che utilizza
, Tailwind 100vw, una larghezza fissa in pixel, o un grande w-screenIn Safari Web Inspector, esegui: min-width.
Inserisci
[...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 sovrapposizione orizzontale derivano da 100vw / w-screenpadding di area sicura duplicato, o da un contenitore di larghezza fissata — non dal tag meta viewport stesso.
Conclusioni
Capacitor offre un mezzo senza soluzione di continuità per costruire applicazioni native basate su un progetto web esistente, fornendo un modo semplice per condividere code e avere una UI coerente.
Grazie a tecnologie come Capacitor, costruire applicazioni mobili da progetti web React.js è mai stato più facile. Porta le tue abilità di sviluppatore web al livello successivo creando applicazioni mobili native impressionanti. Buon codice!
Per ulteriori informazioni su come puoi accelerare il tuo processo di sviluppo di app iscrivi oggi.
Continua da Costruire Applicazioni Mobili con React.puro e Capacitor
Se stai utilizzando Creare Applicazioni Mobili con React.js e Capacitor per pianificare il comportamento dei media e dell'interfaccia nativa, connettilo con Utilizzare @capgo/capacitor-attività-in-vivo per la capacità nativa in Utilizzare @capgo/capacitor-attività-in-vivo, @capgo/capacitor-attività-in-vivo per il dettaglio di implementazione in @capgo/capacitor-attività-in-vivo, Utilizzare @capgo/capacitor-lettore-di-video per la capacità nativa in Utilizzare @capgo/capacitor-lettore-di-video, @capgo/capacitor-lettore-di-video per il dettaglio di implementazione in @capgo/capacitor-lettore-di-video, e Utilizzare @capgo/capacitor-navigazione-nativa per la capacità nativa in Utilizzare @capgo/capacitor-navigazione-nativa.
