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 memungkinkan transformasi mudah aplikasi web React.js menjadi aplikasi seluler native, memerlukan perubahan substansial atau strategi baru seperti React Native.
Proses ini 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.
Ringkasan Capacitor
CapacitorJS adalah perubahan besar. Ia dapat mengintegrasikan 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 plugin-nya, Anda dapat mengakses fitur perangkat native seperti kamera melalui jembatan JS.
Capacitor menawarkan cara yang sederhana untuk membuat aplikasi seluler native tanpa kesulitan atau kurva belajar yang curam. Fungsi API dan fungsionalitas yang diperbarui membuatnya mudah untuk diintegrasikan ke proyek Anda.
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 seluler native, sebuah ekspor adalah diperlukan.
Pertama, mari kita pahami cara mengintegrasikan Capacitor ke dalam aplikasi React kami.
Integrasi Capacitor ke Dalam Aplikasi React.js Anda
Langkah awal mungkin sedikit rinci, tapi setelah itu, memperbarui wrapper aplikasi native Anda menjadi sebesar menjalankan sync perintah.
Pertama, kita akan menginstal Capacitor CLI sebagai dependensi pengembangan dan mengaturnya dalam proyek kita. Selama pengaturan, terima nilai default untuk nama dan ID paket 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 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 androidFolder iOS dan context Page/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan).
Android Studio Android. Untuk iOS, Anda memerlukan Mac dan sebaiknya instal Xcode.
Selanjutnya, update direktori web Anda seperti yang ditunjukkan di bawah: __CAPGO_KEEP_0__.config.json Jalankan perintah build dan sinkronkan proyek Anda dengan __CAPGO_KEEP_0__: Perintah ini akan membangun proyek React.js Anda, sementara capacitor akan mengatur web capacitor di tempat-tempat yang tepat di platform native sehingga dapat dieksekusi dalam aplikasi. Perintah 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.
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "build",
"bundledWebRuntime": false
}Perintah akan membangun proyek React.js Anda, sementara Capacitor akan mengatur web Capacitor di tempat-tempat yang tepat di platform native sehingga dapat dieksekusi dalam aplikasi.
npm run build
npx cap syncPerintah 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 Perintah 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. npx cap sync Perintah akan membangun proyek React.js Anda, sementara code akan mengatur web code di tempat-tempat yang tepat di platform native sehingga dapat dieksekusi dalam aplikasi.
Sekarang, dengan sedikit keberuntungan dan tanpa kesalahan, aplikasi React.js Anda seharusnya sudah siap untuk diluncurkan pada perangkat!
Membangun dan Mengirimkan Aplikasi Nativ 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 di Program Pengembang Apple untuk iOS dan Google Play Console untuk Android.
Proses Capacitor CLI memudahkan proses membuka proyek-proyek native berikut:
npx cap open ios
npx cap open androidSetelah proyek-proyek native Anda terinstal, mengirimkan aplikasi Anda ke perangkat terhubung adalah proses yang sederhana.
Untuk Android Studio, 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 pada perangkat terhubung Anda, yang dapat dipilih di bagian atas.
Jika semuanya berjalan lancar, Anda akan telah mengubah aplikasi web React.js Anda menjadi aplikasi mobile native!
Capacitor Reload Hidup
Framework pengembangan modern biasanya datang dengan reload panas, dan beruntungnya, Anda bisa memiliki hal yang sama dengan Capacitor tetapi di perangkat ponsel Anda!
Anda bisa membuat aplikasi yang dihosting secara lokal dapat diakses dengan reload hidup di jaringan Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu
Pertama, tentukan alamat IP lokal Anda. Pada Mac, Anda bisa 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 file: capacitor.config.ts Pastikan untuk menggunakan IP dan port yang akurat. Jalankan
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;untuk menerapkan perubahan-perubahan ini ke proyek native kita npx cap copy Setelah mengdeploy 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!
__CAPGO_KEEP_0__ Reload Hidup
Perlu diingat bahwa jika plugin baru diinstal, seperti kamera, maka diperlukan rebuild projek native Anda. Ini karena file native akan berubah dan tidak dapat diperbarui secara langsung.
Menggunakan Capacitor Plugins
Mari kita lihat cara menggunakan plugin Capacitor secara cepat. Mari kita instal plugin sederhana, yaitu Share plugin, yang mempromosikan dialog berbagi native:
npm i @capacitor/shareMenggunakannya, import paket dan panggil fungsi yang terkait dari aplikasi kita. Pertimbangkan file share() App.js Sesudah menginstal plugin baru, jangan lupa untuk sinkronisasi projek React Anda lagi menggunakan :
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;Setelah itu, Anda dapat membuat aplikasi terasa lebih native pada iOS dan Android dengan __CAPGO_KEEP_0__ navigasi dan transisi, serta memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong. npx cap sync.
Antarmuka native yang terasa dengan Capgo Native Navigation dan Transisi
Native-feeling UI with Capgo Native Navigation and Transitions
Saya telah bekerja selama bertahun-tahun dengan __CAPGO_KEEP_0__ React dan Capacitor untuk Membuat Aplikasi Mobile untuk membangun aplikasi lintas platform, tetapi mengintegrasikannya dengan React adalah sulit dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.
Untuk merasakan sentuhan mobile asli dalam aplikasi React + Capacitor , gunakan plugin Capgo alih-alih kit UI web seperti Konsta UI:
- @capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar yang diboroskan di Android. Pengaturan rute React Anda tetap; plugin menguasai chrome native.
- @capgo/capacitor-transitions — transisi halaman Ionic dan swipe balik iOS di layer WebView, tanpa menerima UI Ionic.
Install kedua-duanya:
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 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>;
}Mengelilingi halaman yang diarahkan dengan cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') Sebelum melanjutkan. Jangan duplikat header atau footer web ketika navigasi native menguasai permukaan-permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-native-navigation , dan Menggunakan @capgo/capacitor-transisi.
Wilayah aman dengan Tailwind
Untuk area-are yang aman pada perangkat dalam Tailwind CSS, gunakan @capgo/tailwind-capacitor di (diterbitkan sebagai) tailwind-capacitor pada npm). Ini menyediakan safe-areas utilitas dan plugin lainnya Capacitor-ramah Tailwind:
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Pakailah utilitas seperti pt-safe, pb-safe, dan px-safe sebaliknya dari menambahkannya env(safe-area-inset-*) secara manual. Projek ini aktif dikembangkan — jika ada yang hilang untuk pengaturan React Anda, buka PR pada GitHub.
Pengaturan Layout iOS (Viewport, Area Aman, dan Horizontal Overflow)
Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal pada iOS, menambahkan lebih banyak overflow-x: hidden atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Jalankan periksaan-periksaan ini secara berurutan.
Pastikan tag meta viewport telah diterapkan dengan benar
Tambahkan tag meta viewport di index.html didalam <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Handle area aman iOS dari wrapper root saja
Buat shell aplikasi tunggal dan terapkan padding area aman di sana — bukan di komponen nested 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);
}Wrap semua konten halaman di .app-shell Duplicasi padding area aman 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 di shell tunggal tersebut.
Set Capacitor iOS contentInset kepada never pertama
Di capacitor.config.ts, lebih baik menggunakan inset disabled asli dan biarkan CSS (atau Native Navigation's contentInsetMode: 'css') mengelola area yang aman:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'build',
ios: {
contentInset: 'never',
},
};Menggabungkan Capacitor's konten inset otomatis dengan padding CSS env(safe-area-inset-*) Temukan elemen yang sebenarnya mengalami overflows
Biasanya, penyebabnya adalah elemen yang menggunakan
, Tailwind 100vw, lebar piksel tetap, atau besar w-screenDi Safari Web Inspector, jalankan: min-width.
In
[...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,
}));Untuk Tailwind, ganti w-screen dengan w-full banyak masalah overflow horizontal berasal dari 100vw / w-screentambahan padding area aman yang digandakan, 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 sudah tidak pernah lebih mudah. Tingkatkan kemampuan pengembangan web Anda dengan menciptakan aplikasi mobile native yang impresif. Selamat berkode!
Untuk informasi lebih lanjut tentang bagaimana Anda dapat mempercepat proses pengembangan aplikasi Anda daftar diri gratis sekarang.
Teruskan dari Membangun Aplikasi Mobile dengan React.js Murni dan Capacitor
Jika Anda menggunakan Membangun Aplikasi Mobile dengan React.js dan Capacitor untuk merencanakan perilaku media dan antarmuka native, hubungkannya dengan Menggunakan @capgo/capacitor-aktivitas-hidup-nyata untuk kemampuan native dalam Menggunakan @capgo/capacitor-aktivitas-hidup-nyata, @capgo/capacitor-aktivitas-hidup-nyata untuk detail implementasi dalam @capgo/capacitor-aktivitas-hidup-nyata, Menggunakan @capgo/capacitor-pemain-video untuk kemampuan native dalam Menggunakan @capgo/capacitor-pemain-video, @capgo/capacitor-pemain-video untuk detail implementasi dalam @capgo/capacitor-pemain-video, dan Menggunakan @capgo/capacitor-navigasi-native untuk kemampuan native dalam Menggunakan @capgo/capacitor-navigasi-native.
