Dans ce tutoriel, nous allons partir d'une nouvelle Angular application Angular pour passer au monde du mobile natif avec Capacitor. Vous pouvez aussi ajouter Capgo Native Navigation and Transitions pour un rendu mobile natif, et utiliser tailwind-capacitor pour gérer les safe areas.
Capacitor vous permet de convertir facilement votre application web Angular en application mobile native, sans nécessiter de modifications majeures ni d'apprendre un nouveau skill comme React Native.
En quelques étapes simples, la plupart des applications Angular peuvent être transformées en applications mobiles.
Ce tutoriel vous guidera tout au long du processus, en partant d'une nouvelle application Angular, puis en intégrant Capacitor pour passer au monde des applications mobiles natives. Vous pouvez également utiliser Capgo Native Navigation, Transitions, et tailwind-capacitor pour les safe areas.
À propos de Capacitor
CapacitorJS change la donne ! Vous pouvez l'intégrer sans effort dans n'importe quel projet web, et il encapsulera votre application dans une webview native, générant pour vous les projets Xcode et Android Studio natifs. De plus, ses plugins permettent d'accéder aux fonctionnalités natives de l'appareil, comme la caméra, via un bridge JS.
Avec Capacitor, vous obtenez une fantastique application mobile native sans configuration complexe ni courbe d'apprentissage abrupte. Son API léger et ses fonctionnalités optimisées le rendent très facile à intégrer à votre projet. Croyez-moi, vous serez étonné de la facilité avec laquelle vous obtiendrez une application native pleinement fonctionnelle avec Capacitor !
Préparer votre application Angular
Pour créer une nouvelle application Angular, exécutez la commande suivante :
ng new my-app
cd my-appChoisissez « Angular » lorsque la version d'Angular est demandée.
Pour créer une application mobile native, nous avons besoin d'un export de notre projet. Ajoutons donc un script simple dans notre package.json qui peut être utilisé pour compiler et copier le projet Angular :
{
"scripts": {
// ...
"build": "ng build --prod"
}
}Après avoir exécuté la commande build, vous devriez voir apparaître un nouveau dist dossier à la racine de votre projet.
Ce dossier sera utilisé par Capacitor par la suite, mais pour l'instant, nous devons le configurer correctement.
Ajouter Capacitor à votre application Angular
Pour packager n'importe quelle application web dans un conteneur mobile natif, il faut suivre quelques étapes initiales, mais ensuite, il suffit d'exécuter une seule sync commande.
Tout d'abord, nous pouvons installer le Capacitor CLI en tant que dépendance de développement, puis le configurer dans notre projet. Lors de la configuration, vous pouvez appuyer sur « entrée » pour accepter les valeurs par défaut du nom et du bundle ID.
Ensuite, nous devons installer le package core ainsi que les packages nécessaires 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 voir de nouveaux dossiers ios et et android dans votre projet Angular.
Ce sont de véritables projets natifs !
Pour accéder au projet Android plus tard, vous devrez installer Android Studio. Pour iOS, vous avez besoin d'un Mac et devez installer Xcode.
De plus, vous devriez trouver un capacitor.config.ts fichier de votre projet, qui contient des paramètres Capacitor fondamentaux utilisés lors de la synchronisation. La seule chose à laquelle vous devez prêter attention est le webDir, qui doit pointer vers le résultat de votre commande de build. Actuellement, il est incorrect.
Pour rectifier cela, ouvrez le capacitor.config.json fichier et mettez à jour le webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Vous pouvez l'essayer en exécutant les commandes suivantes :
npm run build
npx cap syncLa première commande npm run build va simplement builder votre projet Angular et copier le build statique, tandis que la seconde commande npx cap sync va synchroniser tous les code web aux bons endroits des plateformes natives pour qu'ils puissent s'afficher dans une application.
De plus, la commande sync peut mettre à jour les plateformes natives et installer des plugins, donc lorsque vous installez un nouveau Plugins Capacitor il est temps de lancer npx cap sync à nouveau.
Sans même vous en rendre compte, vous avez terminé ! Voyons maintenant l'application sur un appareil.
Compiler et déployer des apps natives
Pour développer des apps iOS, vous devez avoir Xcode installé, et pour les apps Android, vous devez avoir Android Studio installé. De plus, si vous prévoyez de distribuer votre app sur les stores, vous devrez vous inscrire au programme Apple Developer pour iOS et à la Google Play Console pour Android.
Si vous débutez dans le développement mobile natif, vous pouvez utiliser le Capacitor CLI pour ouvrir facilement les deux projets natifs :
npx cap open ios
npx cap open androidUne fois vos projets natifs configurés, déployer votre application sur un appareil connecté est un jeu d'enfant. Dans Android Studio, il vous suffit d'attendre que tout soit prêt pour déployer votre application sur un appareil connecté sans modifier aucun paramètre. Voici un exemple :
Dans Xcode, vous devez configurer votre compte de signature pour déployer votre application sur un appareil réel plutôt que sur le simulateur. Si vous ne l'avez jamais fait, Xcode vous guidera tout au long du processus (mais là encore, vous devez être inscrit au Developer Program). Ensuite, il vous suffit d'appuyer sur play pour lancer l'application sur votre appareil connecté, que vous pouvez sélectionner en haut. Voici un exemple :
Félicitations ! Vous avez déployé avec succès votre application web Angular sur un appareil mobile. Voici un exemple :
Mais attendez, il existe aussi un moyen plus rapide de faire cela pendant le développement…
Capacitor Live Reload
À ce stade, vous avez probablement l'habitude du hot reload avec tous les frameworks modernes, et la bonne nouvelle est que vous pouvez bénéficier de la même fonctionnalité sur un appareil mobile avec un minimum d'effort !
Activez l'accès à votre application hébergée localement avec le live reload sur votre réseau en faisant charger le contenu de l'application Capacitor depuis l'URL spécifique.
La première étape consiste à trouver votre adresse IP locale. Si vous utilisez un Mac, vous pouvez la trouver en exécutant la commande suivante dans le terminal :
ipconfig getifaddr en0Sur Windows, lancez :
ipconfigCherchez ensuite l'adresse IPv4.
Nous pouvons demander à Capacitor de charger 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;Assurez-vous d'utiliser l'IP et le port corrects, j'ai utilisé le port Angular par défaut dans cet exemple.
Maintenant, nous pouvons appliquer ces changements en les copiant dans notre projet natif :
npx cap copyLe copy la commande est similaire à sync, mais elle ne fera que copier 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 via Android Studio ou Xcode. Ensuite, si vous modifiez quelque chose dans votre application Angular, l'application se rechargera automatiquement et affichera les modifications !
Gardez à l'esprit que si vous installez de nouveaux plugins comme la caméra, un rebuild de votre projet natif reste nécessaire. En effet, les fichiers natifs sont modifiés, et cela ne peut pas se faire à la volée.
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.
Utiliser des plugins Capacitor
Voyons concrètement comment utiliser un plugin Capacitor, que nous avons déjà mentionné plusieurs fois. Pour ce faire, nous pouvons installer un plugin assez simple en exécutant :
npm i @capacitor/shareIl n'y a rien de sorcier dans le Plugin de partage, mais cela affiche tout de même la boîte de dialogue de partage native ! Pour cela, il suffit désormais d'importer le package et d'appeler la share() fonction depuis notre application, modifions donc le src/app/app.component.ts comme ceci :
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'
});
}
}Comme mentionné précédemment, lors de l'installation de nouveaux plugins, nous devons effectuer une synchronisation puis redéployer l'application sur notre appareil. Pour ce faire, lancez la commande suivante :
npx cap syncUne fois le bouton pressé, vous pourrez admirer le superbe dialogue de partage natif en action !
Ensuite, vous pouvez rendre l'application plus native sur iOS et Android grâce à la navigation et aux transitions Capgo, et corriger les problèmes de mise en page iOS courants qui causent des débordements horizontaux ou des safe areas rognées.
Une interface native avec Capgo Native Navigation et Transitions
Je travaille depuis des années avec Ionic pour compiler des applications multiplateformes, mais l'intégrer à Angular est laborieux et rarement rentable si vous utilisez déjà Tailwind CSS.
Pour un rendu mobile natif dans une application Angular + Capacitor, utilisez les plugins Capgo plutôt que des kits UI web comme Konsta UI :
- @capgo/capacitor-native-navigation — une navbar native, une barre d'onglets Liquid Glass sur iOS et un style de barre d'onglets floutée sur Android. Votre routeur Angular gère l'état des routes ; le plugin gère l'interface native.
- @capgo/capacitor-transitions — des transitions de page de style Ionic et le retour par balayage (edge swipe) 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 syncConfigurez la navigation native avec le mode CSS inset pour 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',
},
});Affichez une barre d'onglets Liquid Glass (iOS utilise le rendu système ; Android utilise un fond de WebView flouté) :
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-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant la navigation. Ne dupliquez pas les headers ou footers web lorsque la navigation native gère ces surfaces.
Consultez les guides complets : Utiliser @capgo/capacitor-native-navigation et Utiliser @capgo/capacitor-transitions.
Safe areas avec Tailwind
Pour les safe areas de l'appareil avec Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié en tant que tailwind-capacitor sur npm). Cela permet safe-areas utilitaires et autres plugins Tailwind compatibles avec Capacitor :
bun add -D tailwind-capacitorDans src/styles.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez des utilitaires tels que pt-safe, pb-safe, et px-safe au lieu de les saupoudrer env(safe-area-inset-*) à la main. Le projet est en développement actif — s'il manque quelque chose pour votre configuration Angular, ouvrez une PR sur GitHub.
Corriger les problèmes de mise en page iOS (viewport, safe area et overflow horizontal)
Si le contenu semble coupé, décalé ou s'il défile horizontalement sur iOS, ajoutez plus de overflow-x: hidden ou ajuster seulement la balise viewport ne résout généralement pas le problème. Passez ces vérifications en revue dans l'ordre.
Assurez-vous que la balise meta viewport est correctement appliquée
Dans src/index.html, configurez la balise meta viewport dans <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérez la safe area iOS depuis un seul wrapper racine
Créez un shell d'application unique et appliquez le padding de la safe area à cet endroit — 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 dans .app-shell. La duplication du padding safe-area dans les headers, les modales et les wrappers de layout donne souvent l'impression que l'UI est tronquée ou trop grande.
Avec @capgo/tailwind-capacitor, vous pouvez appliquer le même padding avec des utilitaires comme pt-safe pb-safe px-safe sur ce shell unique.
Configurez Capacitor iOS contentInset à never en premier
Dans capacitor.config.ts, préférez l'inset natif désactivé et laissez le CSS (ou celui de Native Navigation contentInsetMode: 'css') gérer la safe area :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'www',
ios: {
contentInset: 'never',
},
};Mélanger l'inset de contenu automatique de Capacitor avec le CSS env(safe-area-inset-*) le padding est une cause fréquente de double espacement.
Identifiez l'élément réel qui déborde
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur fixe en pixels, ou un large min-width.
Dans Safari Web Inspector, lancez :
[...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 Tailwind, remplacez w-screen avec w-full quand c'est possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, un padding safe-area dupliqué ou un conteneur à largeur fixe — et non pas de la balise meta viewport elle-même.
Conclusion
Capacitor est une excellente option pour créer des applications natives à partir d'un projet web existant, offrant un moyen simple de partager code et de maintenir une interface cohérente.
Et avec l'ajout de Capgo, il est encore plus facile d'ajouter des live updates à votre application, garantissant que vos utilisateurs accèdent toujours aux dernières fonctionnalités et corrections de bugs.
Si vous souhaitez apprendre à ajouter Capgo à votre application Angular, consultez l'article suivant :
Continuer avec : Créer des applications mobiles avec Angular et Capacitor
Si vous utilisez Créer des applications mobiles avec Angular et Capacitor pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-live-activities pour la fonctionnalité native de la page Utiliser @capgo/capacitor-live-activities, @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities , Utiliser @capgo/capacitor-video-player pour la capacité native dans l'utilisation de @capgo/capacitor-video-player, @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player, et Utiliser @capgo/capacitor-native-navigation pour la capacité native dans l'utilisation de @capgo/capacitor-native-navigation.
