Dans ce tutoriel, nous allons commencer par un nouveau React app and transition to native mobile development 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 React en une application mobile native sans modifications importantes ou apprentissage d'une nouvelle compétence comme React Native.
En quelques étapes simples, la plupart des applications React peuvent être transformées en applications mobiles.
Cet article vous guidera tout au long du processus, en commençant par une nouvelle application React 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 changement de jeu ! Vous pouvez l'intégrer facilement à 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 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 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 complète avec Capacitor!
Préparation de votre application React
Alors qu'il existe diverses méthodes pour initier les applications React, allons pour la plus simple dans cet article 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. Ainsi, 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 aucune inquiétude, et vous devriez être en mesure de repérer un dossier frais sorti à la racine de votre projet.
This folder will be used by Capacitor later on, but for now, we must set it up correctly.
Adding Capacitor to Your React App
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 seule sync commande.
Tout d'abord, nous pouvons installer Capacitor et @capacitor/core comme dépendance de développement, et puis les 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. Capacitor CLI Finalement, nous pouvons ajouter les plateformes, et Capacitor créera des dossiers pour chaque plateforme à la racine de notre projet:
À ce stade, vous devriez être en mesure d'observer de nouveaux
Capacitor
# 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__CAPGO_KEEP_1__ ios et android les dossiers de votre projet React.
C'est réellement un projet natif !
Pour accéder au projet Android plus tard, 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 qui contient certaines configurations fondamentales Capacitor utilisées lors de la synchronisation. La seule chose dont vous devez vous soucier est répertoireWeb, qui doit pointer vers le résultat de votre commande de build. Actuellement, elle est inexacte.
Pour rectifier cela, ouvrez le capacitor.config.json fichier et mettez à jour le répertoireWeb:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}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 React et exporterait la construction statique.
Tandis que la deuxième commande npx cap sync syncronisera tous les web code dans les bons endroits des plateformes natives afin qu'ils puissent être affichés dans une application.
De plus, la commande sync pourrait mettre à jour les plateformes natives et installer des plugins, donc lors de l'installation d'un nouveau Capacitor plugins il est temps de lancer npx cap sync encore.
Sans vous en rendre compte, vous êtes maintenant effectivement terminé, 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 de 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 deux 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 :
En 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 déjà effectué cela, Xcode vous guide à travers le processus (mais encore une fois, vous devez être inscrit au programme des développeurs). Une fois cela fait, 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 React sur un appareil mobile. Voici un exemple :
Attendez, il y a aussi une façon plus rapide de procéder 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'effort !
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.
Le premier pas 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.
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 l'adresse IP et le port corrects, 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 copyLa copy commande est similaire à syncmais ce sera uniquement copiez simplement 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 React, l'application se rechargera automatiquement et affichera les modifications !
Tenez 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 par défaut de React à des fins de démonstration.
Utilisation des plugins Capacitor
Examinons 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 :
npm i @capacitor/shareRien de particulièrement compliqué dans le Partager plugin, mais cela ouvre quand même la boîte de dialogue de partage native ! Pour cela, nous n'avons besoin désormais que d'importer le package et d'appeler la share() fonction de notre application. Changeons le src/App.js en cela :
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;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 :
npx cap syncAprès avoir cliqué sur le bouton, vous pouvez voir la belle boîte de dialogue de partage native en action !
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 Native
J'ai travaillé pendant des années avec Ionic pour construire des applications plate-forme croisée, mais l'intégrer 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 Capgo plugins au lieu des kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-native-navigation — 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 possède la barre de chrome native.
- @capgo/capacitor-transitions — transitions de page Ionic-style et iOS swipe-back sur l'arrière de la couche WebView, 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 CSS inset 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 tab en verre liquide (iOS utilise la rendu 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-pageet cap-contentet appeler setDirection('forward') ou setDirection('back') avant de naviguer. N'ajoutez pas les en-têtes ou les pieds de page web lorsqu'une navigation native contrôle ces surfaces.
Voir les guides complets : Utiliser @capgo/capacitor-navigation-native et Utiliser @capgo/capacitor-transitions.
Aires sûres avec Tailwind
Pour les zones sûres de l'appareil dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas des outils et d'autres plugins Tailwind compatibles 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 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.
Fixer 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 suffit généralement pas pour le résoudre. Travaille à travers ces vérifications dans l'ordre.
Assurez-vous que la balise meta de vueport est appliquée correctement
ajoutez la balise meta viewport dans index.html dans <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 une coquille d'application unique et appliquez-y une mise en forme de zone sûre — 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 la zone sûre répétée dans les en-têtes, les modales et les enveloppes de mise en page rend souvent l'interface utilisateur coupée ou trop grande.
Avec @capgo/tailwind-capacitorvous pouvez exprimer la même mise en forme avec des utilitaires comme pt-safe pb-safe px-safe sur cette coquille unique.
Fixez Capacitor iOS contentInset à never In
préférez l'insérer natif désactivé et laissez CSS (ou la navigation native) gérer l'espace sûr : capacitor.config.tsMélanger les __CAPGO_KEEP_0__ automatiques d'insérer le contenu avec CSS contentInsetMode: 'css'ajoute une largeur de pixels fixe ou une largeur importante
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-*) L'élément coupable est généralement un élément utilisant
, Tailwind
, une largeur de pixels fixe, ou une largeur importante 100vwEn inspecteur Web Safari, exécutez : w-screenRemplacez avec Tailwind min-width.
Premier
[...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,
}));Trouvez l'élément qui déborde vraiment w-screen avec w-full lorsque possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screenune zone de sécurité dupliquée, ou d'un conteneur de largeur fixe — et non de la balise meta viewport elle-même.
Conclusion
Capacitor est une excellente option pour créer des applications natives sur la base d'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 Capgocontexte : fragment de texte HTML d'une chaîne de Capgo (clé parent `submitting_a_pr_to_capgo`). Page/zone : site web de marketing de Capgo. Rôle : phrase du site web. Vu dans : page contributing.astro. Conservez exactement les termes de produit/marque et les termes de développeur de Capgo.
If you would like to learn how to add Capgo to your React app, take a look at the next article:
Si vous souhaitez apprendre à ajouter Capacitor à votre application React, consultez l'article suivant :
Continuez à partir de Building Mobile Apps with React et __CAPGO_KEEP_0__ Si vous utilisez Building Mobile Apps with React et Capacitor pour planifier l'automatisation de CI/CD, connectez-l’à Capgo CI/CD pour le flux de travail du produit dans Capgo CI/CD, Capgo Builds natifs pour le flux de travail du produit dans Capgo Builds natifs, Capgo Intégrations pour le flux de travail du produit dans Capgo Intégrations, Intégration CI/CD pour le détail d'implémentation dans Intégration CI/CD, et GitHub Actions d'intégration pour le détail d'implémentation dans GitHub Actions d'intégration.
