Creare App Mobili con React e Capacitor

In questo tutorial, inizieremo con una nuova React app e passeremo alla sviluppo mobile nativo utilizzando Capacitor. Puoi anche aggiungere Capgo per una navigazione e transizioni native, e utilizzare tailwind-capacitor per aree sicure.

Capacitor consente di convertire facilmente la tua applicazione web React in un'app mobile nativa senza modifiche significative o l'apprendimento di una nuova abilità come React Native.

Con solo pochi passaggi, la maggior parte delle applicazioni React può essere trasformata in app mobili.

Questo tutorial ti guiderà attraverso il processo, iniziando con una nuova app React e poi incorporando Capacitor per passare nel mondo degli app mobili native. Puoi anche utilizzare Capgo per la navigazione, le transizioni e tailwind-capacitor per aree sicure.

Sul Capacitor

CapacitorJS è un vero cambiamento! Puoi incorporarlo facilmente in qualsiasi progetto web e lo utilizzerai per avvolgere la tua applicazione in una view web nativa, generando il progetto Xcode e Android Studio nativo per te. Inoltre, i suoi plugin forniscono accesso alle funzionalità del dispositivo nativo come la fotocamera tramite un ponte JS.

Con Capacitor, ottieni un'app mobile nativa fantastica senza alcuna configurazione complessa o curva di apprendimento ripida. La sua API e funzionalità streamlinata rendono facile integrarla nel tuo progetto. Sono sicuro che sarai impressionato dalla facilità con cui puoi ottenere un'app mobile nativa completa con Capacitor!

Preparazione dell'App React

Sebbene ci siano diversi metodi per avviare le applicazioni React, in questo tutorial scegliamo il metodo più semplice che fornisce un'applicazione React vuota:

npx create-react-app my-app

In modo da creare un'applicazione mobile nativa, abbiamo bisogno di un export del nostro progetto. Quindi, aggiungiamo 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 preoccupazioni, e dovresti essere in grado di vedere un nuovo cartello di uscita nel root del tuo progetto.

This folder will be used by Capacitor later on, but for now, we must set it up correctly.

Adding Capacitor to Your React App

in seguito, ma per ora dobbiamo configurarlo correttamente. sync Aggiungere Capacitor alla tua App React

Infine, possiamo installare il Capacitor CLI come dipendenza di sviluppo, e poi configurarlo nel 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 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

Da questo punto, dovresti essere in grado di osservare nuove ios e context: Pagina/Area: Sito web di marketing Capgo. Ruolo: Etichetta UI breve o elemento di navigazione. Visto in: pagina trust.astro. Chiave di messaggio `e` (E). android

cartelle nel tuo progetto React.

Sono progetti nativi reali! Studio Android. Per iOS, hai bisogno di un Mac e dovresti installare Xcode.

Inoltre, dovresti trovare un file capacitor.config.ts nel tuo progetto, che contiene alcune impostazioni fondamentali Capacitor utilizzate durante la sincronizzazione. L'unica cosa di cui dovresti tenere conto è il webDircontext:HTML text fragment from a longer Capgo UI string (parent key `solutions_cordova_to_capacitor_ai_step2_body`). Page/area: Capgo solutions marketing page. Role: Website copy sentence. Seen in: page solutions/cordova-to-capacitor-ai.astro. Message key `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body).

