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 des modifications importantes ou l'apprentissage d'une nouvelle compétence comme React Native.
Avec juste 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 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 périphérique native comme la caméra via un pont JS.
Avec Capacitor, vous obtenez une application mobile native fantastique sans aucune configuration compliquée ou courbe d'apprentissage abrupte. Sa mince 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 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 » lors de la demande de 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 buildVous devriez pouvoir reconnaître un projet récent. dist dossier à la racine de votre projet.
Ce dossier sera utilisé par Capacitor plus tard, mais pour l'instant, nous devons le configurer correctement.
Intégrer 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 une commande unique. sync command.
Tout d'abord, nous pouvons installer le Capacitor CLI as a development dependency, and then set it up within our project. During the setup, you can press “enter” to accept the default values for name and bundle ID.
Finalement, nous pouvons ajouter les plateformes, et __CAPGO_KEEP_0__ créera des dossiers pour chaque plateforme à la racine de notre projet :
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 nouvelles et and 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 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 webDirlaquelle doit pointer vers le résultat de votre commande de build. Actuellement, elle est inexacte.
context : fragment de texte HTML d'une chaîne de Capgo plus longue (clé parente `solutions_cordova_to_capacitor_ai_step2_body`). Page/zone : page de marketing de solutions Capgo. Rôle : phrase de copie de site Web. Vu dans : page solutions/cordova-to-capacitor-ai.astro. Clé de message `solutions_cordova_to_capacitor_ai_step2_body` (Solutions Cordova To Capacitor Ai Step2 Body). capacitor.config.json le fichier et mettez à jour 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 mise en page 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.
Lorsque vous installez un nouveau plugin, le commandement de synchronisation peut également mettre à jour les plateformes natives et installer des plugins. Capacitor plugins il est temps de relancer npx cap sync again.
without noticing, you are now actually done, so let’s see the app on a device!
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 développeur). Ensuite, vous pouvez simplement appuyer sur la touche de lecture 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 une méthode plus rapide pour procéder à cela pendant le développement…
Capacitor Live Reload
À ce stade, vous êtes probablement habitué à avoir la mise à jour en temps réel 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'efforts !
Activer l'accès à votre application hébergée localement avec rechargement en direct sur votre réseau en faisant en sorte que l'application Capacitor charge 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 :
ipconfigRecherchez ensuite l'adresse IPv4.
Nous pouvons instruire Capacitor pour 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'adresse IP et le port corrects, j'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 à syncmais cela ne fonctionnera que copiez les modifications apportées au dossier web and configuration, without updating the native project.
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 par défaut d'Angular à des fins de démonstration.
Utilisation des plugins Capacitor
Examinons 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/shareRien de particulier n'est fait avec le plugin de partageMais cela affiche quand même le dialogue de partage natif ! Pour cela, il suffit maintenant d'importer le package et d'appeler la méthode correspondante. share() function de notre application, donc changeons donc le src/app/app.component.ts à cela :
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 opération de synchronisation puis redéployer l'application sur notre appareil. Pour ce faire, exécutez la commande suivante :
npx cap syncAprès avoir cliqué sur le bouton, vous pouvez voir le dialogue de partage natif en action !
Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec des Capgo de navigation et des transitions, et corriger les problèmes de mise en page iOS courants qui entraînent un débordement horizontal ou des zones de sécurité coupées.
UI native avec Capgo de navigation et de transitions Native
J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais intégrer cela 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 plugins Capgo au lieu des kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-navigation native — barre de navigation native, barre de Liquid Glass 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 gère la barre de chrome native.
- @capgo/capacitor-transitions — transitions de page Ionic et iOS swipe-back sur l'arrière, sans adopter l'interface utilisateur 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',
},
});Afficher une barre d'onglets Liquid Glass (iOS utilise la mise en page système ; Android utilise un arrière-plan flou 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 si la navigation native les gère déjà.
Voir les guides complets : Utilisation de @capgo/capacitor-native-navigation And Utiliser @capgo/capacitor-transitions.
Zones de sécurité avec Tailwind
For device safe areas in Tailwind CSS, use @capgo/tailwind-capacitor paru sur __CAPGO_KEEP_0__ tailwind-capacitor Cela s'applique à npm). Il fournit safe-areas outils et autres plugins Tailwind compatibles avec Capacitor :
bun add -D tailwind-capacitorIn 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, and px-safe au lieu de répandre env(safe-area-inset-*) par votre propre main. Le projet est actuellement développé — si quelque chose manque pour votre configuration Angular, ouvrir un 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.
Assurez-vous que le tag de métadonnées de vueport est appliqué correctement
In 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 un noyau d'application unique et appliquez une marge de zone de sécurité là — 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);
}Wrap all page content inside .app-shellLes marges de sécurité dupliquées dans les en-têtes, les modaux et les enveloppes de mise en page rendent souvent l'interface utilisateur coupée ou trop grande.
With @capgo/tailwind-capacitor, vous pouvez exprimer la même marge avec des utilitaires comme pt-safe pb-safe px-safe on ce seul shell.
Fixez Capacitor iOS contentInset à never first
premier capacitor.config.tspréférez l'insérer nativement désactivé et laissez CSS (ou la navigation native) contentInsetMode: 'css'Propriétaire de la zone de sécurité :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'www',
ios: {
contentInset: 'never',
},
};Mélanger les marges automatiques de contenu de Capacitor avec CSS env(safe-area-inset-*) l'espace de padding est une cause courante de double espace.
Trouvez l'élément qui déborde vraiment
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur de pixels fixe, ou une large min-width.
Inpecteur Web Safari, 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 débordement horizontal proviennent de 100vw / w-screenPas de padding de zone de sécurité dupliquée, ni d'un conteneur à largeur fixe — pas de la balise meta viewport 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 CapgoVous pouvez même ajouter des mises à jour en direct à 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 des médias et de l'interface native, connectez-l’avec Utiliser @capgo/capacitor-activités-en-vive pour la capacité native dans Utiliser @capgo/capacitor-activités-en-vive @capgo/capacitor-activités-en-vive pour le détail d'implémentation dans @capgo/capacitor-activités-en-vive Utiliser @capgo/capacitor-lecteur-de-videos pour la capacité native dans l'utilisation de @capgo/capacitor-video-player, @capgo/capacitor-joueur-de-videos pour le détail d'implémentation dans @capgo/capacitor-video-player, et l'utilisation de @capgo/capacitor-native-navigation pour la capacité native dans l'utilisation de @capgo/capacitor-native-navigation.
