Creare App Mobili con Angular e Capacitor

In questo tutorial, inizieremo con una nuova Angular app e passeremo nel regno delle applicazioni mobili native utilizzando Capacitor. Puoi anche aggiungere la Capgo Navigazione e le Transizioni native per un tocco mobile nativo, e utilizzare tailwind-capacitor per aree sicure.

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

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

Questo tutorial ti guiderà attraverso il processo, iniziando con una nuova app Angular e poi incorporando Capacitor per passare nel regno delle app mobili native. Puoi anche utilizzare la Capgo Navigazione, le Transizioni e tailwind-capacitor per aree sicure.

Al riguardo di Capacitor

CapacitorJS è un vero cambiamento! Puoi incorporarlo facilmente in qualsiasi progetto web, e lo stesso genererà un progetto Xcode e Android Studio nativo per te. Inoltre, i suoi plugin ti danno accesso alle funzionalità del dispositivo nativo come la fotocamera tramite un ponte JS.

Con Capacitor, ottenete una fantastica app mobile nativa senza alcuna configurazione complessa o curva di apprendimento ripida. La sua API sottile e la sua funzionalità ottimizzata rendono facile integrarla nel vostro progetto. Sono sicuro che sarete sorpresi dalla facilità con cui potrete ottenere un'app mobile nativa completamente funzionale con Capacitor!

Preparazione dell'app Angular

Per creare una nuova app Angular, esegui il seguente comando:

ng new my-app
cd my-app

Scegli 'Angular' quando ti viene chiesto la versione di Angular.

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 copiare il progetto Angular:

{
  "scripts": {
    // ...
    "build": "ng build --prod"
  }
}

Dopo l'esecuzione del comando build, dovresti essere in grado di notare un nuovo dist folder alla radice del tuo progetto.

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

Aggiungere Capacitor al tuo App Angular

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

In primo luogo, possiamo installare il Capacitor CLI come dipendenza di sviluppo, e quindi 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 alla radice del nostro progetto:

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your Angular 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

In questo punto, dovresti essere in grado di osservare nuove ios e targetLanguage":"Italian","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"texts":["android","cartelle del tuo progetto Angular.","Sono progetti nativi reali!","Per accedere al progetto Android in seguito, devi installare","Android Studio",". Per iOS, hai bisogno di un Mac e dovresti installare","Xcode","Inoltre, dovresti trovare un","__CAPGO_KEEP_0__.config.ts","file nel tuo progetto, che contiene alcune impostazioni fondamentali __CAPGO_KEEP_0__ utilizzate durante la sincronizzazione. L'unica cosa a cui devi prestare attenzione è il","webDir",", che deve puntare al risultato del tuo comando di build. Attualmente, è inesatto."]} protectedTokens

texts

targetLanguage protectedTokenstexts targetLanguage.

protectedTokens capacitor.config.ts file in your project, which contains some fundamental Capacitor settings utilized during the sync. The only thing you need to pay attention to is the protectedTokenstexts

Per risolvere questo problema, apri il file capacitor.config.json e aggiorna la sezione webDir:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

Puoi provare a eseguirlo con i seguenti comandi:

npm run build
npx cap sync

Il primo comando npm run build costruirà semplicemente il tuo progetto Angular e copierà la build 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 è il momento di eseguire npx cap sync ancora.

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

Costruisci e distribuisci applicazioni native

Per sviluppare applicazioni iOS, avete bisogno di avere Xcode installato, e per le applicazioni Android, avete bisogno di avere Android Studio installato. Inoltre, se pianificate di distribuire la vostra applicazione sul negozio di app, dovete iscrivervi al programma di sviluppo Apple per iOS e al Google Play Console per Android.

Se siete nuovi allo sviluppo di applicazioni mobili native, potete utilizzare il Capacitor CLI per aprire facilmente entrambi i progetti nativi:

npx cap open ios
npx cap open android

Una volta impostati i vostri progetti nativi, distribuire l'applicazione su un dispositivo connesso è facile. In Android Studio, basta aspettare che tutto sia pronto, e potete distribuire l'applicazione su un dispositivo connesso senza modificare alcun impostazione. Ecco un esempio:

In Xcode, avete bisogno di configurare il vostro account di firma per distribuire l'applicazione su un dispositivo reale invece che solo sul simulatore. Se non avete fatto questo prima, Xcode vi guida attraverso il processo (ma ancora una volta, dovete essere iscritti al programma di sviluppo). Successivamente, potete semplicemente premere play per eseguire l'applicazione sul vostro dispositivo connesso, che potete selezionare in alto. Ecco un esempio:

Congratulazioni! Hai avuto successo nel distribuire la tua app web Angular 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 app ospitata localmente con live reload su il tuo rete avendo l'app Capacitor caricare il contenuto dalla specifica URL.

Il primo passo è capire il tuo indirizzo IP locale. Se stai utilizzando un Mac, puoi scoprire questo esplorando il seguente comando nel terminale:

ipconfig getifaddr en0

On Windows, run :

ipconfig

Poi cerca l'indirizzo IPv4.

Possiamo 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: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:4200',
    cleartext: true
  }
};

export default config;

Assicurati di utilizzare l'indirizzo IP e il port corretti, ho utilizzato il porto predefinito di Angular in questo esempio.

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

npx cap copy

Il copy comando è simile a sync, ma copierà solo le modifiche apportate al cartella web e la configurazione, senza aggiornare il progetto nativo.