, che deve puntare al risultato del tuo comando di build. Attualmente, è inesatto. capacitor.config.json __CAPGO_KEEP_0__.config.json file e aggiorna il campo di configurazione denominato "webDir" (HTML text fragment from a longer Capgo UI string (parent key `solutions_cordova_to_capacitor_ai_step2_body`). Page/area: Capgo solutions marketing page. Role: Website copy sentence. Seen in: page solutions/cordova-to-capacitor-ai.astro. Message key `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body).:

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

Esegui i seguenti comandi per provare:

npm run build
npx cap sync

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

Mentre il secondo comando npx cap sync syncronizzerà tutti i web code nei posti giusti delle piattaforme native, in modo che 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 è il momento di eseguire npx cap sync nuovamente.

Senza accorgersene, sei ora effettivamente finito, quindi vediamo l'app sul dispositivo!

Costruisci e distribuisci app native

Per sviluppare app iOS, hai bisogno di Xcode installato e per le app Android, hai bisogno di avere Android Studio installato. Inoltre, se hai l'intenzione 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.

Se sei nuovo nel mondo dello sviluppo mobile nativo, puoi utilizzare il Capacitor CLI per aprire facilmente entrambi i progetti nativi:

npx cap open ios
npx cap open android

Una volta impostati i tuoi progetti nativi, distribuire la tua app su un dispositivo connesso è facile. In Android Studio, basta aspettare che tutto sia pronto, e puoi distribuire la tua app su un dispositivo connesso senza modificare alcun impostazione. Ecco un esempio:

In Xcode, devi impostare il tuo account di firma per distribuire la tua app su un dispositivo reale invece che solo sul simulatore. Se non hai fatto questo prima, Xcode ti guida attraverso il processo (ma di nuovo, devi essere iscritto al programma di sviluppo). 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 distribuito con successo 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, probabilmente sei abituato a avere il caricamento 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 caricamento caldo su il tuo rete avendo l'app Capacitor caricare il contenuto da l'URL specifico.

Il primo passo è capire la tua indirizzo IP locale. Se stai utilizzando un Mac, puoi trovare questo fuori eseguendo il comando seguente nel terminale:

ipconfig getifaddr en0

Su Windows, esegui :

ipconfig

Poi cerca l'indirizzo IPv4.

Posiamo istruire Capacitor a caricare l'app direttamente dal server aggiungendo un'altra voce nel 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 porto corretti, ho utilizzato il porto predefinito di React in questo esempio.

Ora, possiamo applicare queste modifiche copiandole nel nostro progetto nativo:

npx cap copy

La copy questa istruzione è simile a sync, ma copierà solo 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!

Tenete presente che se installate nuovi plugin come la fotocamera, è comunque necessario un rebuild del progetto nativo. Ciò è dovuto al fatto che i file nativi sono cambiati, e non è possibile farlo in modo dinamico.

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 Plugin Capacitor

Vediamo come utilizzare un plugin Capacitor 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 nel plugin di condivisionema comunque apre il dialogo di condivisione nativo! Per questo, adesso dobbiamo solo importare il pacchetto e chiamare la share() funzione dal nostro app. Modifichiamo il src/App.js a questo:

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 prima, quando si installano nuovi plugin, è necessario 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 condivisione nativa in azione!

Successivamente, puoi rendere l'app più nativa su iOS e Android con la Capgo navigazione e le transizioni, 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 Capgo Navigazione e Transizioni native

Lavoro da anni con Ionic per costruire applicazioni cross-platform, ma integrarla 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 UI web-only come Konsta UI:

• @capgo/capacitor-navigazione-nativa --- barra di navigazione nativa, Liquid Glass barra dei tab su iOS, e uno stile di barra dei tab sfocato su Android. Il tuo router React mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
• @capgo/capacitor-transizioni — Transizioni di pagina in stile Ionic e swipe-back di iOS nell layer WebView, senza adottare l'interfaccia utente di Ionic.

Installare sia:

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

Configurare la navigazione nativa con il modello di inset 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',
  },
});

Rendere una barra di tab di vetro liquido (iOS utilizza la rendering di sistema; Android 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}`);
});

