Dans ce tutoriel, nous allons commencer avec une nouvelle application React et passer à la mise en œuvre native de l'application mobile en utilisant __CAPGO_KEEP_0__. Vous pouvez également ajouter __CAPGO_KEEP_1__ Navigation Native et Transitions pour une expérience mobile native, 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.
Ce tutoriel vous guidera tout au long du processus, en commençant par une nouvelle application React et en incorporant ensuite __CAPGO_KEEP_0__ pour passer dans le domaine des applications mobiles natives. Vous pouvez également utiliser __CAPGO_KEEP_1__ Navigation Native, Transitions, et tailwind-__CAPGO_KEEP_2__ pour les zones de sécurité.
This tutorial will guide you through the process, starting with a new React app and then incorporating Capacitor to move into the realm of native mobile apps. You can also use Capgo Native Navigation, Transitions, and tailwind-capacitor for safe areas.
About 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 le projet Xcode et Android Studio natif pour vous. De plus, ses plugins vous donnent accès aux fonctionnalités de l'appareil natif comme la caméra via un pont JS.
With Capacitor, vous obtenez une application mobile native fantastique sans aucune configuration compliquée ou courbe d'apprentissage abrupte. Sa mince 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 fonctionnelle avec Capacitor!
Préparation de l'application React
Tandis 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. 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 vierge à la racine de votre projet.
Ce dossier sera utilisé par Capacitor plus tard, mais pour l'instant, nous devons le configurer correctement.
Intégration de Capacitor à votre application React
To emballer n'importe quel 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 comme une dépendance de développement, et puis configurer cela 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.
Ces 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 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 le webDir, qui doit pointer vers le résultat de votre commande de build. Actuellement, il est inexact.
Pour rectifier cela, ouvrez le capacitor.config.json file et mettez à jour le webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Vous pouvez essayer de l'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 construction statique.
Tandis 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 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 distribuer votre application sur le magasin d'applications, vous devez vous inscrire au programme Apple Developer pour les applications iOS et au Google Play Console pour les applications 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 déjà fait cela, Xcode vous guide à travers le processus (mais encore une fois, vous devez être inscrit au programme de développement). Une fois que vous avez terminé, 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 :
Mais attendez, il existe une méthode plus rapide pour effectuer cela pendant le développement…
Capacitor Live Reload
À ce stade, vous êtes probablement habitué à avoir un rechargement 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 rechargement en direct 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 :
ipconfigPuis cherchez l'adresse IPv4.
Nous pouvons 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 le bon IP et le port, j'ai utilisé le port par défaut de React dans cet exemple.
Maintenant, nous pouvons appliquer ces modifications en les copiant vers notre projet natif :
npx cap copyLa 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!
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
Étudions 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 particulier n'est fait avec le plugin de partage, mais il montre quand même le dialogue de partage natif ! Pour cela, nous n'avons désormais besoin que d'importer le package et d'appeler la share() fonction de notre application. Échangeons maintenant le src/App.js Toi, cela signifie :
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 y parvenir, exécutez la commande suivante :
npx cap syncAprès avoir cliqué sur le bouton, vous pouvez assister à 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 la navigation et des 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 la navigation native et des transitions
J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais l'intégration 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 --- une barre de navigation native, une barre de Liquid Glass sur iOS et un style de barre de navigation flou sur Android. Votre routeur React conserve l'état des routes ; le plugin possède la barre native de navigation.
- @capgo/capacitor-transitions --- des transitions de page à la manière d'Ionic et un retour arrière par balayage sur iOS dans la couche WebView, sans adopter l'interface utilisateur d'Ionic.
Installez les deux :
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigurez la navigation native avec le mode d'insérion 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 Liquid Glass (iOS utilise la mise en page système ; Android utilise un fond flou de 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-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 : En utilisant @capgo/capacitor-navigation-native et En utilisant @capgo/capacitor-transitions.
Aires sûres avec Tailwind
Pour les aires sûres du dispositif dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié comme tailwind-capacitor sur npm). Il fournit safe-areas des utilitaires et d'autres plugins de Tailwind compatibles avec Capacitor:
bun add -D tailwind-capacitorEn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utilisez des utilitaires comme pt-safe, pb-safeet px-safe au lieu de les répandre env(safe-area-inset-*) par la main. 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 disposition 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 seul le tag de vueport ne résout généralement pas le problème. Effectuez ces vérifications dans l'ordre.
Vérifiez 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érer la zone de sécurité iOS à partir d'un seul wrapper racine
Créez une coquille d'application unique et appliquez-y la mise en forme de la zone de sécurité — 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-shellLa mise en page de la zone de sécurité répétée dans les en-têtes, les modaux et les enveloppes de mise en page peut souvent donner l'impression que l'interface utilisateur est coupée ou trop grande.
Avec @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__, vous pouvez exprimer la même mise en page avec des utilitaires comme @capgo/tailwind-capacitorConfigurez __CAPGO_KEEP_0__ iOS pt-safe pb-safe px-safe à
Set Capacitor iOS contentInset En never , préférez la zone de sécurité native désactivée et laissez CSS (ou la navigation native) s'occuper de la zone de sécurité :
Inserer capacitor.config.tsInserer contentInsetMode: 'css'Inserer
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mélanger les Capacitor automatiques d'insertion de contenu avec CSS env(safe-area-inset-*) Un padding CSS est une cause fréquente de double espace.
Trouvez l'élément débordant réel
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur de pixels fixe, ou une large min-width.
En 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 par 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é de l'écran, ou un conteneur à largeur fixe — et non de la balise meta de la vue d'ensemble du navigateur 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 maintenir une interface utilisateur cohérente.
Et avec l'ajout de Capgo",il est encore plus facile d'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 corrections de bogues.
Si vous souhaitez apprendre à ajouter Capgo à votre application React, consultez l'article suivant :
Continuez à partir de la création d'applications mobiles avec React et Capacitor
Si vous utilisez La création d'applications mobiles avec React et Capacitor pour planifier l'automatisation CI/CD, connectez-le à 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 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 Intégration d'actions pour le détail d'implémentation dans GitHub Intégration d'actions.
