Créer des applications mobiles avec Angular et Capacitor

Dans ce tutoriel, nous allons commencer par un nouveau Angular 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 vous permet de convertir facilement votre application web Angular en application mobile native sans nécessiter de modifications importantes ou d'apprendre une nouvelle compétence comme React Native.

En quelques étapes simples, la plupart des applications Angular peuvent être transformées en applications mobiles.

Cet article vous guidera tout au long du processus, en commençant par une nouvelle application Angular et en incorporant ensuite Capacitor pour entrer dans le domaine des applications mobiles natives. Vous pouvez également utiliser Capgo Native Navigation, Transitions et tailwind-capacitor pour les zones de sécurité.

À propos de Capacitor

CapacitorJS est un véritable changement de cap ! Vous pouvez l'intégrer facilement dans tout projet web, et il enveloppera votre application dans une vue web native, générant ainsi les projets Xcode et Android Studio natifs pour vous. De plus, ses plugins vous donnent accès aux fonctionnalités de l'appareil natif comme la caméra via un pont JavaScript.

Avec Capacitor, vous obtenez une fantastique application mobile native sans aucune configuration compliquée ou courbe d'apprentissage raide. Sa API et sa fonctionnalité épurée rendent l'intégration dans votre projet un jeu d'enfant. Croyez-moi, vous serez impressionné par la facilité avec laquelle vous pouvez obtenir une application mobile native complète avec Capacitor !

Préparation de votre application Angular

Pour créer une nouvelle application Angular, exécutez la commande suivante :

ng new my-app
cd my-app

Sélectionnez « Angular » lorsque vous êtes invité à choisir la version d'Angular.

Pour créer une application mobile native, nous avons besoin d'un export de notre projet. Ainsi, ajoutons un script simple à notre package.json que vous pouvez utiliser pour créer et copier le projet Angular :

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

Après avoir exécuté la commande buildvous devriez pouvoir voir un dossier frais à la racine de votre projet. dist Ce dossier sera utilisé par Capacitor plus tard, mais pour l'instant, nous devons le configurer correctement.

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

Adding Capacitor to Your Angular App

Tout d'abord, nous pouvons installer Capacitor et @capgo/cli sync comme une dépendance de développement, et puis les configurer dans notre projet. Lors de la configuration, vous pouvez appuyer sur « Entrée » pour accepter les valeurs par défaut pour le nom et l'ID de l'application.

Ensuite, nous devons installer le package principal et les packages pertinents pour les plateformes iOS et Android. Capacitor CLI comme une dépendance de développement, et puis les configurer dans notre projet. Lors de la configuration, vous pouvez appuyer sur « Entrée » pour accepter les valeurs par défaut pour le nom et l'ID de l'application.

Ensuite, nous devons installer le package principal et les packages pertinents pour les plateformes iOS et Android.

Enfin, nous pouvons ajouter les plateformes, et Capacitor créera des dossiers pour chaque plateforme à la racine de notre projet :

# 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

À ce stade, vous devriez pouvoir observer de nouveaux ios et android dossiers dans votre projet Angular.

Ce sont des projets natifs réels !

Pour accéder au projet Android ultérieurement, vous devez installer Android Studio. Pour iOS, vous avez besoin d'un Mac et devriez installer Xcode.

De plus, vous devriez trouver un capacitor.config.ts fichier dans votre projet, contenant certaines configurations fondamentales Capacitor utilisées lors de la synchronisation. L'unique chose dont vous devez vous soucier est le répertoire web, qui doit pointer vers le résultat de votre commande de build. Actuellement, il est inexact.

Pour rectifier cela, ouvrez le capacitor.config.json fichier et mettez à jour le répertoire web:

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

Vous pouvez essayer cela en exécutant les commandes suivantes :

npm run build
npx cap sync

La première commande npm run build construira simplement votre projet Angular et copiera la build statique, tandis que la deuxième commande npx cap sync synchronisera toutes les web code dans les bons endroits des plateformes natives afin qu'elles puissent être affichées dans une application.

De plus, la commande de synchronisation peut mettre à jour les plateformes natives et installer des plugins, donc lors de l'installation d'un nouveau Capacitor plugins il est temps de relancer npx cap sync encore.

Sans vous en rendre compte, vous êtes maintenant effectivement terminé, alors voyons l'application sur un appareil !

Construire et déployer des applications natives

Pour développer des applications iOS, vous devez avoir Xcode installé, et pour les applications Android, vous devez avoir Android Studio installé. De plus, si vous prévoyez de distribuer votre application sur l'app store, vous devez vous inscrire au programme Apple Developer pour iOS et au Google Play Console pour Android.

