Tutorial ini akan memandu Anda dalam menciptakan aplikasi seluler menggunakan React dan Capacitor. Pada akhirnya, Anda akan tahu cara mengubah aplikasi web React.js menjadi aplikasi seluler native dengan Capacitor, dan menambahkan sentuhan native dengan Capgo Navigasi dan Transisi.
Capacitor memungkinkan transformasi mudah aplikasi web React.js menjadi aplikasi seluler native, tanpa perlu perubahan signifikan atau belajar strategi baru seperti React Native.
Prosesnya melibatkan beberapa langkah sederhana, dan sebelum Anda menyadari, aplikasi React.js Anda akan menjadi aplikasi seluler yang berfungsi sepenuhnya. Jadi, tetaplah bersama kami dalam perjalanan ini.
Capacitor Ringkasan
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 menawarkan cara yang sederhana untuk menciptakan aplikasi seluler native tanpa kesulitan atau kurva belajar yang curam. Fungsi API dan fungsionalitas yang disederhanakan membuatnya mudah diintegrasikan ke proyek Anda.
Mengatur Aplikasi React.js Anda
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.
Kita akan kembali ke hal ini dalam sekejap. Terlebih dahulu, mari kita pahami cara mengintegrasikan Capacitor ke dalam aplikasi React kami.
Mengintegrasikan Capacitor ke Dalam Aplikasi React.js Anda
Langkah-langkah awal konfigurasi mungkin sedikit terperinci, tapi setelah itu, memperbarui wrapper aplikasi native Anda menjadi se sederhana sebagai menjalankan sync command.
Pertama, kita akan menginstal Capacitor CLI sebagai dependensi pengembangan dan mengaturnya di dalam proyek kami. Selama proses pengaturan, terima nilai default untuk nama dan ID bundle dengan menekan “enter.”
Kemudian, 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 proyek kami:
# 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 androidAplikasi iOS dan android Direktori sekarang ada di proyek React.js Anda.
Untuk mengakses proyek Android nanti, instal Android Studio. Untuk iOS, Anda membutuhkan Mac dan harus menginstal Xcode.
Selanjutnya, update webDir di file capacitor.config.json sebagai berikut:
{
"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 syncThe npm run build Perintah akan membangun proyek React.js Anda, sementara npx cap sync akan menyinkronkan web code di tempat-tempat yang akurat dari platform native sehingga dapat dijalankan dalam aplikasi.
Sekarang, dengan sedikit keberuntungan dan tidak ada kesalahan, aplikasi React.js Anda seharusnya sudah siap untuk diluncurkan pada perangkat!
Membangun dan Mengirimkan Aplikasi Native Anda
Membangun aplikasi iOS memerlukan Xcode, dan aplikasi Android memerlukan Android Studio. Jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda harus mendaftar ke Program Pengembang Apple untuk iOS dan Google Play Console untuk Android.
Capacitor CLI memudahkan proses membuka proyek native keduanya:
npx cap open ios
npx cap open androidSetelah proyek native Anda telah terkonfigurasi, meng-deploy aplikasi ke perangkat yang terhubung adalah proses yang sederhana.
Untuk Android Studio, tunggu sampai segalanya terisi dan kemudian deploy aplikasi ke perangkat yang terhubung.
Untuk Xcode, buatlah akun tanda tangan Anda untuk meng-deploy aplikasi ke perangkat nyata bukan hanya simulator. Setelah itu, cukup tekan tombol play untuk menjalankan aplikasi di perangkat yang terhubung, yang dapat dipilih di bagian 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 di-hosting secara lokal dapat diakses dengan live reload di jaringan Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu.
Pertama, 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.
Setelah itu, instruksikan Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan parameter lain ke URL Anda. capacitor.config.ts 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 Anda menggunakan IP dan port yang akurat. Jalankan npx cap copy untuk menerapkan perubahan-perubahan ini ke proyek native kami.
Setelah meng-deploy aplikasi Anda satu kali lagi melalui Android Studio atau Xcode, perubahan-perubahan di aplikasi React Anda akan secara otomatis di-reload dan ditampilkan di aplikasi Anda!
Perlu diingat bahwa jika plugin baru diinstal, seperti kamera, maka diperlukan rebuild proyek native Anda. Hal ini karena file-file native akan berubah dan tidak dapat diperbarui secara real-time.
Menggunakan Capacitor Plugins
Mari kita lihat secara singkat bagaimana menggunakan plugin Capacitor. Mari kita instal plugin yang sederhana, yaitu Share plugin, yang mempromosikan dialog berbagi native:
npm i @capacitor/shareUntuk menggunakan plugin ini, import paket dan panggil fungsi yang terkait dari aplikasi kami. Pertimbangkan file share() App.js Menggunakan __CAPGO_KEEP_0__ Plugins:
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;After menginstal plugin baru, jangan lupa untuk sinkronkan kembali proyek React Anda menggunakan npx cap sync.
Selanjutnya, Anda dapat membuat aplikasi terasa lebih native pada iOS dan Android dengan Capgo navigasi dan transisi, dan memperbaiki masalah tata letak iOS yang umum yang menyebabkan overflows horizontal atau area aman yang dipotong.
Tampilan UI yang terasa asli dengan Capgo Navigasi dan Transisi Asli
Saya telah bekerja selama bertahun-tahun dengan Ionic untuk membangun aplikasi cross-platform, tetapi mengintegrasikannya dengan React adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.
Untuk merasakan mobile native di aplikasi React + Capacitor gunakan plugin Capgo bukan UI kit web saja seperti Konsta UI:
- @capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar pada iOS, dan gaya tab bar yang diblurkan pada Android. Router React Anda tetap memiliki status jalur; plugin ini yang menguasai chrome native.
- @capgo/capacitor-transitions — transisi halaman yang mirip dengan Ionic dan swipe-back pada iOS di layer WebView, tanpa mengadopsi UI Ionic.
Instal kedua:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurasi navigasi native dengan mode inset CSS 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 milik sistem; Android menggunakan latar belakang WebView yang diburamkan):
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 Anda:
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>;
}Kemas halaman yang diarahkan dalam cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') sebelum berpindah. Jangan duplikat header atau footer web ketika navigasi native menguasai permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-native-navigation dan Menggunakan @capgo/capacitor-transisi.
Daerah aman dengan Tailwind
Untuk daerah aman perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor pada npm). Ini menyediakan safe-areas fasilitas dan plugin-plugin Tailwind yang ramah Capacitor:
bun add -D tailwind-capacitorDi src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Gunakan fasilitas seperti pt-safe, pb-safe, dan px-safe sebagai ganti dari menambahkannya env(safe-area-inset-*) secara manual. Projek ini aktif dikembangkan — jika ada yang hilang untuk pengaturan React Anda, Buka PR di GitHub.
Mengatasi Masalah Tata Letak iOS (Viewport, Area Aman, dan Overflows Horizontal)
Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di iOS, menambahkan lebih overflow-x: hidden atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Kerjakan periksaan-periksaan ini secara berurutan.
Pastikan tag meta viewport diterapkan dengan benar
Tambahkan tag meta viewport di index.html dalam <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Atasi area aman iOS dari satu wrapper root saja
Buat shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-komponen nested yang banyak:
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);
}Bungkus semua konten halaman di .app-shellPenggunaan padding area aman yang berulang di header, modal, dan wrapper tata letak 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 di shell tunggal itu.
Atur Capacitor iOS contentInset ke never pertama
Di capacitor.config.ts, lebih baik mengaktifkan inset native dan biarkan CSS (atau Native Navigation’s) contentInsetMode: 'css') mengendalikan 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-*) padding adalah penyebab umum dari jarak ganda.
Temukan elemen yang benar-benar mengalami overflown
Biasanya, pelaku utama adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel yang tetap, atau ukuran 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 ketika memungkinkan. Banyak masalah keluaran horizontal berasal dari 100vw / w-screen, padding area yang aman yang diulang, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
Capacitor menawarkan cara yang mulus 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 ke tingkat berikutnya dengan menciptakan aplikasi mobile native yang impresif. Selamat berkode!
Untuk lebih lanjut tentang bagaimana Anda dapat mempercepat proses pengembangan aplikasi Anda, Daftar untuk akun gratis Hari ini.
Teruskan dari Membangun Aplikasi Mobile dengan React.js murni dan Capacitor
Jika Anda menggunakan Membangun Aplikasi Mobile dengan React.js murni dan Capacitor untuk merencanakan perilaku media dan antarmuka native, hubungkannya dengan Menggunakan @capgo/capacitor-aktivitas-hidup untuk kemampuan native di Menggunakan @capgo/capacitor-aktivitas-hidup, @capgo/capacitor-aktivitas-hidup untuk detail implementasi di @capgo/capacitor-aktivitas-hidup, Menggunakan @capgo/capacitor-player-video untuk kemampuan native di Menggunakan @capgo/capacitor-player-video, @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player, dan Menggunakan @capgo/capacitor-native-navigation untuk kemampuan asli di Menggunakan @capgo/capacitor-native-navigation.
