Costruire App Mobili con Angular e Capacitor

In questo tutorial, inizieremo con una nuova app Angular e passeremo al mondo delle app mobili native utilizzando __CAPGO_KEEP_0__. Puoi anche aggiungere la navigazione e le transizioni nativa __CAPGO_KEEP_1__ per un'app mobile nativa e utilizzare tailwind-__CAPGO_KEEP_2__ per aree sicure. app and transition into the native mobile app realm 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 Angular web application into a native mobile app without requiring significant modifications or learning a new skill like React Native.

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

Questo tutorial 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 Capgo per la navigazione nativa, le transizioni e tailwind-capacitor per aree sicure.

Sul Capacitor

CapacitorJS è un vero cambiamento! Puoi incorporarlo facilmente in qualsiasi progetto web e lo vedrai avvolgere la tua applicazione in un webview nativo, 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 una fantastica app mobile nativa 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 da quanto sia facile raggiungere un'app mobile nativa completa 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 richiesto per la versione di Angular.

Per creare un'app mobile nativa, abbiamo bisogno di un export del nostro progetto. Quindi, incorporiamo uno script semplice nel nostro package.json That può essere utilizzato per creare e copiare il progetto Angular:

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

Dopo l'esecuzione del comando buildpotresti notare un nuovo dist cartella nella radice del tuo progetto.

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

Aggiungere Capacitor al tuo progetto Angular

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

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

A questo punto, dovresti essere in grado di osservare nuove ios e android cartelle nel tuo progetto Angular.

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 capacitor.config.ts il file del tuo progetto, che contiene alcune impostazioni fondamentali Capacitor 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.

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

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

Puoi provare a farlo eseguendo 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, in modo che possano essere visualizzati nell'app.

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

Senza accorgersi, si è già concluso, quindi vediamo l'app sul dispositivo!

Costruisci e distribuisci app native

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

Se sei nuovo allo sviluppo di app mobili native, puoi utilizzare il Capacitor CLI per aprire facilmente entrambi i progetti nativi:

npx cap open ios
npx cap open android

Una volta che hai configurato i tuoi progetti nativi, distribuire la tua app su un dispositivo connesso è facile. In Android Studio, non devi fare altro che attendere che tutto sia pronto, e puoi distribuire la tua app su un dispositivo connesso senza modificare alcun impostazione. Ecco un esempio:

In Xcode, devi configurare 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 per sviluppatori). Successivamente, 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 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 applicazione ospitata localmente con live reload On 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 scoprire questo eseguendo il seguente comando nel terminale:

ipconfig getifaddr en0

On Windows, esegui :

ipconfig

Poi cerca l'indirizzo IPv4.

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

export default config;

Sii sicuro di utilizzare l'indirizzo IP e la porta corretti Ho utilizzato la porta Angular predefinita in questo esempio.

Ora, possiamo applicare questi cambiamenti copiandoli nel nostro progetto nativo:

npx cap copy

Le copy il comando è simile a syncma lo utilizzerai solo copierai solo le modifiche apportate al folder web e alla configurazione, senza aggiornare il progetto nativo.

Puoi ora distribuire nuovamente la tua app tramite Android Studio o Xcode. Dopo di che, se cambi qualcosa nell'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 progetto nativo. Ciò è dovuto al fatto che i file nativi sono stati modificati, e ciò non può essere fatto in modo dinamico.

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

Utilizzo dei Capacitor Plugins

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

There’s nothing fancy about il Condividi plugin, but it anyway brings up the native share dialog! For this we now only need to import the package and call the according share() funzione from our app, so let’s change the src/app/app.component.ts to this:

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 menzionato in precedenza, when installing new plugins, we need to perform a sync operation and then redeploy the app to our device. To do this, run the following command:

npx cap sync

Dopo aver premuto il pulsante, you can witness the beautiful native share dialog in action!

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.

Interfaccia utente con sentore nativo con Capgo Native Navigation and Transitions

Ho lavorato per anni con Ionici To costruire applicazioni cross-platform, ma integrarla con Angular è un po' artigianale e raramente vale la pena quando già ne hai una Per un aspetto nativo su dispositivi mobili in un'app Angular + __CAPGO_KEEP_0__ utilizza i plugin __CAPGO_KEEP_1__ al posto di kit UI web-only come Konsta UI:.

@Capacitor/Capgo-native-navigation

• @capgo/capacitor-native-navigation @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions
• @capgo/capacitor-transitions Installa entrambi:

Configura la navigazione nativa con modalità CSS inset affinché il contenuto web rispetti le barre native:

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

Rendi una barra delle schede di vetro liquido (su iOS viene utilizzato il rendering di sistema; su Android viene utilizzato un sfondo sfocato della WebView):

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Avvolgi le pagine di rotta in

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

, e cap-router-outlet, cap-pagee 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 queste superfici.

Vedi le guide complete: Utilizzare @capgo/capacitor-navigazione-nativa e Utilizzare @capgo/capacitor-transizioni.

Aree sicure con Tailwind

Per le 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/styles.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

Usa strumenti come pt-safe, pb-safe, e px-safe invece di spargere env(safe-area-inset-*) manualmente. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Angular, 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 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

In src/index.html, impostare la meta tag di viewport <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

Gestisci l'area sicura di iOS da un wrapper root solo

Crea un singolo contenitore dell'applicazione e applica il padding dell'area sicura lì — non nei componenti nidificati multipli:

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 tutta il contenuto della pagina dentro .app-shell. Il 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 utilità come pt-safe pb-safe px-safe su quel singolo contenitore.

Imposta Capacitor iOS contentInset a never primo

In capacitor.config.ts, prefer native inset disabilitato e lascia che CSS (o la navigazione nativa) contentInsetMode: 'css'own the safe area:

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

Mixing Capacitor’s automatic content inset con CSS env(safe-area-inset-*) padding è una causa comune di doppio spazio.

Trova l'elemento che sta veramente sovrapponendo

Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screen, Tailwind min-width.

, una larghezza in pixel fissi, o un grande

[...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,
  }));

In Safari Web Inspector, esegui: w-screen Con Tailwind, sostituisci con w-full quando possibile. Molti problemi di sovrapposizione orizzontale derivano da 100vw / w-screen, padding di area sicura duplicato, o da un contenitore di larghezza fissata — non dal tag meta viewport stesso.

Conclusioni

Capacitor è un'ottima opzione 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 desiderate imparare a aggiungere Capgo al vostro'app Angular, guardate il prossimo articolo:

Continuate a leggere da Building Mobile Apps con Angular e Capacitor

Se state utilizzando Building Mobile Apps con Angular e Capacitor per pianificare il comportamento di media e interfaccia nativi, connettetelo con Utilizzando @capgo/capacitor-live-attività per la capacità nativa in Utilizzando @capgo/capacitor-live-attività @capgo/capacitor-live-attività per il dettaglio di implementazione in @capgo/capacitor-live-attività 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.