Creare App Mobili con React.js e Capacitor

Questa guida vi guiderà attraverso la creazione di un'applicazione mobile utilizzando React e Capacitor. Alla fine, saprete 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 nativa.

Capacitor consente la trasformazione facile della vostra app web React.js in un'applicazione mobile nativa, richiedendo nessuna sostanziale alterazione o apprendimento di nuove strategie come React Native.

Il processo coinvolge pochi passaggi semplici, e prima che lo si sappia, la vostra app React.js sarà un'applicazione mobile funzionante. Quindi, rimanete con noi mentre vi guideremo in questo viaggio.

Capacitor Overview

CapacitorJS è un vero cambiamento. Può integrarsi facilmente con qualsiasi progetto web e avvolgere la vostra app in una view web nativa mentre genera il progetto Xcode e Android Studio nativo. Inoltre, attraverso i suoi plugin, potete accedere alle funzionalità del dispositivo nativo come la fotocamera tramite un ponte JS.

Capacitor offre un modo diretto 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 progetto.

Configurazione dell'app React.js

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-app

Per trasformare il nostro progetto in un'app mobile nativa, è richiesta l' export del nostro app.

Ritorneremo a questo momento. Prima, capiremo come integrare Capacitor nella nostra app React.

Integrazione di Capacitor nel tuo App React.js

Il primo passaggio di configurazione potrebbe essere un po' dettagliato, ma dopo di esso, l'aggiornamento del wrapper di app nativa diventa semplice come eseguire un sync comando.

Prima di tutto, installeremo il Capacitor CLI come dipendenza di sviluppo e lo configureremo all'interno del 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 android

Le directory iOS e context":"Page/area: Capgo marketing website. Role: Short UI label or navigation item. Seen in: page trust.astro. Message key `and` (And)."

directory Android sono ora presenti nel tuo progetto React.js. Per accedere al progetto Android in seguito, installa Studio Android. Per iOS, hai bisogno di un Mac e dovresti installare Xcode.

Successivamente, aggiorna il webDir config.json capacitor.config.json Run the build command and sync your project with

{
  "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 sync

comanderà di costruire il tuo progetto React.js, mentre npm run build allineerà il web in i posti precisi delle piattaforme native affinché possano essere eseguiti in un'app. npx cap sync will align the web code in the accurate places of the native platforms so they can be executed in an app.

Ora, 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

Lo sviluppo di app iOS richiede Xcode, e le app Android necessitano di Android Studio. Se hai in programma di distribuire la tua app sul negozio di app, devi iscriverti al programma di sviluppatore Apple per iOS e al Google Play Console per Android.

Il Capacitor CLI semplifica il processo di apertura di entrambi i progetti nativi:

npx cap open ios
npx cap open android

Una volta impostati i progetti nativi, il processo di distribuzione dell'app su un dispositivo connesso è facile.

Per Android Studio, attendi che tutto si carichi e poi distribuisci l'app su un dispositivo connesso.

Per Xcode, stabilisci il tuo account di firma per distribuire l'app su un dispositivo reale invece che solo sul simulatore. Dopo aver fatto questo, basta cliccare su 'play' 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 include il live reload, e fortunatamente, puoi avere lo stesso con Capacitor ma su il tuo dispositivo mobile!

Puoi rendere il tuo'applicazione ospitata localmente accessibile con live reload nel tuo 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 port corretti. Esegui npx cap copy per applicare questi cambiamenti al nostro progetto nativo.

Una volta che hai distribuito nuovamente l'app tramite Android Studio o Xcode, qualsiasi modifica all'app React verrà automaticamente ricaricata e visualizzata sull'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.

Utilizzare plugin Capacitor

Vediamo velocemente come utilizzare un plugin Capacitor. Installiamo un plugin semplice, il Plugin di condivisione, che sollecita il dialogo di condivisione nativo:

npm i @capacitor/share

Per 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 su iOS che causano un sovraccarico orizzontale o aree sicure tagliate.

Interfaccia utente nativa con navigazione e transizioni Capgo

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 invece 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 il chrome nativo.
• @capgo/capacitor-transitions — transizioni di pagina dello stile Ionic e swipe indietro su iOS nell' layer WebView, senza adottare l'interfaccia UI di Ionic.

Installare entrambi:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Configura la navigazione nativa con modalità CSS inset per far rispettare le 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 possiede quelle 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, 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-capacitor

In 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 di sicurezza di iOS da un wrapper radice solo

Crea un unico contenitore dell'applicazione e applica 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 tutta il contenuto della pagina all'interno .app-shelldi. Il padding dell'area di sicurezza duplicato 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 Inizia never primo

Sul capacitor.config.ts, preferisci l'ingombro 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: 'build',
  ios: {
    contentInset: 'never',
  },
};

Mescolare l'ingombro automatico di contenuto di Capacitor con CSS env(safe-area-inset-*) è una causa comune di doppia spaziatura.

Cerca l'elemento che sta effettivamente sovrapprendendo

L'elemento colpevole è spesso un elemento che utilizza 100vw, Tailwind w-screen, una larghezza in pixel fissata, o un grande min-width.

Sul 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 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 sulla base di 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 da progetti web React.js è mai stato più facile. Porta le tue competenze di sviluppo web al livello successivo creando applicazioni mobili native impressionanti. Buon codice!

Per saperne di più 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 nativi e connetterli 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