Ora puoi distribuire nuovamente la tua app tramite Android Studio o Xcode. Dopo di che, se cambi qualcosa nella tua app Angular, l'app si ricaricherà automaticamente e mostrerà le modifiche!

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

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

Utilizzo dei plugin Capacitor

Ecco un esempio di 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 condivisione, ma comunque apre il dialogo di condivisione nativo! Per questo ora abbiamo bisogno solo di importare il pacchetto e chiamare la funzione corrispondente dal nostro app, quindi cambiamo il share() __CAPGO_KEEP_0__ src/app/app.component.ts per questo:

import { Component } from '@angular/core';
import { Share } from '@capacitor/share';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  title = 'my-app';

  async share() {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends'
    });
  }
}

Come abbiamo già detto, quando si installano nuovi plugin, è necessario eseguire un'operazione di sincronizzazione e poi ri-deployare l'app sul dispositivo. Per farlo, esegui il seguente comando:

npx cap sync

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

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 overflow orizzontale o aree sicure tagliate.

Interfaccia utente con un aspetto nativo con Capgo Navigazione e Transizioni Native

Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Angular è un processo complicato e raramente vale la pena quando già si dispone di Tailwind CSS.

Per un aspetto mobile nativo in un'app Angular + Capacitor utilizza i plugin Capgo al posto di kit UI web come Konsta UI:

• @capgo/capacitor-native-navigation — 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 Angular mantiene lo stato delle rotte; il plugin possiede il chrome nativo.
• @capgo/capacitor-transizioni — transizioni di pagina dello stile Ionic e swipe indietro su iOS nel layer WebView, senza adottare l'interfaccia utente di Ionic.

Installa entrambi:

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

Configura la navigazione nativa con il CSS inset mode in modo che 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 di tab di vetro liquido (su iOS si utilizza la rendering di sistema; su Android si utilizza un sfondo sfocato del layer WebView):

import { inject } from '@angular/core';
import { Router } from '@angular/router';

const router = inject(Router);

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 }) => {
  router.navigate([`/${id}`]);
});

Add native page transitions in your app shell:

```typescript
// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import { Router } from '@angular/router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions';

initTransitions({ platform: 'auto' });

@Component({
  selector: 'app-root',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-router-outlet #outlet platform="auto" swipe-gesture="auto">
      <router-outlet></router-outlet>
    </cap-router-outlet>
  `,
})
export class AppComponent implements AfterViewInit {
  @ViewChild('outlet') outlet?: ElementRef<HTMLElement>;

  constructor(private router: Router) {}

  ngAfterViewInit() {
    if (this.outlet?.nativeElement) {
      setupRouterOutlet(this.outlet.nativeElement, { platform: 'auto', swipeGesture: 'auto' });
    }
  }

  openSettings() {
    setDirection('forward');
    this.router.navigate(['/settings']);
  }
}

Avvolgi le pagine di rotta in cap-router-outlet, cap-page, e cap-content, e chiama 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: Usando @capgo/capacitor-navigazione nativa e Usando @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 utilità e altri plugin Tailwind amichevoli con Capacitor:

bun add -D tailwind-capacitor

In src/styles.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 spruzzare env(safe-area-inset-*) sviluppato attivamente — se qualcosa manca per la tua configurazione Angular, apri una PR su GitHub.

I Problemi di Layout iOS (Viewport, Area di Sicurezza e Scoramento 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. Esegui questi controlli in ordine.

Assicurati che il tag meta viewport sia applicato correttamente

In src/index.html, impostare il tag meta viewport in <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 più componenti nidificati:

html,
body,
app-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-shell. Il sovrapposizionamento di padding di sicurezza duplicato in intestazioni, modali e wrapper di layout può rendere l'interfaccia utente appiattita o troppo grande.

Con @capgo/tailwind-capacitor, puoi esprimere lo stesso padding con utilità come pt-safe pb-safe px-safe su quel singolo shell.

Imposta Capacitor iOS contentInset su never primo

In capacitor.config.ts, preferisci l'inserimento di contenuto 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: 'www',
  ios: {
    contentInset: 'never',
  },
};

La mescolanza di Capacitor’s automatico contenuto inset con CSS env(safe-area-inset-*) La spaziatura è una causa comune di doppia spaziatura.

Trova l'elemento che sta effettivamente sovrapponendosi

L'elemento colpevole è spesso un elemento che utilizza 100vwTailwind w-screenun'altezza in pixel fisse, 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 sovrapposizione orizzontale derivano da 100vw / w-screenduplicati padding di area sicura, o un contenitore a 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'app, assicurando che i tuoi utenti abbiano sempre accesso alle ultime funzionalità e correzioni di bug.

Se desideri imparare a aggiungere Capgo alla tua app Angular, prendi un'occhiata all'articolo successivo:

Continua da Building Mobile Apps con Angular e Capacitor

Se stai utilizzando Building Mobile Apps con Angular e Capacitor per pianificare il comportamento di media e interfaccia nativa, connettilo con Utilizzando @capgo/capacitor-live-activities per la capacità nativa in Utilizzando @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio di implementazione in @capgo/capacitor-live-activities, Usando @capgo/capacitor-player-video per la capacità nativa in Usando @capgo/capacitor-player-video, @capgo/capacitor-player-video per il dettaglio di implementazione in @capgo/capacitor-player-video, e Usando @capgo/capacitor-navigazione-nativa per la capacità nativa in Usando @capgo/capacitor-navigazione-nativa.