Costruire Applicazioni Mobili con React e Capacitor

In questo tutorial, inizieremo con una nuova app React e passeremo alla sviluppo mobile nativo utilizzando __CAPGO_KEEP_0__. Puoi anche aggiungere __CAPGO_KEEP_1__ navigazione e transizioni nativa per un'app mobile nativa, e utilizzare tailwind-__CAPGO_KEEP_2__ per aree sicure. app and transition to native mobile development using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.

Capacitor allows you to easily convert your React web application into a native mobile app without significant modifications or learning a new skill like React Native.

With solo pochi semplici passaggi, la maggior parte delle applicazioni React possono essere trasformate in app mobili.

Questa guida vi guiderà attraverso il processo, iniziando con una nuova app React e poi incorporando Capacitor per entrare nel regno delle app mobili native. Potete anche utilizzare Capgo per la navigazione nativa, le transizioni e tailwind-capacitor per aree sicure.

Sul Capacitor

CapacitorJS è un vero cambiamento! Potete incorporarlo facilmente in qualsiasi progetto web e renderà la vostra applicazione in un webview nativo, generando il progetto Xcode e Android Studio nativo per voi. Inoltre, i suoi plugin forniscono accesso alle funzionalità del dispositivo nativo come la fotocamera tramite un ponte JS.

Con Capacitor, otterrete una fantastica app mobile nativa senza alcuna configurazione complessa o curva di apprendimento ripida. La sua API sottile e la sua funzionalità streamlinata rendono facile da integrare nel vostro progetto. Sono sicuro che vi sorprenderete alla facilità con cui potete ottenere un'app mobile nativa completa con Capacitor!

Preparazione dell'App React

Mentre ci sono vari metodi per avviare le applicazioni React, andiamo per il più semplice in questa guida che fornisce una app React vuota:

npx create-react-app my-app

Per creare un'app mobile nativa, abbiamo bisogno di un export del nostro progetto. Quindi, includiamo 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"
  }
}

Ora puoi eseguire npm run build senza alcun problema, e dovresti essere in grado di notare una cartella fresca all'interno della root del tuo progetto.

Questa cartella verrà utilizzata da Capacitor in un secondo momento, ma per ora dobbiamo configurarla correttamente.

Aggiungere Capacitor al tuo App React

Per pacchettizzare qualsiasi app web in un contenitore mobile nativo, dobbiamo seguire alcuni passaggi iniziali, ma in seguito è semplice come eseguire un solo sync comando.

Innanzitutto, 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 root 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

Al punto in cui ti trovi, dovresti essere in grado di osservare nuove iOS e Android i cartelle del tuo progetto React.

Sono progetti nativi reali!

Per accedere al progetto Android in seguito, è necessario installare Android Studio. Per iOS, hai bisogno di un Mac e dovresti installare Xcode.

Inoltre, dovresti trovare un file capacitor.config.ts che contiene alcune impostazioni fondamentali Capacitor utilizzate durante la sincronizzazione. L'unica cosa a cui dovresti prestare attenzione è il directoryWeb, che deve puntare al risultato del comando di build. Attualmente, è inesatto.

Per correggere questo, apri il capacitor.config.json file e aggiorna il directoryWeb:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "out",
  "bundledWebRuntime": false
}

Puoi provarlo eseguendo i seguenti comandi:

npm run build
npx cap sync

Il primo comando npm run build costruirà semplicemente il tuo progetto React e esporterà la costruzione statica.

Mentre il secondo comando npx cap sync sincronizzerà tutti i web code nei posti giusti delle piattaforme native affinché possano essere visualizzati in un'app.

Inoltre, il comando di sincronizzazione potrebbe aggiornare le piattaforme native e installare plugin, quindi quando installi un nuovo Capacitor plugin È ora il momento di eseguire npx cap sync ancora.

Senza accorgersene, si è ora effettivamente finiti, quindi vediamo l'applicazione su un dispositivo!

Sviluppa e distribuisci applicazioni native

Per sviluppare applicazioni iOS, è necessario avere Xcode installato, e per le applicazioni Android, è necessario avere Android Studio installato. Inoltre, se si prevede di distribuire l'applicazione sul negozio di app, è necessario iscriversi al programma di sviluppatore Apple per iOS e al Google Play Console per Android.

Se si è nuovi allo sviluppo di applicazioni mobili native, si può utilizzare il Capacitor CLI per aprire facilmente entrambi i progetti nativi:

npx cap open ios
npx cap open android

Una volta impostati i progetti nativi, il deployment dell'applicazione su un dispositivo connesso è facile. In Android Studio, è sufficiente attendere che tutto sia pronto, e si può deployare l'applicazione su un dispositivo connesso senza modificare alcun setting. Ecco un esempio:

In Xcode, è necessario configurare il proprio account di firma per distribuire l'applicazione su un dispositivo reale invece che solo sul simulatore. Se non l'hai fatto prima, Xcode ti guida attraverso il processo (ma di nuovo, devi essere iscritto al Programma per sviluppatori). Dopo di che, puoi semplicemente premere play per eseguire l'app sul tuo dispositivo connesso, che puoi selezionare in alto. Ecco un esempio:

Congratulazioni! Hai avuto successo nel distribuire la tua app web React su un dispositivo mobile. Ecco un esempio:

