Cet article 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 permet une 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 : Présentation
CapacitorJS est un jeu de hasard. Il peut intégrer de manière fluide avec 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
Alors, 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 sur cela dans un moment. Tout d'abord, comprenons comment intégrer Capacitor dans notre application React.
Intégrer Capacitor dans votre application React.js
Après les étapes d'installation initiales, qui peuvent être un peu détaillées, mettre à jour 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'ensemble 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 androidLa ios et android les dossiers sont maintenant présents dans votre projet React.js.
Pour accéder au projet Android ultérieurement, installez Android Studio. Pour iOS, vous avez besoin d'un Mac et devriez installer Xcode.
Ensuite, mettez à jour le webDir dans votre capacitor.config.json comme indiqué ci-dessous :
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Exécutez la commande de construction et synchronisez votre projet avec Capacitor :
npm run build
npx cap syncLa npm run build la 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.
alignera le web __CAPGO_KEEP_0__ dans les endroits précis des plateformes natives afin qu'ils puissent être exécutés dans une application.
Créer et Déployer Vos Applications Natives
Construire et déployer vos applications natives Xcodeet les applications Android nécessitent , et les applications Android nécessitent. If you plan to distribute your app on the app store, you must enroll in the Apple Developer Program for iOS and the Google Play Console for Android.
Le Capacitor CLI facilite la création de projets natives.
npx cap open ios
npx cap open androidUne fois vos projets natifs configurés, déployer votre application sur un appareil connecté est un processus simple et direct.
Pour Android Studio, attendez que tout soit chargé 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, appuyez simplement sur la touche 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 disposent généralement d'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 la mise à jour en temps réel 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 un Mac, vous pouvez le faire en exécutant ipconfig getifaddr en0 dans le terminal. Sur Windows, exécutez ipconfig et recherchez 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;Assurez-vous d'utiliser l'adresse IP et le port exacts. Exécutez npx cap copy pour appliquer ces modifications à notre projet natif.
Une fois votre application déployée une fois de plus à l'aide d'Android Studio ou Xcode, toutes les modifications apportées à votre application React seront automatiquement rechargées et affichées dans votre application !
Notez cependant 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.
Utilisation des Capacitor Plugins
Commençons par jeter un coup d'œil sur la façon de utiliser un Capacitor plugin. Installons un simple, le plugin de partage, qui déclenche le dialogue de partage natif :
npm i @capacitor/sharePour l'utiliser, importez le package et appelez la méthode correspondante. share() fonction de notre application. Pensez à la App.js:
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;Après l'installation d'un nouveau plugin, n'oubliez pas de synchroniser à nouveau votre projet React. npx cap sync.
Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec Capgo de navigation et de 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 natives
J'ai travaillé pendant des années avec Ionic pour construire des applications cross-plateformes, mais l'intégration avec React est hacky et rarement justifiée lorsque vous avez déjà Tailwind CSS.
Pour un sentiment mobile natif dans une application React + Capacitor , utilisez les plugins Capgo au lieu des kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-navigation native native — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Votre routeur React 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 de la vue, sans adopter l'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',
},
});Afficher une barre d'onglets Liquid Glass (iOS utilise la mise en page système ; Android utilise un arrière-plan flou 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}`);
});Add native page transitions in your app shell:
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-pageet cap-contentet 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 : Utiliser @capgo/capacitor-navigation-native et Utiliser @capgo/capacitor-transitions.
Aires sûres avec Tailwind
Pour les aires sûres du dispositif dans Tailwind CSS, utilisez @capgo/tailwind-capacitor paru sous le titre tailwind-capacitor sur npm. Il fournit safe-areas des utilitaires et d'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 utilitaires comme 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 React, 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 déroulable 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
Ajoutez le tag de métadonnées de vueport dans index.html à l'intérieur <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérez la zone de sécurité iOS à partir d'un seul wrapper racine
Créez un noyau d'application unique et appliquez-y une marge de zone de sécurité — 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);
}Entourer tout le contenu de la page .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.
Avec @capgo/tailwind-capacitor, vous pouvez exprimer le même padding avec des utilitaires comme pt-safe pb-safe px-safe sur cette seule coquille.
Définissez Capacitor iOS contentInset à never premier
Dans capacitor.config.ts, préférez l'inset natif désactivé et laissez CSS (ou la navigation native) contentInsetMode: 'css') prendre en charge la zone de sécurité :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Mélanger les inset automatiques de contenu de Capacitor avec CSS env(safe-area-inset-*) est une cause courante de double espacement.
Trouvez l'élément qui déborde vraiment
Le coupable habituel est un élément utilisant 100vwTailwind w-screenune largeur fixe en pixels, ou une min-width.
In 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 avec w-full lorsque possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, des margeures de zone de sécurité dupliquées ou un conteneur de largeur fixe — pas de la balise meta viewport elle-même.
Conclusion
Capacitor offre un moyen fluide de créer des applications natives en fonction d'un projet web existant, offrant une façon simple de partager code et d'avoir une interface utilisateur cohérente.
Merci à des technologies comme Capacitor, la création d'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 de accélérer votre processus de développement d'applications. inscrivez-vous à un compte gratuit Aujourd'hui.
Keep going from Building Mobile Apps with Pure React.js and Capacitor
Si vous utilisez Building Mobile Apps with Pure React.js and Capacitor pour planifier le comportement des médias et de l'interface native, connectez-l’avec Utilisation de @capgo/capacitor-activités en direct pour la capacité native dans l'utilisation de @capgo/capacitor-activités en direct. @capgo/capacitor-activités en direct pour les détails d'implémentation dans @capgo/capacitor-activités en direct Utilisation de @capgo/capacitor-player vidéo pour la capacité native dans l'utilisation de @capgo/capacitor-player vidéo @capgo/capacitor-joueur-de-videos pour les détails d'implémentation dans @capgo/capacitor-video-player, et En utilisant @capgo/capacitor-native-navigation pour la capacité native dans En utilisant @capgo/capacitor-native-navigation.