Aggiungere le 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-pagee cap-contente chiamare setDirection('forward') o setDirection('back') Page/area: Pagina di confronto delle alternative per l'aggiornamento live di Capacitor. Ruolo: Lungo paragrafo di marketing o legale. Visto in: pagina alternatives.astro. Preservare i termini di prodotto e marchio di Capgo e i termini di sviluppatore esattamente. Chiave di messaggio `alternatives_cta_questions` (Domande per l'azione delle alternative). | Pagina/area: Pagina di confronto e migrazione per Appflow. Ruolo: Lungo paragrafo di marketing o legale. Visto in: pagina ionic-appflow.astro. Preservare i termini di prodotto e marchio di Capgo e i termini di sviluppatore esattamente. Chiave di messaggio `appflow_cta_questions` (Domande per l'azione di Appflow). | Pagina/area: Pagina di confronto per Capawesome. Ruolo: Lungo paragrafo di marketing o legale. Visto in: pagina capwesome.astro. Preservare i termini di prodotto e marchio di Capgo e i termini di sviluppatore esattamente. Chiave di messaggio `capwesome_cta_questions` (Domande per l'azione di Capawesome). | Pagina/area: Pagina dei servizi di consulenza. Ruolo: Sottotitolo o didascalia di sezione. Visto in: pagina consulting.astro. Preservare i termini di prodotto e marchio di Capgo e i termini di sviluppatore esattamente. Chiave di messaggio `consulting_faq_subtitle` (Sottotitolo FAQ dei servizi di consulenza). | Pagina/area: Pagina di confronto e migrazione per Appflow. Ruolo: Etichetta di navigazione breve o elemento di navigazione. Visto in: pagina ionic-appflow.astro, pagina ionic-enterprise-plugins.astro, pagina solutions/ionic-enterprise-plugins.astro. Chiave di messaggio `appflow_plugins_or` (Appflow Plugins O).

prima di navigare. Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa possiede quelle superfici. Vedere le guide complete: «Usare @capgo/capacitor-native-navigation». E e Utilizzando @capgo/capacitor-transizioni.

Aree sicure con Tailwind

Per le aree sicure del dispositivo in Tailwind CSS, utilizzare @capgo/tailwind-capacitor Pubblicato su tailwind-capacitor npm safe-areas Fornisce utilità 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";

Utilizzare utilità come pt-safe, pb-safe, e px-safe al posto di diffondere env(safe-area-inset-*) con le proprie mani. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione React, apri un PR su GitHub.

Il problema dei layout 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 il tag viewport da solo non risolve di solito il problema. Esegui 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 solo wrapper radice

Creati un unico contenitore dell'applicazione e applica la spaziatura di sicurezza dell'area lì — non in più componenti nidificati:

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 tutto il contenuto della pagina all'interno .app-shellLa spaziatura di sicurezza dell'area duplicata nei titoli, nei modali e nei wrapper di layout spesso fa sembrare il UI tagliato o troppo grande.

With @capgo/tailwind-capacitor, puoi esprimere la stessa spaziatura con utilità come pt-safe pb-safe px-safe su quella singola shell.

Imposta Capacitor iOS contentInset su never context: Pagina/Area: Pagina prodotto per aggiornamenti in tempo reale. Ruolo: Etichetta UI breve o elemento di navigazione. Chiave messaggio `live_update_dynamic_label_to` (Etichetta dinamica di aggiornamento in tempo reale To).

primo capacitor.config.tsIn contentInsetMode: 'css', preferisci l'inserimento nativo disabilitato e lascia che CSS (o la navigazione nativa)

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-*) Mischia l'inserimento automatico di contenuto di __CAPGO_KEEP_0__ con CSS

Trova l'elemento che sta veramente sovraccaricando

Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screen, un'altezza 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, padding di area sicura duplicato, o un contenitore di larghezza fissata — non dal tag meta viewport stesso.

Conclusioni

Capacitor è un'ottima opzione per creare 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 CapgoE' 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 alla tua 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 del flusso di lavoro CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD Capgo Build Native per il flusso di lavoro del prodotto in Capgo Build Native Capgo Integrazioni per il workflow del prodotto in Capgo Integrazioni, Integrazione CI/CD context: Pagina/Area: Capgo Builder / prodotto di costruzione nativa cloud. Ruolo: Etichetta UI breve o elemento di navigazione. Chiave di messaggio `native_build_feature_ci_cd` (Native Build Feature Ci Cd). GitHub Actions Integration GitHub Azioni di integrazione