Si vous êtes nouveau dans le développement mobile natif, vous pouvez utiliser le Capacitor CLI pour ouvrir facilement les deux projets natives :

npx cap open ios
npx cap open android

Une fois que vous avez configuré vos projets natifs, déployer votre application sur un appareil connecté est facile.

En Xcode, vous devez configurer votre compte de signature pour déployer votre application sur un appareil réel au lieu du simulateur.

Félicitations ! Vous avez réussi à déployer votre application web Angular sur un appareil mobile.

Attendez, il y a aussi une façon plus rapide de procéder pendant le développement…

Capacitor Live Reload

Par conséquent, vous pouvez avoir la même fonctionnalité de rechargement chaud sur un appareil mobile on a mobile device avec un minimum d'efforts !

Activer l'accès à votre application hébergée localement avec rechargement live sur votre réseau en faisant en sorte que l'application Capacitor charge le contenu à partir de l'URL spécifique.

Le premier pas consiste à déterminer votre adresse IP locale. Si vous utilisez un Mac, vous pouvez trouver cela en exécutant la commande suivante dans le terminal :

ipconfig getifaddr en0

On Windows, exécutez :

ipconfig

Recherchez ensuite l'adresse IPv4.

On peut faire en sorte que Capacitor charge l'application directement depuis le serveur en ajoutant une autre entrée à notre capacitor.config.ts fichier :

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;

S'assurez-vous d'utiliser l'adresse IP et le port corrects, j'ai utilisé le port Angular par défaut dans cet exemple.

Maintenant, nous pouvons appliquer ces modifications en les copiant vers notre projet natif :

npx cap copy

Le copy La commande est similaire à sync, mais elle ne mettra à jour que et copiera uniquement les modifications apportées au dossier web et la configuration, sans mettre à jour le projet natif.

Vous pouvez maintenant déployer votre application une fois de plus à l'aide d'Android Studio ou Xcode. Après cela, si vous modifiez quelque chose dans votre application Angular, l'application se rechargera automatiquement et affichera les modifications !

Prenez en compte que si vous installez de nouveaux plugins comme la caméra, il est encore nécessaire de reconstruire votre projet natif. C'est parce que les fichiers natifs sont modifiés, et cela ne peut pas être fait en temps réel.

Notez que vous devez utiliser l'IP et le port corrects dans votre configuration. Le bloc code ci-dessus montre le port Angular par défaut à des fins de démonstration.

Utilisation des Capacitor Plugins

Étudions maintenant comment utiliser un plugin Capacitor en action, que nous avons mentionné quelques fois avant. Pour cela, nous pouvons installer un plugin relativement simple en exécutant :

npm i @capacitor/share

Rien de particulier n'est à dire sur le plugin de partage, mais il apporte quand même le dialogue de partage natif ! Pour cela, nous n'avons besoin désormais que d'importer le package et d'appeler la fonction correspondante de notre application, donc changeons donc le share() src/app/app.component.ts en cela : Comme mentionné précédemment, lors de l'installation de nouveaux plugins, nous devons effectuer une opération de synchronisation et puis redéployer l'application sur notre appareil. Pour cela, exécutez la commande suivante :

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

Après avoir cliqué sur le bouton, vous pouvez assister à la belle apparition du dialogue de partage natif en action !

npx cap sync

Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec la navigation et les transitions __CAPGO_KEEP_0__ et corriger les problèmes de mise en page courants d'iOS qui entraînent un débordement horizontal ou des zones de sécurité coupées.

UI native avec la navigation et les transitions Capgo

Native-feeling UI with Capgo Native Navigation and Transitions

Ionic Je pour construire des applications plate-forme croisée, mais l'intégrer avec Angular est hacky et rarement valable lorsque vous avez déjà Tailwind CSS.

Pour un sentiment mobile natif dans une application Angular + Capacitor , utilisez les Capgo plugins au lieu des kits UI uniquement web comme Konsta UI :

• @capgo/capacitor-native-navigation — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Votre routeur Angular conserve l'état de la route ; le plugin possède la barre de chrome native.
• @capgo/capacitor-transitions — transitions de page à la manière d'Ionic et un retour arrière par swipe sur l'édge sur iOS dans la couche WebView, sans adopter l'UI d'Ionic.

Installez les deux :

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

Configurez la navigation native avec le mode CSS inset afin que le contenu web respecte les barres natives :

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

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

Rendre une barre de tab en verre liquide (iOS utilise la rendu système ; Android utilise un arrière-plan flou de 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']);
  }
}

