Cette tutrice vous guidera dans la création d'une application mobile à l'aide de React et Capacitor. À la fin, vous saurez comment transformer une application web React.js en une application mobile native avec Capacitor, et ajouter un sentiment natif avec Capgo Navigation et Transitions natives.
Capacitor facilite la transformation facile de votre application web React.js en une application mobile native, nécessitant aucune modification substantielle ou apprentissage de nouvelles stratégies comme React Native.
Le processus implique quelques étapes simples, et avant de le savoir, votre application React.js sera une application mobile fonctionnelle. Alors, restez avec nous tout au long de ce voyage.
Capacitor Vue d'ensemble
CapacitorJS est un changement de jeu. Il peut intégrer de manière fluide à tout projet web et envelopper votre application dans une vue web native tout en générant le projet Xcode et Android Studio natif. De plus, grâce à ses plugins, vous pouvez accéder aux fonctionnalités de dispositif natif comme la caméra via un pont JS.
Capacitor offre une méthode directe pour créer une application mobile native sans aucune difficulté ou courbe d'apprentissage raide. Sa simple API et sa fonctionnalité épurée rendent facile son incorporation dans votre projet.
Configuration de votre application React.js
Allons-y pour la méthode la plus simple pour initier une application React. Nous utiliserons le gestionnaire de packages npm pour créer une nouvelle application React :
npx create-react-app my-appPour transformer notre projet en application mobile native, un export de notre application est requis.
Nous reviendrons à cela dans un moment. Tout d'abord, comprenons comment intégrer Capacitor dans notre application React.
Intégrer Capacitor dans votre application React.js
Les étapes d'initialisation peuvent être un peu détaillées, mais après cela, la mise à jour de votre enveloppe d'application native devient aussi simple que de lancer un sync commande.
Tout d'abord, nous installerons le Capacitor CLI en tant que dépendance de développement et le configurerons dans notre projet. Lors de la configuration, acceptez les valeurs par défaut pour le nom et l'ID de l'application en appuyant sur « entrer ».
Ensuite, nous installerons le package de base et les packages pertinents pour les plateformes iOS et Android.
Enfin, nous ajouterons 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 React 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 androidLe répertoire iOS et Android
sont maintenant présents dans votre projet React.js. Android Studio Pour iOS, vous avez besoin d'un Mac et devriez installer Xcode.
Ensuite, mettez à jour le webDir dans votre capacitor.config.json fichier comme indiqué ci-dessous :
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Exécutez la commande de build et synchronisez votre projet avec Capacitor:
npm run build
npx cap sync La npm run build commande construira votre projet React.js, tandis que npx cap sync alignera le web code dans les endroits précis des plateformes natives afin qu'ils puissent être exécutés dans une application.
Now, with a little luck and no errors, your React.js app should be ready for launch on a device!
Construire et Déployer Vos Applications Natives
Le développement d'applications iOS nécessite Xcode, et les applications Android nécessitent Android Studio. Si vous prévoyez de distribuer votre application sur le magasin d'applications, vous devez vous inscrire au programme Apple Developer pour iOS et au Google Play Console pour Android.
Le Capacitor CLI simplifie le processus d'ouverture de tous les projets natifs :
npx cap open ios
npx cap open androidUne fois que vos projets natifs sont configurés, le déploiement de votre application sur un appareil connecté est un processus simple.
Pour Android Studio, attendez que tout soit chargé et puis déployez votre application sur un appareil connecté.
Pour Xcode, établissez votre compte de signature pour déployer votre application sur un appareil réel au lieu du simulateur. Une fois cela fait, simplement appuyez sur 'play' pour exécuter l'application sur votre appareil connecté, que vous pouvez choisir en haut.
Si tout s'est bien passé, vous aurez converti votre application web React.js en application mobile native !
Capacitor Live Reload
Les frameworks de développement modernes viennent généralement avec un rechargement chaud, et heureusement, vous pouvez en avoir le même avec Capacitor mais sur votre appareil mobile!
Vous pouvez rendre votre application hébergée localement accessible avec un rechargement en direct sur votre réseau en faisant en sorte que l'application Capacitor charge le contenu à partir d'une URL spécifique.
Tout d'abord, déterminez votre adresse IP locale. Sur Mac, vous pouvez le faire en exécutant ipconfig getifaddr en0 dans le terminal. Sur Windows, exécutez ipconfig et cherchez l'adresse IPv4.
Après cela, instruisez Capacitor pour charger l'application directement depuis le serveur en ajoutant un autre paramètre à votre capacitor.config.ts fichier :
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'build',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Soyez sûr d'utiliser l'adresse IP et le port exacts. Exécutez npx cap copy pour appliquer ces modifications à notre projet natif.
Lorsque vous déployez votre application une fois de plus à l'aide d'Android Studio ou Xcode, les modifications de votre application React seront automatiquement rechargées et affichées dans votre application !
N'oubliez pas que si de nouveaux plugins sont installés, comme la caméra, cela nécessite une reconstruction de votre projet natif. C'est parce que les fichiers natifs auront changé et ne peuvent pas être mis à jour en temps réel.
Utiliser les Capacitor Plugins
Prenez un moment pour voir comment utiliser un Capacitor plugin. Installons un simple, le plugin de partage, qui affiche le dialogue de partage natif :
npm i @capacitor/sharePour l'utiliser, importez le package et appelez la fonction respective de notre application. Considérez le share() App.js Après l'installation d'un nouveau plugin, n'oubliez pas de synchroniser votre projet React à nouveau en utilisant:
import { Share } from '@capacitor/share';
function ShareButton() {
const share = async () => {
await Share.share({
title: 'React App',
text: 'Visit this React App',
url: 'http://localhost:3000',
dialogTitle: 'Share with...'
});
};
return (
<button onClick={share}>
Share
</button>
);
}
export default ShareButton;Vous pouvez ensuite rendre votre application plus native sur iOS et Android avec les __CAPGO_KEEP_0__ navigation et 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. npx cap sync.
UI native avec les Capgo Navigation et Transitions Native
Native-feeling UI with Capgo Native Navigation and Transitions
J'ai travaillé pendant des années avec __CAPGO_KEEP_0__ Ionic pour construire des applications cross-plateformes, mais intégrer Ionic avec React est fastidieux et rarement justifié lorsque vous avez déjà Tailwind CSS.
Pour un sentiment mobile natif dans une application React + Capacitor , utilisez les Capgo plugins au lieu des kits UI web uniquement comme 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 React conserve l'état des routes ; le plugin gère la barre de chrome native.
- @capgo/capacitor-transitions — transitions de page Ionic et iOS swipe-back sur l'arrière de la couche WebView, sans adopter la UI 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',
},
});Affichez une barre de tabs Liquid Glass (iOS utilise la mise en page système ; Android utilise un arrière-plan flou de la couche WebView) :
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 }) => {
navigate(`/${id}`);
});Ajoutez les transitions de page natives dans votre coquille d'application :
import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });
export function AppShell() {
const navigate = useNavigate();
const outletRef = useRef<HTMLElement>(null);
useEffect(() => {
if (outletRef.current) {
setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
}
}, []);
const openSettings = () => {
setDirection('forward');
navigate('/settings');
};
return <cap-router-outlet ref={outletRef}>{/* routes */}</cap-router-outlet>;
}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.
Voir les guides complets : Utilisation de @capgo/capacitor-navigation-native et Utilisation de @capgo/capacitor-transitions.
Aires sûres avec Tailwind
Pour les zones sûres des appareils dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous le nom de tailwind-capacitor sur npm). Il fournit safe-areas outils et autres plugins Tailwind compatibles avec Capacitor :
bun add -D tailwind-capacitorDans src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez des outils comme pt-safe, pb-safe, et px-safe au lieu de les ajouter env(safe-area-inset-*) manuellement. Le projet est actuellement développé — si quelque chose manque pour votre configuration React, ouvre une demande de tirage à part sur GitHub.
Résoudre les problèmes de disposition iOS (Vueport, Zone de sécurité, et Débordement horizontal)
Si le contenu semble coupé, décalé ou déroulable horizontalement sur iOS, ajouter plus overflow-x: hidden ou ajuster la balise de vueport seule ne résout généralement pas le problème. Travaillez à travers ces vérifications dans l'ordre.
Assurez-vous que la balise meta viewport soit appliquée correctement
Ajoutez la balise meta viewport dans index.html à l'intérieur <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérez l'espace sûr d'iOS à partir d'un seul enveloppe racine
Créez un seul coquille d'application et appliquez-y la mise en forme de l'espace sûr — pas dans plusieurs composants imbriqués :
html,
body,
#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-shellLa mise en forme de l'espace sûr répétée dans les en-têtes, les modales et les enveloppes de disposition peut rendre l'interface utilisateur 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 To never Premier
En capacitor.config.ts, préférez l'insérer natif désactivé et laissez CSS (ou la navigation native) gérer l'espace sûr : contentInsetMode: 'css'Mélanger les marges automatiques de __CAPGO_KEEP_0__ avec CSS
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Trouvez l'élément qui déborde vraiment
Le coupable habituel est un élément utilisant
, Tailwind 100vw, une largeur fixe en pixels, ou un w-screenEn inspecteur Web Safari, exécutez : min-width.
In Safari Web Inspector, run:
[...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,
}));With Tailwind, remplacez w-screen par w-full lorsque possible. Beaucoup d'issues de débordement horizontal proviennent de 100vw / w-screen, de la mise en forme de la zone de sécurité dupliquée, ou d'un conteneur de largeur fixe — et non de la balise meta de la vue portative elle-même.
Conclusion
Capacitor offre un moyen fluide de créer des applications natives basées sur un projet web existant, fournissant un moyen simple de partager code et d'avoir une interface utilisateur cohérente.
Merci aux technologies comme Capacitor, la création de applications mobiles à partir d'applications web React.js a jamais été aussi facile. Portez vos compétences en développement web à un niveau supérieur en créant des applications mobiles natives impressionnantes. Bon codage !
Pour en savoir plus sur la façon dont vous pouvez accélérer votre processus de développement d'applications, inscrivez-vous à un compte gratuit aujourd'hui.
Continuez à partir de Building Mobile Apps with Pure React.js et Capacitor
Si vous utilisez Créer des applications mobiles avec Pure React.js et Capacitor pour planifier le comportement de médias et d'interface natifs, et les connecter avec Utilisation de @capgo/capacitor-activités-en-ligne pour la capacité native dans Utilisation de @capgo/capacitor-activités-en-ligne, @capgo/capacitor-activités-en-ligne pour le détail d'implémentation dans @capgo/capacitor-activités-en-ligne, 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.
