In ce tutoriel, nous allons commencer par une nouvelle React app et passer à la mise en œuvre mobile native en utilisant Capacitor. Vous pouvez également ajouter Capgo Native Navigation et Transitions pour une expérience mobile native, et utiliser tailwind-capacitor pour les zones de sécurité.
Capacitor vous permet de convertir facilement votre application web React en une application mobile native sans modifications importantes ou apprentissage d'une nouvelle compétence comme React Native.
Avec juste quelques étapes simples, la plupart des applications React peuvent être transformées en applications mobiles.
Ce tutoriel vous guidera tout au long du processus, en commençant par une nouvelle application React et en incorporant ensuite Capacitor pour passer 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 changement de jeu ! Vous pouvez l'intégrer facilement dans tout projet web, et il enveloppera votre application dans une vue web native, générant le projet Xcode et Android Studio natif pour vous. De plus, ses plugins fournissent un accès aux fonctionnalités de dispositif natif 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 raide. Sa structure API et sa fonctionnalité épurée en font une tâche de bricolage pour l'intégrer dans votre projet. Croyez-moi, vous serez impressionné par la facilité avec laquelle vous pouvez obtenir une application mobile native complète avec Capacitor !
Préparation de votre application React
Alors que plusieurs méthodes existent pour initier des applications React, allons pour la plus simple dans ce tutoriel qui fournit une application React vierge :
npx create-react-app my-appPour créer une application mobile native, nous avons besoin d'un export de notre projet. Par conséquent, ajoutons un script simple à notre package.json qui peut être utilisé pour construire et exporter le projet React :
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Vous pouvez maintenant exécuter npm run build sans vous soucier de rien, et vous devriez être en mesure de voir un dossier frais
Capacitor
Adding Capacitor to Your React App
Ce dossier sera utilisé par sync __CAPGO_KEEP_0__
Premièrement, nous pouvons installer le Capacitor CLI comme une dépendance de développement, et puis le configurer 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 avons besoin d’installer le package de base et les packages pertinents pour les plateformes iOS et Android.
Finalement, 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 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 androidÀ ce stade, vous devriez pouvoir observer de nouveaux ios dossiers context : Page/zone : Site de marketing Capgo. Rôle : Étiquette de navigation ou élément UI court. Vu dans : page trust.astro. Clé de message `and` (Et). dossiers
context : Page/zone : Site de marketing Capgo. Rôle : Étiquette de navigation ou élément UI court. Vu dans : page trust.astro. Clé de message `and` (Et).
android 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 webDircontext
qui doit pointer vers le résultat de votre commande de build. Actuellement, elle est inexacte. capacitor.config.json __CAPGO_KEEP_0__.config.json fichier et mettez à jour le fichier de configuration de votre projet. La seule chose dont vous devez vous soucier est le paramètre de configuration de votre projet, qui doit pointer vers le résultat de votre commande de build. Actuellement, il est inexact.:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Vous pouvez essayer cela en exécutant les commandes suivantes :
npm run build
npx cap syncLa première commande npm run build construira simplement votre projet React et exporter la construction statique.
Alors 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.
De plus, la commande de synchronisation pourrait 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 sans même vous en rendre compte, vous êtes maintenant effectivement terminé, alors voyons donc l'application sur un appareil !
Construire et déployer des applications natives
Pour développer des applications iOS, vous devez avoir
les 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 Apple Developer Program 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). Une fois cela fait, vous pouvez simplement appuyer sur 'play' 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 React sur un appareil mobile. Voici un exemple :
Attendez, il y a une façon plus rapide de faire 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 avoir la même fonctionnalité sur un appareil mobile avec un minimum d'efforts !
Activer l'accès à votre application hébergée localement avec mise à jour en temps réel 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 en0Sur Windows, exécutez :
ipconfigRecherchez ensuite l'adresse IPv4.
On peut instruire Capacitor à 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: 'out',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;Assurez-vous d'utiliser le bon IP et le port, j'ai utilisé le port React par défaut dans cet exemple.
Maintenant, nous pouvons appliquer ces modifications en les copiant vers notre projet natif :
npx cap copyLe 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. Après cela, si vous modifiez quelque chose dans votre application React,
l'application se rechargera automatiquement et affichera les modifications ! 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 React, 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 toujours 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 React par défaut pour 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/shareCe plugin n'a rien de spécial, mais il montre quand même le dialogue de partage natif ! Pour cela, nous n'avons besoin que d'importer le package et d'appeler la fonction de notre application. Modifions le src/App.js share() en le rendant ainsi : Comme 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 cela, exécutez la commande suivante : redeployer
import React from 'react';
import { Share } from '@capacitor/share';
function App() {
const share = async () => {
await Share.share({
title: 'Open Youtube',
text: 'Check new video on youtube',
url: 'https://www.youtube.com',
dialogTitle: 'Share with friends'
});
};
return (
<div>
<h1>Welcome to React and Capacitor!</h1>
<p>
<h2>Cool channel</h2>
<button onClick={() => share()}>Share now!</button>
</p>
</div>
);
}
export default App;l'application
npx cap syncAfter 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 la navigation et les transitions Capgo et résoudre 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 natif avec la navigation et les transitions Capgo Native
J'ai travaillé pendant des années avec Ionic pour créer des applications cross-platform, mais intégrer Ionic avec React est hacky et rarement valable 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-native-navigation — barre de navigation native, barre de Liquid Glass 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 --- Transition de page Ionic et iOS edge swipe-back dans la couche WebView, 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',
},
});Affichez une barre de tabs en verre liquide (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}`);
});Ajoutez des 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-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') context : fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `alternatives_cta_questions`). Page/zone : page de comparaison des alternatives de mise à jour en direct de Capacitor. Rôle : Paragraphe marketing ou juridique long. Voir dans : page alternatives.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `alternatives_cta_questions` (Questions de CTA alternatives). | Fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `appflow_cta_questions`). Page/zone : page de comparaison/migration de Appflow. Rôle : Paragraphe marketing ou juridique long. Voir dans : page ionic-appflow.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `appflow_cta_questions` (Questions de CTA Appflow). | Fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `capwesome_cta_questions`). Page/zone : page de comparaison de Capawesome. Rôle : Paragraphe marketing ou juridique long. Voir dans : page capwesome.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `capwesome_cta_questions` (Questions de CTA Capwesome). | Fragment de texte HTML d'une chaîne de dialogue Capgo plus longue (clé parente `consulting_faq_subtitle`). Page/zone : page de services de conseil. Rôle : Sous-titre ou tagline de section. Voir dans : page consulting.astro. Préservez les termes de produit et de marque Capgo ainsi que les termes de développeur exactement. Clé de message `consulting_faq_subtitle` (Sous-titre FAQ de conseil). | Page/zone : page de comparaison/migration de Appflow. Rôle : Étiquette de navigation ou élément de navigation court. Voir dans : page ionic-appflow.astro, page ionic-enterprise-plugins.astro, page solutions/ionic-enterprise-plugins.astro. Clé de message `appflow_plugins_or` (Appflow Plugins ou).
avant de naviguer. N'ajoutez pas de titres ou de pieds de page web en doublons lorsque la navigation native possède ces surfaces. Voir les guides complets : « Utilisation de @capgo/capacitor-native-navigation » et Utilisez @capgo/capacitor-transitions.
Zones de sécurité avec Tailwind
Pour les zones de sécurité des appareils dans Tailwind CSS, utilisez @capgo/tailwind-capacitor paru sur __CAPGO_KEEP_0__ tailwind-capacitor Cela fournit des utilitaires et d'autres plugins de Tailwind compatibles avec npm : safe-areas utilities and other Capacitor-friendly Tailwind plugins:
bun add -D tailwind-capacitorUtilisez des utilitaires comme src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";et pt-safe, pb-safeau lieu de les répandre px-safe et env(safe-area-inset-*) par vous-même. Le projet est actuellement développé — si quelque chose manque pour votre configuration React, 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 la balise de vueport seule ne suffit généralement pas. Travaillez à travers ces vérifications dans l'ordre.
Assurez-vous que la balise meta de vueport est appliquée correctement
Ajoutez la balise meta de vueport dans index.html à l'intérieur <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 enveloppeur 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,
#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-shellLe doublonnement de la mise en page de la zone de sécurité dans les en-têtes, les modales et les enveloppeurs de mise en page fait souvent que l'interface utilisateur semble 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 sur cette seule coquille.
Fixez Capacitor iOS contentInset à never context : Page/zone : Page de produit avec mises à jour en temps réel. Rôle : Petit élément d'interface utilisateur ou élément de navigation. Clé de message `live_update_dynamic_label_to` (Étiquette dynamique de mise à jour en temps réel).
premier capacitor.config.tsDans contentInsetMode: 'css', préférez l'insérer natif désactivé et laissez CSS (ou la navigation native)
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Mélanger les __CAPGO_KEEP_0__ automatiques de l'insérer du contenu avec CSS
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 un grand 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 avec w-full lorsque possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, une duplication de la marge de sécurité, ou un conteneur à largeur fixe — et non de la balise meta de la vue d'ensemble 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 temps réel à 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 React, consultez l'article suivant :
Continuez à partir de Building Mobile Apps with React et Capacitor
Si vous utilisez Building Mobile Apps with React et Capacitor pour planifier l'automatisation CI/CD, connectez-l’avec Capgo CI/CD pour le flux de travail du produit dans Capgo CI/CD, Capgo Native Builds pour le flux de travail du produit dans Capgo Native Builds, Capgo Integrations pour le flux de travail du produit dans les intégrations Capgo Intégration CI/CD pour les détails d'implémentation dans Intégration CI/CD, et Actions Integration GitHub pour les détails d'implémentation dans Actions Integration GitHub
