Dans ce tutoriel, nous allons commencer avec une nouvelle application Angular et passer dans le monde des applications mobiles natives en utilisant __CAPGO_KEEP_0__. Vous pouvez également ajouter __CAPGO_KEEP_1__ de la navigation et des transitions natives pour un sentiment d'application mobile native, et utiliser tailwind-__CAPGO_KEEP_2__ pour les zones de sécurité. 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.
Ce tutoriel vous guidera tout au long du processus, en commençant par une nouvelle application Angular et en incorporant ensuite __CAPGO_KEEP_0__ pour passer dans le monde des applications mobiles natives. Vous pouvez également utiliser __CAPGO_KEEP_1__ de la navigation et des transitions natives, ainsi que tailwind-__CAPGO_KEEP_2__ pour les zones de sécurité.
This tutorial will guide you through the process, starting with a new Angular app and then incorporating Capacitor to move into the realm of native mobile apps. You can also use Capgo Native Navigation, Transitions, and tailwind-capacitor for safe areas.
About Capacitor
Martin Donadieu
With Capacitor, vous obtenez une application mobile native fantastique sans aucune mise en place compliquée ou courbe d'apprentissage raide. Sa mince API et sa fonctionnalité épurée rendent l'intégration dans votre projet un jeu d'enfant. Faites-moi confiance, vous serez impressionné par la facilité avec laquelle vous pouvez obtenir une application mobile native fonctionnelle 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-appSé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. Par conséquent, incluez un script simple dans votre package.json qui peut être utilisé pour construire et copier l'application Angular :
{
"scripts": {
// ...
"build": "ng build --prod"
}
}Après avoir exécuté la commande build, vous devriez être en mesure de repérer un nouveau dist dossier à la racine de votre projet.
Ce dossier sera utilisé par Capacitor plus tard, mais pour l'instant, nous devons le configurer correctement.
Ajouter Capacitor à votre application Angular
Pour emballer toute application web dans un conteneur mobile natif, nous devons suivre quelques étapes initiales, mais ensuite, c'est aussi simple que d'exécuter un seul sync commande.
Tout d'abord, nous pouvons installer le Capacitor CLI en tant que dépendance de développement, et puis configurer cela dans notre projet. Lors de la configuration, vous pouvez appuyer sur “entrer” pour accepter les valeurs par défaut pour le nom et l'ID de l'application.
Ensuite, nous devons installer le package de base 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 être en mesure d'observer de nouveaux ios et android les dossiers de 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 fichier capacitor.config.ts dans votre projet, qui contient certaines configurations fondamentales Capacitor utilisées lors de la synchronisation. La seule chose dont vous devez vous soucier est le webDir, qui doit pointer vers le résultat de votre commande de build. Actuellement, il est inexact.
Pour remédier à cela, ouvrez le capacitor.config.json fichier et mettez à jour la webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Vous pouvez essayer en exécutant les commandes suivantes :
npm run build
npx cap syncLa première commande npm run build construira simplement votre projet Angular et copiera la construction statique, tandis que la deuxième commande npx cap sync syncra toutes les web code dans les bons endroits des plateformes natives afin qu'elles puissent être affichées dans une application.
En outre, la commande sync peut mettre à jour les plateformes natives et installer des plugins, donc lorsque vous installez un nouveau Capacitor plugins il est temps de relancer npx cap sync encore.
Vous n'avez même pas réalisé que vous étiez fini, 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 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 projets natifs :
npx cap open ios
npx cap open androidUne fois que vous avez configuré vos projets natifs, déployer votre application sur un appareil connecté est facile. Dans Android Studio, vous n'avez qu'à attendre que tout soit prêt, et vous pouvez déployer votre application sur un appareil connecté sans modifier les paramètres. Voici un exemple :
Dans Xcode, vous devez configurer votre compte de signature pour déployer votre application sur un appareil réel au lieu du simulateur. Si vous n'avez pas fait cela avant, Xcode vous guide à travers le processus (mais encore une fois, vous devez être inscrit au programme de développement). Ensuite, vous pouvez simplement appuyer sur jouer pour exécuter l'application sur votre appareil connecté, que vous pouvez sélectionner en haut. Voici un exemple :
Félicitations ! Vous avez réussi à déployer votre application web Angular sur un appareil mobile. Voici un exemple :
Mais attendez, il existe également un moyen plus rapide de procéder pendant le développement…
Capacitor Live Reload
À ce stade, vous êtes probablement habitué à avoir un rechargement chaud avec tous les frameworks modernes, et la bonne nouvelle est que vous pouvez avoir la même fonctionnalité sur un appareil mobile avec un minimum d'effort !
Activer l'accès à votre application hébergée localement avec rechargement en direct sur votre réseau en ayant l'application Capacitor charger le contenu à partir de l'URL spécifique.
La première étape 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 en0On Windows, exécutez :
ipconfigAlors, recherchez l'adresse IPv4.
On peut instruire Capacitor pour charger l'application directement du serveur en ajoutant une autre entrée à notre capacitor.config.ts dossier :
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'il vous plaît assurez-vous d'utiliser l'adresse IP et le port correctsJ'ai utilisé le port par défaut d'Angular dans cet exemple.
Maintenant, nous pouvons appliquer ces modifications en les copiant vers notre projet natif :
npx cap copyLa copy commande est similaire à sync, mais elle ne copiera que 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. Une fois cela fait, si vous modifiez quelque chose dans votre application Angular, l'application se rechargera automatiquement et affichera les modifications !
Notez que si vous installez de nouveaux plugins comme la caméra, il est toujours nécessaire de reconstruire votre projet natif. Cela est dû au fait 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 __CAPGO_KEEP_0__ ci-dessus montre le port par défaut Angular pour des raisons de démonstration.
Utilisation des plugins code
É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 :
Let’s take a look at how to use a Capacitor plugin in action, which we’ve mentioned a few times before. To do this, we can install a fairly simple plugin by running:
npm i @capacitor/shareplugin de partage mais il montre quand même le dialogue de partage natif ! Pour cela, nous n'avons désormais besoin que d'importer le package et d'appeler la fonction correspondante de notre application, donc changeons donc lefunction from our app, so let’s change the share() function from our app, so let’s change the As 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 effectuer cela, exécutez la commande suivante : Après avoir cliqué sur le bouton, vous pouvez voir le dialogue de partage natif en action !
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'
});
}
}Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec des __CAPGO_KEEP_0__ de navigation et des transitions, 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.
npx cap syncInterface utilisateur ressemblant à une interface native avec __CAPGO_KEEP_0__ de navigation et de transitions natives
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.
Native-feeling UI with Capgo Native Navigation and Transitions
pour construire des applications cross-platform, mais l'intégration avec Angular est hacky et rarement valable lorsque vous avez déjà Tailwind CSS Pour un sentiment mobile natif dans une application Angular + __CAPGO_KEEP_0__ , utilisez les plugins __CAPGO_KEEP_1__ au lieu des kits UI web uniquement comme Konsta UI : @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation.
For a native mobile feel in an Angular + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- @capgo/capacitor-native-navigation — barre de navigation native, Liquid Glass barre de tabs sur iOS, et un style de barre de tabs flou sur Android. Votre routeur Angular conserve l'état des routes ; le plugin possède la barre d'outils native.
- @capgo/capacitor-transitions — transitions de pages à la manière d'Ionic et un retour arrière par balayage sur l'écran sur iOS, sans adopter l'interface utilisateur d'Ionic.
Installez les deux :
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigurez la navigation native avec le mode d'insertion CSS 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',
},
});Rendre une barre de tabs en verre liquide (iOS utilise la mise en page système ; Android utilise un fond 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-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant de naviguer. N'ajoutez pas de titres ou de pieds de page web lorsque la navigation native possède ces surfaces.
Consultez les guides complets : En utilisant @capgo/capacitor-navigation-native et En utilisant @capgo/capacitor-transitions.
Les zones de sécurité avec Tailwind
Pour les zones de sécurité des appareils dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas des utilitaires et d'autres plugins de Tailwind compatibles avec Capacitor:
bun add -D tailwind-capacitorEn src/styles.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez des utilitaires comme pt-safe, pb-safe, et px-safe au lieu de les répandre env(safe-area-inset-*) par la main. Le projet est actuellement développé — si quelque chose manque pour votre configuration Angular, ouvrir 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 overflow-x: hidden ou ajuster seul le tag de vueport ne suffit généralement pas. Travaillez à travers ces vérifications dans l'ordre.
Vérifiez que le tag de métadonnées de vueport est appliqué correctement
Dans src/index.html, définissez le tag de métadonnées de vueport dans <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérer la zone de sécurité iOS à partir d'un seul wrapper racine
Créez une coquille d'application unique et appliquez la mise en page de la zone de sécurité là-bas — 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-shell. La mise en forme de la zone de sécurité dupliquée dans les en-têtes, les modaux et les enveloppes de mise en page peut souvent donner l'impression que l'interface utilisateur est coupée ou trop grande.
Avec @capgo/tailwind-capacitor, vous pouvez exprimer la même mise en forme avec des utilitaires comme pt-safe pb-safe px-safe sur cette seule coquille.
Définissez Capacitor iOS contentInset sur never premier
En capacitor.config.ts, préférez la mise en forme native de la zone de sécurité désactivée et laissez CSS (ou la navigation native) gérer la zone de sécurité : contentInsetMode: 'css'Mélanger les mise en forme automatique de contenu de __CAPGO_KEEP_0__ avec CSS
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-*) padding est une cause courante de double espace.
Trouvez l'élément en surflot qui est réel
Le coupable habituel est un élément utilisant 100vwTailwind w-screenune largeur de pixels fixe, ou un min-width.
En Safari Web Inspector, exécutez :
[...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 par w-full lorsque possible. De nombreux problèmes de surflot horizontal proviennent de 100vw / w-screenla duplication de la marge de sécurité de l'aire sûre, ou d'un conteneur à largeur fixe — et non de la balise meta de la zone de vue elle-même.
Conclusion
Capacitor est une excellente option pour créer des applications natives basées sur 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 encore plus facile d'ajouter des mises à jour en temps réel à votre application, vous assurant que vos utilisateurs ont 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 Building Mobile Apps with Angular et Capacitor
Si vous utilisez Building Mobile Apps with Angular et Capacitor pour planifier le comportement de médias et d'interface natifs, connectez-le à Utiliser @capgo/capacitor-activités-en-vivre pour la capacité native dans Utiliser @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, Utiliser @capgo/capacitor-player vidéo natif pour la capacité native dans Utiliser @capgo/capacitor-player vidéo natif, @capgo/capacitor-player vidéo natif pour le détail d'implémentation dans @capgo/capacitor-player vidéo natif, et Utiliser @capgo/capacitor-navigation native pour la capacité native dans Utiliser @capgo/capacitor-navigation native.
