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 nativo con Capgo Navigazione e Transizioni nativi.
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.
Capacitor Overview
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à di dispositivo nativo come la fotocamera tramite un ponte JS.
Capacitor offre una via diretta per creare un'applicazione mobile nativa senza alcun problema o curva di apprendimento impegnativa. La sua semplice API e la sua funzionalità streamlinata rendono facile l'integrazione nel tuo progetto.
Configurazione dell'App React.js
Vediamo il metodo più semplice per avviare un'applicazione React. Utilizzeremo il gestore di pacchetti npm per creare una nuova app React:
npx create-react-app my-appTrasformare il nostro progetto in un'app mobile nativa, esportazione La creazione di un'app mobile richiede.
Ritorneremo a questo momento. In primo luogo, cerchiamo 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 nostra radice del 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 android le directory 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 installare Xcode.
Successivamente, aggiorna il webDir 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 syncIl npm run build comando costruirà il tuo progetto React.js, mentre npx cap sync allagherà l'applicazione web code nei posti precisi delle piattaforme native, in modo che possa essere eseguita all'interno dell'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 Xcode, e le app Android hanno bisogno di Studio AndroidSe hai l'intenzione di distribuire il tuo'applicazione sul negozio dell'app, devi iscriverti al programma di sviluppo Apple 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 impostati i progetti nativi, il processo di distribuzione dell'applicazione su un dispositivo connesso è un processo lineare.
Per Android Studio, attendi che tutto si carichi e poi distribuisci l'applicazione su un dispositivo connesso.
Per Xcode, stabilisci il tuo account di firma per distribuire l'applicazione su un dispositivo reale invece che solo sul simulatore. Dopo aver fatto ciò, basta cliccare su 'Esegui' per eseguire l'applicazione sul tuo dispositivo connesso, che puoi scegliere in alto.
Se tutto è andato bene, avrai convertito la tua applicazione web React.js in un'applicazione mobile nativa!
Capacitor Live Reload
Il framework di sviluppo moderno solitamente viene fornito con il rilascio caldo, e fortunatamente, puoi avere lo stesso con Capacitor ma su il tuo dispositivo mobile!
Puoi rendere la tua applicazione ospitata localmente accessibile con il rilascio live sul tuo rete da avere l'app Capacitor caricare il contenuto da una specifica URL.
Determina l'indirizzo IP locale. Su un Mac, puoi farlo eseguendo ipconfig getifaddr en0 Inserisci il comando nel terminale. Su Windows, 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 un'altra volta tramite Android Studio o Xcode, qualsiasi modifica nell'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
Usiamo un plugin Capacitor per vedere come funziona. Installiamo uno semplice, il plugin di condivisione, che sollecita il dialogo di condivisione nativo:
npm i @capacitor/shareTo utilizzarlo, importa il pacchetto e chiama la rispettiva share() funzione dalla nostra 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 nativa con Capgo Navigazione e Transizioni 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à disponi 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 come Konsta UI:
- @capgo/capacitor-navigazione nativa --- barra di navigazione nativa, Liquid Glass tab bar su iOS e uno stile di barra di tab con sfondo sfocato su Android. Il tuo router React mantiene lo stato delle rotte; il plugin possiede 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 il CSS inset mode 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',
},
});Visualizza una barra dei pulsanti Liquido Glass (iOS utilizza la rendering di 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}`);
});Aggiungi transizioni di pagina native nel tuo shell 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>;
}Avvolgi le pagine di destinazione in cap-router-outlet, cap-pagee cap-contente chiama setDirection('forward') o setDirection('back') Prima di navigare. Non ripetere i titoli o i piedi di pagina web se la navigazione nativa gestisce questi elementi.
Vedi le guide complete: Usa @capgo/capacitor-navigazione nativa e Usa @capgo/capacitor-transizioni.
Zone sicure con Tailwind
Per le aree sicure del dispositivo in Tailwind CSS, usa @capgo/tailwind-capacitor pubblicato su tailwind-capacitor su 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 utilità come pt-safe, pb-safe, e px-safe al posto di aggiungere env(safe-area-inset-*) tramite la mano. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione React, apri una PR su GitHub.
Risolvere Problemi di Layout iOS (Viewport, Area di Sicurezza e Sovrapposizione Orizzontale)
Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o regolare la tag di viewport da solo non risolve di solito il problema. Esegui questi controlli in ordine.
Assicurati che la tag meta viewport sia applicata correttamente
Aggiungi la 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'app 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);
}Avvolgere tutto il contenuto della pagina all'interno .app-shellIl sovrapposizione di padding di area sicura nei capisaldi, nei modali e nei wrapper di layout può rendere l'interfaccia utente appiattita o troppo grande.
Con @capgo/tailwind-capacitor, puoi esprimere lo stesso spazio di padding con utilità come pt-safe pb-safe px-safe su quel singolo shell.
Imposta Capacitor iOS contentInset su never first
primo capacitor.config.tspreferare l'inserzione nativa disabilitata e lasciare che CSS (o la navigazione nativa) contentInsetMode: 'css'Possiedi l'area di sicurezza
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mischia Capacitor’s automatico contenuto di insetto con CSS env(safe-area-inset-*) l'aggiunta di padding è una causa comune di doppia spaziatura.
Trova l'elemento che si estende effettivamente
L'elemento colpevole è spesso un elemento che utilizza 100vw, Tailwind w-screen, un'ampiezza di pixel fissata, 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 sovraccarico orizzontale derivano da 100vw / w-screen, duplicato padding di area sicura, o un contenitore di ampiezza fissata — non dal tag meta viewport stesso.
Conclusioni
Capacitor offre una via semplice 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 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 poter velocizzare il processo di sviluppo del tuo'app. iscrivi un account gratuito oggi.
Continua a lavorare da Building Mobile Apps con React.js e Capacitor
Se stai utilizzando Building Mobile Apps con React.js e Capacitor per pianificare il comportamento di media e interfaccia nativa, collega Usando @capgo/capacitor-live-activities per la capacità nativa in Usando @capgo/capacitor-live-activities, @capgo/capacitor-attività-in-vivo per il dettaglio di implementazione in @capgo/capacitor-live-attivitàs Utilizzando @capgo/capacitor-player-video per la capacità nativa in Utilizzando @capgo/capacitor-player-video @capgo/capacitor-player-video per il dettaglio di implementazione in @capgo/capacitor-player-video, e Utilizzando @capgo/capacitor-navigazione-nativa per la capacità nativa in Utilizzando @capgo/capacitor-navigazione-nativa.
