Pada tutorial ini, kita akan memulai dengan sebuah aplikasi baru Reakt Aplikasi dan beralih ke pengembangan mobile native menggunakan Capacitor. Anda juga dapat menambahkan Capgo Navigasi dan Transisi Native untuk merasa seperti pengembangan mobile native, dan menggunakan tailwind-capacitor untuk area yang aman.
Capacitor memungkinkan Anda untuk dengan mudah mengubah aplikasi web React Anda menjadi aplikasi mobile native tanpa perlu melakukan modifikasi signifikan atau belajar keterampilan baru seperti React Native.
Apa yang dibutuhkan hanya beberapa langkah sederhana, sebagian besar aplikasi React dapat diubah menjadi aplikasi mobile.
Tutorial ini akan mengajak Anda melalui prosesnya, mulai dari aplikasi React baru dan kemudian mengintegrasikan Capacitor untuk memasuki wilayah aplikasi mobile native. Anda juga dapat menggunakan Capgo Native Navigation, Transisi, dan tailwind-capacitor untuk area aman.
Tentang Capacitor
CapacitorJS adalah perubahan besar! Anda dapat dengan mudah mengintegrasikannya ke dalam proyek web apa pun, dan itu akan menggabungkan aplikasi Anda ke dalam view web native, menghasilkan proyek Xcode dan Android Studio native untuk Anda. Selain itu, plugin-nya memberikan akses ke fitur perangkat native seperti kamera melalui jembatan JS.
Dengan Capacitor, Anda mendapatkan aplikasi mobile native yang fantastis tanpa setup yang rumit atau kurva belajar yang curam. API dan fungsi yang diperbarui membuatnya mudah untuk diintegrasikan ke dalam proyek Anda. Percayalah, Anda akan terkejut dengan seberapa mudahnya mencapai aplikasi native yang sepenuhnya berfungsi dengan Capacitor!
Mengatur Aplikasi React Anda
Sementara ada beberapa metode untuk memulai aplikasi React, mari kita pilih yang paling sederhana dalam tutorial ini yang menyediakan aplikasi React kosong:
npx create-react-app my-appUntuk membuat aplikasi mobile native, kita membutuhkan ekspor projek kita. Oleh karena itu, mari kita tambahkan skrip yang sederhana ke dalam package.json yang dapat digunakan untuk membangun dan mengexport proyek React:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Kamu bisa menjalankan aplikasi sekarang npm run build tanpa harus khawatir, dan kamu seharusnya bisa melihat folder baru di root proyek kamu.
This folder will be used by Capacitor later on, but for now, we must set it up correctly.
Adding Capacitor to Your React App
Untuk mengemas aplikasi web menjadi kontainer mobile native, kita harus mengikuti beberapa langkah awal, tapi setelah itu, cukup sederhana seperti menjalankan perintah tunggal. sync Pertama-tama, kita bisa menginstal Capacitor dan
sebagai dependensi pengembangan, dan kemudian mengaturnya di proyek kita. Selama pengaturan, kamu bisa menekan tombol “enter” untuk menerima nilai default untuk nama dan ID bundle. Capacitor CLI Terakhir, kita bisa menambahkan platform, dan Capacitor akan membuat folder untuk setiap platform di root proyek kita:
Sampai saat ini, kamu seharusnya bisa melihat folder baru
Capacitor
# 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__CAPGO_KEEP_1__ iOS dan Android folder di proyek React Anda.
Proyek asli native!
Untuk mengakses proyek Android nanti, Anda harus menginstal Android Studio. Untuk iOS, Anda memerlukan Mac dan harus menginstal Xcode.
Selain itu, Anda harus menemukan file capacitor.config.ts di proyek Anda, yang berisi beberapa pengaturan dasar Capacitor yang digunakan selama sinkronisasi. Yang perlu Anda perhatikan hanyalah directory web, yang harus mengarah ke hasil perintah build Anda. Saat ini, itu tidak akurat.
Untuk memperbaiki hal ini, buka file capacitor.config.json dan update directory web:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}Anda dapat mencobanya dengan menjalankan perintah-perintah berikut:
npm run build
npx cap syncPerintah pertama npm run build akan hanya membangun proyek React Anda dan mengexport hasil build statis.
Sementara perintah kedua npx cap sync akan sinkronkan semua web code ke tempat-tempat yang tepat di platform-platform native sehingga dapat ditampilkan di aplikasi.
Selain itu, perintah sinkronisasi mungkin juga memperbarui platform-platform native dan menginstal plugin, sehingga ketika Anda menginstal plugin baru Capacitor plugin-plugin sekarang saatnya menjalankan npx cap sync lagi.
Tidak menyadari, Anda sekarang sudah selesai, jadi mari kita lihat aplikasi di perangkat!
Bangun dan Rilis Aplikasi Nativ
Untuk mengembangkan aplikasi iOS, Anda perlu memiliki Xcode terpasang, dan untuk aplikasi Android, Anda perlu memiliki Android Studio terpasang. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda perlu bergabung dengan Program Pengembang Apple untuk iOS dan Console Google Play untuk Android.
Jika Anda baru dalam mengembangkan aplikasi mobile natif, Anda dapat menggunakan Capacitor CLI untuk dengan mudah membuka proyek-proyek natif:
npx cap open ios
npx cap open androidSaat Anda telah mengatur proyek-proyek natif Anda, mengirimkan aplikasi Anda ke perangkat yang terhubung sangat mudah. Di Android Studio, Anda hanya perlu menunggu sampai segalanya siap, dan Anda dapat mengirimkan aplikasi Anda ke perangkat yang terhubung tanpa mengubah pengaturan apa pun. Contoh berikut ini:
In Xcode, Anda perlu mengatur akun tanda tangan Anda untuk mengirimkan aplikasi ke perangkat nyata daripada hanya simulator. Jika Anda belum pernah melakukannya sebelumnya, Xcode akan mengantarkan Anda melalui proses (tetapi lagi, Anda perlu terdaftar dalam Program Pengembang). Setelah itu, Anda hanya perlu menekan tombol play untuk menjalankan aplikasi pada perangkat yang terhubung, yang dapat Anda pilih di bagian atas. Berikut adalah contoh:
Pengumuman! Anda telah berhasil mengirimkan aplikasi web React Anda ke perangkat mobile. Berikut adalah contoh:
Tapi tunggu dulu, ada cara yang lebih cepat untuk melakukannya selama pengembangan…
Capacitor Live Reload
Sekarang, Anda mungkin sudah terbiasa dengan memiliki hot reload dengan semua kerangka kerja modern, dan kabar baiknya adalah bahwa Anda dapat memiliki fungsi yang sama pada perangkat mobile dengan upaya yang minimal!
Aktifkan akses ke aplikasi yang dihosting secara lokal dengan live reload pada jaringan Anda melalui aplikasi Capacitor memuat konten dari URL tertentu.
Langkah pertama adalah menentukan alamat IP lokal Anda. Jika Anda menggunakan Mac, Anda dapat menemukannya dengan menjalankan perintah berikut di terminal:
ipconfig getifaddr en0On Windows, jalankan :
ipconfigLalu cari alamat IPv4.
Kita dapat menginstruksikan Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan entri lain ke dalam file kita: capacitor.config.ts Pastikan Anda menggunakan
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;alamat IP dan port yang benar Saya telah menggunakan port React default dalam contoh ini.Sekarang, kita dapat menerapkan perubahan ini dengan menyalinnya ke proyek native kita:
Perintah ini mirip dengan
npx cap copyPerintah ini mirip dengan copy Perintah ini mirip dengan synctetapi hanya menggandakan perubahan yang dibuat ke folder web dan konfigurasi, tanpa memperbarui proyek native.
Anda dapat menyelesaikan aplikasi satu kali lagi melalui Android Studio atau Xcode. Setelah itu, jika Anda mengubah sesuatu di aplikasi React Anda, aplikasi akan secara otomatis reload dan menampilkan perubahan!
Pertahankanlah di dalam pikiran Anda bahwa jika Anda menginstal plugin baru seperti kamera, masih memerlukan pembangunan ulang proyek native. Ini karena file native telah berubah, dan tidak dapat dilakukan secara instan.
Penting untuk diingat bahwa Anda harus menggunakan IP dan port yang benar dalam konfigurasi. Blok code di atas menampilkan port React default untuk keperluan demonstrasi.
Menggunakan Capacitor Plugins
Tinjauan singkat tentang bagaimana menggunakan plugin Capacitor dalam aksi, yang telah disebutkan beberapa kali sebelumnya. Untuk melakukan ini, kita dapat menginstal plugin yang cukup sederhana dengan menjalankan:
npm i @capacitor/shareTidak ada yang istimewa tentang hal ini karena Plugin berbagiTapi itu tetap membawa dialog berbagi asli! share() Kita hanya perlu mengimport paket dan memanggil fungsi dari aplikasi kita. Mari kita ubah src/App.js menjadi ini:
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;Seperti yang disebutkan sebelumnya, ketika menginstal plugin baru, kita perlu melakukan operasi sinkronisasi dan kemudian meng-redeploy aplikasi ke perangkat kita. Untuk melakukan ini, jalankan perintah berikut:
npx cap syncSetelah menekan tombol, Anda dapat menyaksikan dialog berbagi asli dalam aksi!
Selanjutnya, Anda dapat membuat aplikasi terasa lebih asli di iOS dan Android dengan Capgo navigasi dan transisi, dan memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong.
UI yang terasa asli dengan Capgo Navigasi dan Transisi Asli
Saya telah bekerja selama bertahun-tahun dengan Ionic untuk membangun aplikasi lintas platform, tetapi mengintegrasikannya dengan React adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.
Untuk merasa mobile asli dalam aplikasi React + Capacitor , gunakan plugin Capgo bukan UI web-only seperti Konsta UI:
- @capgo/capacitor-native-navigation — navbar asli, Liquid Glass tab bar di iOS, dan gaya tab bar yang diboroskan di Android. Pengaturan rute React Anda tetap; plugin ini menguasai chrome asli.
- @capgo/capacitor-transitions — transisi halaman Ionik dan swipe-back di lapisan WebView iOS, tanpa menerima UI Ionik.
Install kedua:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurasi navigasi asli dengan mode CSS inset agar konten web menghormati bar-bar asli:
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 asli 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>;
}Wrap halaman yang dilalui dengan cap-router-outlet, cap-pageMenggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navigasi native cap-contentatau setDirection('forward') Menggunakan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transisi setDirection('back') Menggunakan @__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__
(diterbitkan sebagai Using @capgo/capacitor-native-navigation , dan Using @capgo/capacitor-transitions.
sebelum melanjutkan. Jangan duplikat header atau footer web ketika navigasi native menguasai permukaan-permukaan tersebut.
Lihat panduan lengkap: Menggunakan @capgo/capacitor-navigasi native atau tailwind-capacitor di npm). Ini menyediakan safe-areas fasilitas dan plugin lainnya yang Capacitor-ramah:
bun add -D tailwind-capacitorPada src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Pakai fasilitas 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 cukup untuk memperbaikinya. Lakukan periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport diterapkan dengan benar
buka PR di __CAPGO_KEEP_0__
Tambahkan tag meta viewport di index.html di dalam <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Menangani area aman iOS dari wrapper root saja
Buatlah shell aplikasi tunggal dan aplikasikan 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);
}Terapkan padding area aman di shell tunggal tersebut — bukan di komponen header, modal, dan wrapper layout: .app-shellJangan menambahkan padding area aman di beberapa komponen untuk menghindari tampilan UI yang terpotong atau terlalu besar.
Dengan @capgo/tailwind-capacitorkamu bisa mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di shell tunggal tersebut.
Setel Capacitor iOS contentInset ke never pertama
Di capacitor.config.ts, lebih baik menggunakan inset asli yang dinonaktifkan dan biarkan CSS (atau Navigasi Asli) mengontrol area yang aman: contentInsetMode: 'css'Menggabungkan __CAPGO_KEEP_0__’s automatic content inset dengan padding CSS adalah penyebab umum dari jarak ganda.
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-*) Biasanya, pelaku adalah elemen yang menggunakan
, Tailwind
, lebar piksel yang tetap, atau besar 100vwDi Safari Web Inspector, jalankan: w-screenDengan Tailwind, gantikan 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,
}));, w-screen Membuat Aplikasi Mobile React dengan Capacitor w-full Membuat Aplikasi Mobile React dengan Capacitor 100vw / w-screenBanyak masalah overflow horizontal berasal dari padding area aman yang digandakan, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
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.
Dan dengan penambahan Capgobahkan lebih mudah untuk menambahkan pembaruan hidup ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur dan perbaikan bug terbaru.
If you would like to learn how to add Capgo to your React app, take a look at the next article:
Keep going from Building Mobile Apps with React and Capacitor
Jika Anda menggunakan Building Mobile Apps with React and Capacitor untuk merencanakan otomatisasi CI/CD, hubungkannya dengan Capgo Otomatisasi CI/CD untuk alur kerja produk di Capgo Otomatisasi CI/CD, Capgo Pembangunan Nativ untuk alur kerja produk di Capgo Pembangunan Nativ, Capgo Integrasi for the product workflow in Capgo Integrations, untuk alur kerja produk di __CAPGO_KEEP_0__ Integrasi, Integrasi CI/CD GitHub Actions Integration for the implementation detail in GitHub Actions Integration.