Ma aspetta, c'è anche un modo più veloce per farlo durante lo sviluppo…

Capacitor Live Reload

Da adesso, sei probabilmente abituato a avere il reload caldo 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 su il tuo rete avendo l'app Capacitor caricare il contenuto dalla specifica URL.

Il primo passo è capire l'indirizzo IP locale. Se stai utilizzando un Mac, puoi scoprirlo eseguendo il seguente comando nel terminale:

ipconfig getifaddr en0

Su Windows, esegui:

ipconfig

Poi 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 il port correttiNell'esempio ho utilizzato il porto predefinito di React.

Ora possiamo applicare queste modifiche copiandole nel nostro progetto nativo:

npx cap copy

Il copy comando è simile a syncma ciò che farà è solo copierà le modifiche apportate al folder web e alla configurazione, senza aggiornare il progetto nativo.

Ora puoi 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!

Tieni presente che se installi nuovi plugin come la fotocamera, è ancora necessario un rebuild del tuo progetto nativo. Ciò è dovuto al fatto che i file nativi sono stati modificati, e ciò non può essere fatto in tempo reale.

Nota che dovresti utilizzare l'IP e il port corretti nella tua configurazione. Il blocco code sopra mostra il port di reazione predefinito per scopi dimostrativi.

Utilizzo dei Capacitor Plugins

Ecco un esempio di come utilizzare un Capacitor plugin in azione, di cui abbiamo parlato prima. Per farlo, possiamo installare un plugin abbastanza semplice eseguendo:

npm i @capacitor/share

Non c'è nulla di particolarmente complesso in questo Condividi plugin, ma porta comunque in esecuzione la finestra di dialogo di condivisione nativa! 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 menzionato in precedenza, quando installiamo nuovi plugin, dobbiamo eseguire un'operazione di sincronizzazione e poi ri-deployare l'app sul nostro dispositivo. Per farlo, esegui il seguente comando:

npx cap sync

Dopo aver premuto il pulsante, potrai assistere alla bella finestra di dialogo di condivisione nativa in azione!

Successivamente, puoi rendere l'app più nativa su iOS e Android con Capgo navigazione e transizioni, e risolvere i problemi di layout comuni di iOS che causano overflow orizzontale o aree sicure tagliate.

Interfaccia utente con sentore di nativezza con Capgo Navigazione e Transizioni native

L'ho lavorato per anni con Ionic To costruire applicazioni cross-platform, ma integrarla con React è un po' artigianale e raramente vale la pena quando già ne hai una 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 uno 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 il kit UI Ionic.

Installa entrambi:

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

Configura 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',
  },
});

Rendi una barra delle schede di vetro liquido (su iOS si utilizza la rendering di sistema; su Android si utilizza un sfondo di 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 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>;
}

Avvolgi le pagine di destinazione nel contenitore dell'app: cap-router-outlet, cap-pageEcco le guide complete: cap-contentUtilizza @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navigazione-nativa setDirection('forward') e setDirection('back') Utilizza @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transizioni

Aree sicure con Tailwind Using @capgo/capacitor-native-navigation @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ Using @capgo/capacitor-transitions.

Non duplicare i testi di intestazione o di piè di pagina quando la navigazione nativa gestisce queste superfici.

Oppure @capgo/tailwind-capacitor Ecco le guide complete: Utilizza @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navigazione-nativa e Utilizza @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transizioni 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 al posto di aggiungerli env(safe-area-inset-*) manualmente. 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 Flusso Orizzontale)

Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o regolare il tag viewport da solo non risolve di solito il problema. Passa attraverso questi controlli in ordine.

assicurati che il meta tag viewport sia applicato correttamente

Aggiungi l'etichetta 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 unico wrapper radice

Crea un unico contenitore dell'applicazione e applica il padding dell'area sicura lì — non nei 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-shellIl padding dell'area sicura duplicato 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 lo stesso padding con utility come pt-safe pb-safe px-safe su quel singolo contenitore.

Imposta Capacitor iOS contentInset su never primo

In capacitor.config.ts, preferisci l'inserimento nativo disabilitato e lascia che CSS (o la navigazione nativa) gestisca l'area sicura: contentInsetMode: 'css'Mescolare l'inserimento automatico del contenuto di __CAPGO_KEEP_0__ con CSS

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'dist',
  ios: {
    contentInset: 'never',
  },
};

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Trova l'elemento che sta veramente sovrapprendendo.

Il solito colpevole è un elemento che utilizza

, Tailwind 100vw, una larghezza in pixel fisse, o un grande w-screenIn Safari Web Inspector, esegui: min-width.

Con Tailwind, sostituisci

[...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 With w-full quando possibile. Molti problemi di sovrapposizione orizzontale derivano da 100vw / w-screen, sovrapposizione di padding di area sicura duplicata, o da 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 Capgo, è ancora più facile aggiungere aggiornamenti in tempo reale all'applicazione, assicurando che gli utenti abbiano sempre accesso alle ultime funzionalità e correzioni di bug.

Se desideri imparare a aggiungere Capgo al tuo'app React, consulta l'articolo successivo:

Continua a leggere 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 automazione CI/CD per il flusso di lavoro del prodotto in Capgo automazione CI/CD, Capgo Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e GitHub Integrazione delle azioni per i dettagli di implementazione in GitHub Integrazione delle azioni.