Questa guida ti guiderà nella creazione di un'applicazione mobile utilizzando React e Capacitor. Alla fine, saprai come trasformare un'applicazione web React.js in un'applicazione mobile nativa con Capacitor, e aggiungere un tocco di realtà con Capgo Navigazione Nativa e Transizioni.
Capacitor consente la trasformazione facile della tua app web React.js in un'applicazione mobile nativa, richiedendo nessuna sostanziali alterazioni o strategie di apprendimento come React Native.
Il processo coinvolge pochi passaggi semplici, e prima di sapere, 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 in modo trasparente con qualsiasi progetto web e avvolgere il tuo app in una vista web nativa mentre genera i progetti Xcode e Android Studio nativi. Inoltre, attraverso i suoi plugin, puoi accedere alle funzionalità di dispositivo nativo come la fotocamera tramite un ponte JS.
Capacitor offre una via di mezzo per creare 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
Vediamo il metodo più semplice per avviare un'applicazione React. Utilizzeremo il package manager npm per creare una nuova app React:
npx create-react-app my-appPer trasformare il nostro progetto in un'applicazione mobile nativa, è necessario un esportazione del nostro app.
Ritorneremo a questo momento. Prima, cercheremo di capire come integrare Capacitor nella nostra app React.
Integrazione di Capacitor nell'App React.js
I primi passaggi di configurazione potrebbero essere un po' dettagliati, ma dopo di che, l'aggiornamento del wrapper dell'app nativa diventa semplice come eseguire un sync comando.
Prima, 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 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 androidLa iOS e cartelle sono ora presenti nel tuo progetto React.js. Per accedere al progetto Android in seguito, installa
Android Studio . Per iOS, hai bisogno di un Mac e dovresti installareXcode Aggiornare il.
e directory web in your capacitor.config.json file come mostrato di seguito:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Eseguire il comando di build e sincronizzare il tuo progetto con Capacitor:
npm run build
npx cap syncLa npm run build comanderà la costruzione del tuo progetto React.js, mentre npx cap sync allineerà il web code nei posti precisi delle piattaforme native affinché possano essere eseguiti in un'app.
Ora, con un po' di fortuna e nessun errore, il tuo app React.js dovrebbe essere pronto per essere lanciato su un dispositivo!
Costruire e Distribuire le Tue App Native
Sviluppare app iOS richiede Xcodee Android app devono Android Studio. Se hai l'intenzione di distribuire il tuo 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 aprire entrambi i progetti nativi:
npx cap open ios
npx cap open androidDopo aver configurato i tuoi progetti nativi, distribuire il tuo app su un dispositivo connesso è un processo lineare.
Per Android Studio, attendi che tutto si carichi e poi distribuisci il tuo app su un dispositivo connesso.
Per Xcode, stabilisci il tuo account di firma per distribuire il tuo app su un dispositivo reale invece che solo sul simulatore. Dopo aver fatto questo, basta cliccare su 'Esegui' per eseguire l'app sul tuo dispositivo connesso, 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 viene fornito con il rilancio caldo, e fortunatamente, puoi avere lo stesso con Capacitor ma sul tuo dispositivo mobile!
Puoi rendere il tuo'applicazione ospitata localmente accessibile con il rilancio live sul tuo rete di rete avendo l'app Capacitor caricare il contenuto da una specifica URL.
Determina il tuo indirizzo IP locale. Su Mac, puoi farlo eseguendo ipconfig getifaddr en0 Esegui ipconfig Esegui e cerca l'indirizzo IPv4.
Dopo di che, 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 port corretti. Esegui npx cap copy per applicare queste modifiche al nostro progetto nativo.
Una volta distribuita la tua app una volta di più tramite Android Studio o Xcode, qualsiasi modifica all'app React verrà automaticamente ricaricata e visualizzata sulla tua app!
Tieni presente che se vengono installati nuovi plugin, come la fotocamera, è necessario ricostruire il tuo progetto nativo. Ciò è dovuto al fatto che i file nativi sono stati modificati e non possono essere aggiornati in tempo reale.
Utilizzo dei Capacitor Plugins
Ecco un esempio di come utilizzare un plugin Capacitor. Installiamo un plugin semplice, il Plugin di condivisioneche attiva il dialogo di condivisione nativa:
npm i @capacitor/sharePer utilizzarlo, importa il pacchetto e chiama la rispettiva share() funzione dal nostro'app. Considera il 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 l'installazione di 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 la navigazione e le transizioni Capgo 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 la navigazione e le transizioni Capgo native
L'ho utilizzato per anni con Ionic per costruire applicazioni cross-platform, ma integrarlo 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 delle kit di interfaccia utente web come Konsta UI:
- @capgo/capacitor-navigazione nativa — barra di navigazione nativa, Liquid Glass tab bar su iOS e una barra di tab con sfondo sfocato su Android. Il tuo router React mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
- @capgo/capacitor-transizioni — transizioni di pagina dello stile Ionic e swipe-back di iOS nell' layer WebView, senza adottare l'interfaccia UI di Ionic.
Installate sia:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigura la navigazione nativa con il modo di inserimento CSS 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',
},
});Rendi una barra di tab di vetro liquido (iOS utilizza la rendering di sistema; Android 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 della tua 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>;
}Avvolgi le pagine di destinazione in cap-router-outlet, cap-pagee cap-contente chiama setDirection('forward') o setDirection('back') prima di navigare. Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa possiede queste superfici.
Vedi le guide complete: Utilizzare @capgo/capacitor-navigazione nativa e Utilizzare @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 di 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, e px-safe al posto 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 su iOS (Viewport, Area di sicurezza, e sovrapposizione orizzontale)
Se il contenuto sembra essere tagliato, spostato o scrollabile orizzontalmente su iOS, aggiungere più overflow-x: hidden o modificare solo il tag viewport non risolve il problema. Esegui questi controlli in ordine.
Assicurati di aver applicato correttamente il tag meta viewport
Aggiungi il tag meta viewport in index.html all'interno di <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 per l'app e applicare il padding di 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);
}Avvolgere tutto il contenuto della pagina dentro .app-shell. Il padding di area duplicato nei titoli, nei modali e nei contenitori di layout spesso fa sembrare l'interfaccia utente tagliata o troppo grande.
Con @capgo/tailwind-capacitor, puoi esprimere lo stesso padding con utilità come pt-safe pb-safe px-safe su quel singolo contenitore.
Impostare Capacitor iOS contentInset su never context: Pagina/area: Pagina di aggiornamenti in tempo reale. Ruolo: Etichetta di navigazione breve o elemento di navigazione. Chiave di messaggio `live_update_dynamic_label_to` (Live Update Dynamic Label To).
primo capacitor.config.tsIn contentInsetMode: 'css'Possiedere l'area di sicurezza:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Miscelare l'inserimento automatico di contenuto di Capacitor con CSS env(safe-area-inset-*) Aggiungere padding è una causa comune di doppia spaziatura.
Trova l'elemento che sta effettivamente sovrascrivendo
Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screen, un'altezza di pixel fissata, o un contenitore molto 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 di sicurezza duplicato, o un contenitore a larghezza fissata — non dal tag meta viewport stesso.
Conclusione
Capacitor offre una via semplice per costruire applicazioni native basate su un progetto web esistente, fornendo un modo semplice per condividere code e avere un'interfaccia utente coerente.
Grazie a tecnologie come Capacitor, costruire applicazioni mobili a partire da applicazioni 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 dell'applicazione iscrivi il tuo account gratuito oggi.
Continua da Costruire Applicazioni Mobili con React.js e Capacitor
Se stai utilizzando Costruire Applicazioni Mobili con React.js e Capacitor per pianificare il comportamento di media e interfaccia nativa, connettilo con Utilizzare @capgo/capacitor-live-attività per la capacità nativa in Utilizzare @capgo/capacitor-live-attività, @capgo/capacitor-attività in diretta per i dettagli di implementazione in @capgo/capacitor-attività in diretta, Utilizzo di @capgo/capacitor-lettore di video per la capacità nativa in Utilizzo di @capgo/capacitor-lettore di video, @capgo/capacitor-lettore di video per i dettagli di implementazione in @capgo/capacitor-lettore di video, e Utilizzo di @capgo/capacitor-navigazione nativa per la capacità nativa in Utilizzo di @capgo/capacitor-navigazione nativa.
