This tutorial will walk you through crafting a mobile application using React and Capacitor. By the end, you’ll know how to morph a React.js web app into a native mobile application with Capacitor, and add a native feel with Capgo Native Navigation and Transitions.
Capacitor enables the easy transformation of your React.js web app into a native mobile application, requiring no substantial alterations or learning of new strategies such as React Native.
Prosesnya melibatkan beberapa langkah sederhana, dan sebelum Anda tahu, aplikasi React.js Anda akan menjadi aplikasi mobile yang berfungsi penuh. Jadi, tetaplah bersama kami untuk menemani perjalanan ini.
Capacitor Overview
CapacitorJS adalah perubahan besar. Ia dapat menyatu dengan proyek web apa pun dan menggabungkan aplikasi Anda ke dalam tampilan web native sambil menghasilkan proyek Xcode dan Android Studio native. Selain itu, melalui pluginnya, Anda dapat mengakses fitur perangkat native seperti kamera melalui jembatan JS.
Capacitor offers a straightforward way to create a native mobile application without any hassle or steep learning curve. Its simple API and streamlined functionality make it easy to incorporate into your project.
Pengaturan Aplikasi React.js
Mari kita mulai dengan metode yang paling sederhana untuk memulai aplikasi React. Kami akan menggunakan manajer paket npm untuk membuat aplikasi React baru:
npx create-react-app my-appUntuk mengubah proyek kami menjadi aplikasi mobile native, sebuah export dari aplikasi kami diperlukan.
Kami akan kembali ke hal ini dalam beberapa saat. Terlebih dahulu, mari kita pahami cara mengintegrasikan Capacitor ke dalam aplikasi React kami.
Mengintegrasikan Capacitor ke dalam Aplikasi React.js
Langkah-langkah pengaturan awal mungkin sedikit rinci, tetapi setelah itu, memperbarui wrapper aplikasi native menjadi se sederhana sebagai menjalankan sync perintah.
Pertama, kami akan menginstal Capacitor CLI sebagai dependensi pengembangan dan mengaturnya dalam proyek kami. Selama pengaturan, terima nilai default untuk nama dan ID paket dengan menekan tombol “enter.”
Selanjutnya, kita akan menginstal paket inti dan paket relevan untuk platform iOS dan Android.
Terakhir, kita akan menambahkan platform, dan Capacitor akan membuat folder untuk setiap platform di root projek kita:
# 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 androidBagian iOS dan context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI pendek atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan). Android
direktori sekarang hadir di projek React.js Anda. Untuk mengakses projek Android nanti, instalAndroid Studio . Untuk iOS, Anda memerlukan Mac dan harus menginstal.
Xcode webDir dalam direktori web Anda capacitor.config.json seperti yang ditunjukkan di bawah:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Jalankan perintah pembangunan dan sinkronkan proyek Anda dengan Capacitor:
npm run build
npx cap syncPerintah tersebut akan membangun proyek React.js Anda, sementara __CAPGO_KEEP_0__ akan mengatur web __CAPGO_KEEP_0__ di tempat-tempat yang tepat di platform native sehingga dapat dieksekusi dalam aplikasi. npm run build Sekarang, dengan sedikit keberuntungan dan tidak ada kesalahan, aplikasi React.js Anda seharusnya sudah siap untuk diluncurkan di perangkat! npx cap sync will align the web code in the accurate places of the native platforms so they can be executed in an app.
Membangun aplikasi iOS memerlukan
Xcode
Xcode Xcodedan aplikasi Android memerlukan Studio AndroidJika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda harus mendaftar ke Apple Developer Program untuk iOS dan Google Play Console untuk Android.
Proses Capacitor CLI memudahkan proses membuka proyek native berikut:
npx cap open ios
npx cap open androidSaat proyek native Anda telah terinstal, mengirimkan aplikasi Anda ke perangkat terhubung adalah proses yang sederhana.
Untuk Studio Android, tunggu sampai segalanya terisi dan kemudian kirimkan aplikasi Anda ke perangkat terhubung.
Untuk Xcode, buatlah akun tanda tangan Anda untuk mengirimkan aplikasi Anda ke perangkat nyata bukan hanya simulator. Setelah itu, cukup tekan tombol play untuk menjalankan aplikasi di perangkat terhubung, yang dapat dipilih di atas.
Jika semuanya berjalan lancar, Anda akan telah mengubah aplikasi web React.js Anda menjadi aplikasi mobile native!
Capacitor Live Reload
Framework pengembangan modern biasanya dilengkapi dengan hot reload, dan beruntungnya, Anda dapat memiliki hal yang sama dengan Capacitor tetapi di perangkat mobile Anda!
Anda dapat membuat aplikasi yang dihosting secara lokal dapat diakses dengan live reload di jaringan Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu.
Terlebih dahulu, tentukan alamat IP lokal Anda. Pada Mac, Anda dapat melakukannya dengan menjalankan ipconfig getifaddr en0 di terminal. Pada Windows, jalankan ipconfig dan cari alamat IPv4.
After this, instruct Capacitor to load the app directly from the server by adding another parameter to your capacitor.config.ts untuk memuat aplikasi secara langsung dari server dengan menambahkan parameter lain ke file:
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;Pastikan untuk menggunakan IP dan port yang akurat. Jalankan npx cap copy untuk menerapkan perubahan-perubahan ini ke proyek native kita.
Setelah mengunduh aplikasi satu kali lagi melalui Android Studio atau Xcode, perubahan-perubahan dalam aplikasi React Anda akan secara otomatis di-reload dan ditampilkan di aplikasi Anda!
Hati-hati bahwa jika plugin baru dipasang, seperti kamera, maka diperlukan pembangunan ulang proyek native Anda. Hal ini karena file-file native akan berubah dan tidak dapat diperbarui secara langsung.
Menggunakan Plugin Capacitor
Mari kita lihat secara singkat bagaimana menggunakan plugin Capacitor. Mari kita instal plugin sederhana, yaitu Share pluginyang memicu dialog berbagi asli:
npm i @capacitor/shareTo menggunakan itu, import paket dan panggil fungsi yang sesuai dari aplikasi kami. Pertimbangkan kode share() Setelah menginstal plugin baru, jangan lupa untuk menyinkronkan kembali proyek React Anda menggunakan Selanjutnya, Anda dapat membuat aplikasi terasa lebih asli di iOS dan Android dengan navigasi dan transisi :
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;Antarmuka pengguna yang terasa asli dengan Navigasi dan Transisi Asli npx cap sync.
Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.
Native-feeling UI with Capgo Native Navigation and Transitions
Untuk merasakan mobile native di aplikasi React + , gunakan plugin-plugin alih-alih kit UI web seperti Konsta UI: __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_0__.
For a native mobile feel in a React + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- @capgo/capacitor-native-navigation — navigasi native, Liquid Glass tab bar di iOS, dan gaya tab bar yang diboroskan di Android. Router React Anda menjaga keadaan jalur; plugin menguasai chrome native.
- @capgo/capacitor-transitions — transisi halaman yang mirip dengan Ionic dan swipe-back di lapisan WebView iOS tanpa menerapkan UI Ionic.
Pasang kedua:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurasi navigasi native dengan mode CSS inset agar konten web menghormati bar-bar native:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Tampilkan tab bar Liquid Glass (iOS menggunakan rendering yang dimiliki sistem; Android menggunakan latar belakang WebView yang diboroskan):
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}`);
});Tambahkan transisi halaman native di shell aplikasi:
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>;
}Bungkus halaman yang dilalui dengan cap-router-outlet, cap-pagedan cap-contentdan panggil setDirection('forward') atau setDirection('back') Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navigasi native sebelum melanjutkan. Jangan duplikat header atau footer web ketika navigasi native menguasai permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi native dan Menggunakan @capgo/capacitor-transisi.
Menggunakan area yang aman dengan Tailwind
Untuk area yang aman perangkat dengan Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas utilitas dan plugin lainnya yang Capacitor-ramah Tailwind:
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Gunakan utilitas seperti pt-safe, pb-safe, dan px-safe daripada menambahkannya secara manual. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan React Anda, env(safe-area-inset-*) buka PR di __CAPGO_KEEP_0__ open a PR on GitHub.
Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, menambahkan lebih banyak
atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport diterapkan dengan benar
Tambahkan tag meta viewport di
di dalam index.html Pengaturan Area Aman iOS dari satu wrapper root saja <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, menambahkan lebih banyak atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan ini secara berurutan.
Buatlah sebuah shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen yang terikat beberapa kali:
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);
}Bungkuslah semua konten halaman di dalam .app-shell. Penggunaan padding area aman yang berulang di header, modal, dan wrapper layout sering membuat UI terlihat dipotong atau terlalu besar.
Dengan @capgo/tailwind-capacitor, Anda dapat mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe pada shell tunggal tersebut.
Tetapkan Capacitor iOS contentInset ke never context: Halaman/area: Halaman produk update hidup. Peran: Label UI singkat atau item navigasi. Kunci pesan `live_update_dynamic_label_to` (Live Update Dynamic Label To).
pertama capacitor.config.tsDalam contentInsetMode: 'css'Miliki area yang aman:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Menggabungkan Capacitor’s automatic content inset dengan CSS env(safe-area-inset-*) Menggunakan padding CSS adalah penyebab umum dari jarak ganda.
Cari elemen yang sebenarnya mengalami overflows
Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel yang tetap, atau kontainer yang sangat lebar min-width.
Dalam Safari Web Inspector, jalankan:
[...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,
}));Dengan Tailwind, ganti w-screen dengan w-full banyak masalah overflows horizontal berasal dari 100vw / w-screen, padding safe-area yang duplikat, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
Capacitor menyediakan cara yang mudah untuk membangun aplikasi native berdasarkan proyek web yang sudah ada, memberikan cara sederhana untuk berbagi code dan memiliki UI yang konsisten.
Terima kasih kepada teknologi seperti Capacitor, membangun aplikasi mobile dari aplikasi web React.js telah menjadi lebih mudah. Tingkatkan kemampuan pengembangan web Anda dengan menciptakan aplikasi mobile native yang impresif. Selamat berkode!
Untuk informasi lebih lanjut tentang cara Anda dapat mempercepat proses pengembangan aplikasi Anda, Daftar diri gratis hari ini. Teruslah dari Membangun Aplikasi Mobile dengan React.js dan __CAPGO_KEEP_0__
Keep going from Building Mobile Apps with Pure React.js and Capacitor
Membangun Aplikasi Mobile dengan React.js dan __CAPGO_KEEP_0__ Building Mobile Apps with Pure React.js and Capacitor Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-live-activities capgo/capacitor-aktivitas-nyata-hidup untuk detail implementasi di capgo/capacitor-aktivitas-nyata-hidup, Menggunakan capgo/capacitor-player-video untuk kemampuan asli di Menggunakan capgo/capacitor-player-video, capgo/capacitor-player-video untuk detail implementasi di capgo/capacitor-player-video, dan Menggunakan capgo/capacitor-navigasi-asli untuk kemampuan asli di Menggunakan capgo/capacitor-navigasi-asli.