Enveloppez les pages routées dans cap-router-outlet, cap-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') avant de naviguer. N'insérez pas les en-têtes ou les pieds de page web lorsqu'une navigation native contrôle ces surfaces.

Voir les guides complets : En utilisant @capgo/capacitor-navigation-native et En utilisant @capgo/capacitor-transitions.

Aires sûres avec Tailwind

Pour les zones sûres du dispositif dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié comme tailwind-capacitor sur npm). Il fournit safe-areas outils et autres plugins Tailwind compatibles avec Capacitor:

bun add -D tailwind-capacitor

In src/styles.css:

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

Utilisez des outils tels que pt-safe, pb-safe, et px-safe au lieu de les répandre env(safe-area-inset-*) manuellement. Le projet est actuellement développé — si quelque chose manque pour votre configuration Angular, ouvre une PR sur GitHub.

Résoudre les problèmes de mise en page iOS (Vueport, Zone de sécurité, et Débordement horizontal)

Si le contenu semble coupé, décalé ou scrollable horizontalement sur iOS, ajouter plus de overflow-x: hidden ou ajuster la balise de vueport seule ne suffit généralement pas pour le résoudre. Travaillez à travers ces vérifications dans l'ordre.

Assurez-vous que la balise meta de vueport est appliquée correctement

In src/index.html, définissez la balise meta de viewport en <head>:

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

Traitez l'espace sûr iOS à partir d'un seul enveloppe racine

Créez une coquille d'application unique et appliquez-y la mise en forme de l'espace sûr — et non dans plusieurs composants imbriqués :

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

Enveloppez tout le contenu de la page à l'intérieur .app-shellDupliquer la mise en forme de l'espace sûr dans les en-têtes, les modales et les enveloppes de mise en page peut rendre l'interface utilisateur coupée ou trop grande.

Avec @capgo/tailwind-capacitorvous pouvez exprimer la même mise en forme avec des utilitaires comme pt-safe pb-safe px-safe sur cette coquille unique.

Fixez Capacitor iOS contentInset à never context : Page/zone : Page de mise à jour en direct. Rôle : Étiquette de l'interface utilisateur courte ou élément de navigation. Clé de message `live_update_dynamic_label_to` (Étiquette de mise à jour en direct dynamique à).

Dans capacitor.config.ts, préférez les éléments de mise en page natifs désactivés et laissez CSS (ou la navigation native) gérer l'espace sûr : contentInsetMode: 'css'Mélanger les marges automatiques de contenu de __CAPGO_KEEP_0__ avec les marges CSS est une cause courante de double espace.

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Le coupable habituel est un élément utilisant

, Tailwind

, une largeur de pixels fixe, ou une large 100vwDans l'inspecteur Web de Safari, exécutez : w-screenAvec Tailwind, remplacez min-width.

par

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

Avec w-screen par w-full lorsque possible. Beaucoup d'issues de débordement horizontal proviennent de 100vw / w-screenune duplication de la marge de sécurité de l'espace sûr, ou d'un conteneur de largeur fixe — et non de la balise meta de la vue d'ensemble elle-même.

Conclusion

Capacitor est une excellente option pour construire des applications natives sur la base d'un projet web existant, offrant une façon simple de partager code et de maintenir une interface utilisateur cohérente.

Et avec l'ajout de Capgo, il est même plus facile d'ajouter des mises à jour en temps réel à votre application, vous assurant que vos utilisateurs aient toujours accès aux dernières fonctionnalités et correctifs de bogues.

Si vous souhaitez apprendre à ajouter Capgo à votre application Angular, consultez l'article suivant :

Continuez à partir de Construire des applications mobiles avec Angular et Capacitor

Si vous utilisez Construire des applications mobiles avec Angular et Capacitor pour planifier le comportement de la média et de l'interface native, connectez-l’avec Utilisation de @capgo/capacitor-activités-en-vivre pour la capacité native dans Utilisation de @capgo/capacitor-activités-en-vivre @capgo/capacitor-activités-en-vivre pour le détail d'implémentation dans @capgo/capacitor-activités-en-vivre Utilisation de @capgo/capacitor-joueur-de-videos pour la capacité native dans Utilisation de @capgo/capacitor-joueur-de-videos @capgo/capacitor-joueur-de-videos pour le détail d'implémentation dans @capgo/capacitor-joueur-de-videos, et Utilisation de @capgo/capacitor-navigation-native pour la capacité native dans Utilisation de @capgo/capacitor-navigation-native.