Dans ce tutoriel, nous allons commencer avec une nouvelle application React et passer à un développement mobile natif en utilisant __CAPGO_KEEP_0__. Vous pouvez également ajouter __CAPGO_KEEP_1__ des meilleures pratiques de navigation et de transitions pour un sentiment mobile natif, et utiliser tailwind-__CAPGO_KEEP_2__ pour les zones de sécurité. 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 allows you to easily convert your React web application into a native mobile app without significant modifications or learning a new skill like React Native.
With just a few simple étapes, 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 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 jeu de hasard ! 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 dispositif natif comme la caméra via un pont JS.
Avec Capacitor, vous obtenez une fantastique application mobile native sans aucune configuration compliquée ou courbe d'apprentissage raide. Sa fine API et sa fonctionnalité épurée rendent l'intégration dans votre projet un jeu d'enfant. Faites-moi confiance, 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 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, incorporons un script simple dans 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.
Ce dossier sera utilisé par Capacitor plus tard, mais pour l'instant, nous devons le configurer correctement.
Ajouter Capacitor à votre application React
Pour emballer n'importe quelle application web dans un conteneur mobile natif, nous devons suivre quelques étapes initiales, mais ensuite, c'est aussi simple que d'exécuter un seul sync commande.
Tout d'abord, nous pouvons installer le Capacitor CLI en tant que dépendance de développement, et puis configurer ensuite 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 devons installer le package de base et les packages pertinents pour les plateformes iOS et Android.
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 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 être en mesure d'observer de nouveaux ios et android dossiers dans votre projet React.
Cela sont des projets natifs réels !
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 capacitor.config.ts fichier 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 répertoireWeb, qui doit pointer vers le résultat de votre commande de build. Actuellement, c'est inexact.
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 exporter la build statique.
Alors que la deuxième commande npx cap sync syncra 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 à nouveau.
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 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 :
Configurez votre compte de signature dans Xcode 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 '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 :
Mais attendez, il existe également un moyen plus rapide de procéder pendant le développement…
Capacitor Live Reload
À ce stade, vous êtes probablement habitué à avoir un redémarrage chaud 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 redémarrage en direct 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 en0Ensuite, sur Windows, exécutez :
ipconfigRecherchez ensuite l'adresse IPv4.
On peut instruire Capacitor pour charger l'application directement du 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 correctsJ'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 cela ne fera que copier 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 !
Tenez compte que si vous installez de nouveaux plugins tels que 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'adresse 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 Capacitor Plugins
Étudions maintenant comment utiliser un Capacitor plugin 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 cela. Partager plugin, mais elle affiche quand même le dialogue de partage natif ! Pour cela, nous n'avons besoin désormais que d'importer le package et d'appeler la share() fonction depuis notre application. Modifions 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 redéployer ensuite l'application sur notre appareil. Pour cela, exécutez la commande suivante :
npx cap syncAprès avoir cliqué sur le bouton, vous pouvez assister à la belle apparition du dialogue de partage natif !
Ensuite, vous pouvez rendre l'application encore 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.
Interface utilisateur ressemblant à celle d'un appareil natif avec Capgo de Navigation et de Transitions Native
J'ai travaillé pendant des années avec Ionic pour construire des applications multiplateformes, mais intégrer cela avec React est un peu maladroit et rarement justifié lorsque vous avez déjà Tailwind CSS.
Pour un sentiment de mobile natif dans une application React + Capacitor , utilisez les Capgo plugins au lieu de kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-navigation-native — barre de navigation native, Liquid Glass barre de tabs sur iOS, et un style de barre de tabs flou sur Android. L'État de navigation de votre routeur React est conservé ; 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 en verre liquide (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 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-contentou appeler setDirection('forward') avant de naviguer. N'ajoutez pas les en-têtes ou les pieds de page lorsque la navigation native gère ces surfaces. setDirection('back') Consultez les guides complets :
En utilisant @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navigation-native Using @capgo/capacitor-native-navigation En utilisant @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions Using @capgo/capacitor-transitions.
Pour les zones sûres des appareils dans Tailwind CSS, utilisez
@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitor __CAPGO_KEEP_0__ tailwind-capacitor On npm). Il fournit des safe-areas outils et d'autres plugins de Tailwind compatibles avec Capacitor :
bun add -D tailwind-capacitorIn 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 PR 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 de overflow-x: hidden ou ajuster la balise de vueport seule ne suffit généralement pas pour résoudre le problème. 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 index.html dans <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Gérer l'espace sûr iOS à partir d'un seul enveloppe racine
Créez une coquille d'application unique 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 .app-shell. La mise en forme de l'espace sûr répétée dans les en-têtes, les modales et les enveloppes de mise en page 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 coquille unique.
Configurez Capacitor iOS contentInset à never Premier
En français, préférez l'insérer nativement désactivé et laissez CSS (ou la navigation native) gérer la zone de sécurité : capacitor.config.tsMélanger les marges automatiques de __CAPGO_KEEP_0__ avec CSS est une cause courante de double espace. contentInsetMode: 'css'Trouvez l'élément qui déborde vraiment
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-*) , Tailwind
, une largeur fixe en pixels, ou une large
En inspecteur Web Safari, exécutez : 100vwAvec Tailwind, remplacez w-screenpar min-width.
un
[...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,
}));un w-screen Lorsque possible. De nombreux problèmes de débordement horizontal proviennent de w-full , d'une duplication de la marge de sécurité, ou d'un conteneur de largeur fixe — et non de la balise meta viewport elle-même. 100vw / w-screenConclusion
__CAPGO_KEEP_0__ est une excellente option pour créer des applications natives basées sur un projet web existant, offrant une façon simple de partager __CAPGO_KEEP_1__ et de maintenir une interface utilisateur cohérente.
Capacitor is an excellent option for building native applications based on an existing web project, offering a simple way to share code and maintain a consistent UI.
__CAPGO_KEEP_0__ CapgoSi vous souhaitez apprendre à ajouter __CAPGO_KEEP_0__ à votre application React, consultez l'article suivant :
Continuez à partir de la création d'applications mobiles avec React et Capgo
Keep going from Building Mobile Apps with React and Capacitor
La création d'applications mobiles avec React et __CAPGO_KEEP_0__ Building Mobile Apps with React and Capacitor planifier l'automatisation de CI/CD, la connecter à 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 de CI/CD pour les détails d'implémentation dans Intégration de CI/CD, et GitHub Intégration d'Actions pour les détails d'implémentation dans GitHub Intégration d'Actions.
