Di tutorial ini, kita akan memulai dengan aplikasi React baru dan beralih ke pengembangan mobile native menggunakan __CAPGO_KEEP_0__. React 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.
Tutorial ini akan memandu Anda melalui prosesnya, mulai dari aplikasi React baru dan kemudian mengintegrasikan __CAPGO_KEEP_0__ untuk beralih ke aplikasi mobile native. Anda juga dapat menggunakan __CAPGO_KEEP_1__ Native Navigation, Transitions, dan tailwind-__CAPGO_KEEP_2__ untuk area yang aman.
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
Dengan __CAPGO_KEEP_0__, Anda mendapatkan aplikasi mobile native yang fantastis tanpa setup yang rumit atau kurva belajar yang curam. Fungsi __CAPGO_KEEP_1__ dan __CAPGO_KEEP_2__ yang tipis dan terstruktur membuatnya mudah untuk diintegrasikan ke proyek Anda. Percayalah, Anda akan terkejut dengan seberapa mudahnya mencapai aplikasi mobile native yang sepenuhnya berfungsi dengan __CAPGO_KEEP_2__!
With Capacitor, you get a fantastic native mobile app without any complicated setup or steep learning curve. Its slim API and streamlined functionality make it a breeze to integrate into your project. Trust me, you’ll be amazed at how effortless it is to achieve a fully functional native app with Capacitor!
__CAPGO_KEEP_1__
Meskipun ada beberapa cara untuk memulai aplikasi React, mari kita pilih cara termudah dalam tutorial ini yang menyediakan aplikasi React kosong:
npx create-react-app my-appMengapa kita memerlukan aplikasi React native, kita memerlukan ekspor projek kita. Oleh karena itu, mari kita tambahkan skrip yang sederhana ke dalam package.json yang dapat digunakan untuk membangun dan mengexport aplikasi React:
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}Sekarang Anda dapat menjalankan npm run build tanpa khawatir, dan Anda seharusnya dapat melihat folder baru di root projek Anda.
This folder will be used by Capacitor later on, but for now, we must set it up correctly.
Adding Capacitor to Your React App
Mengemas aplikasi web apa pun ke dalam kontainer mobile native, kita harus mengikuti beberapa langkah awal, tetapi setelah itu, itu hanya sebagai sederhana sebagai menjalankan perintah tunggal. sync __CAPGO_KEEP_0__
Terlebih dahulu, kita dapat menginstal Capacitor CLI sebagai dependensi pengembangan, dan kemudian mengaturinya dalam proyek kita. Selama pengaturan, Anda dapat menekan “enter” untuk menerima nilai default untuk nama dan ID paket.
Selanjutnya, kita perlu menginstal paket inti dan paket relevan untuk platform iOS dan Android.
Akhirnya, kita dapat 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 androidPada titik ini, Anda seharusnya dapat melihat folder baru ios dan context Page/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (And).
android
di proyek React Anda. Studio AndroidUntuk iOS, Anda memerlukan Mac dan sebaiknya menginstal Xcode.
Selain itu, Anda harus menemukan file capacitor.config.ts yang berisi beberapa pengaturan dasar Capacitor yang digunakan selama sinkronisasi. Yang perlu Anda perhatikan adalah webDiryang harus mengarah ke hasil perintah build Anda. Saat ini, nilai ini tidak akurat.
Untuk memperbaiki hal ini, buka file capacitor.config.json dan update nilai webDir:
{
"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 hanya akan membangun proyek React Anda dan mengexport 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 akan memperbarui platform-platform native dan menginstal plugin, sehingga ketika Anda menginstal plugin baru Capacitor maka saatnya untuk menjalankan npx cap sync lagi.
Tanpa menyadari, Anda sudah selesai, jadi mari kita lihat aplikasi di perangkat!
Membangun dan Mengirimkan Aplikasi Nativ
Untuk mengembangkan aplikasi iOS, Anda memerlukan Xcode terpasang, dan untuk aplikasi Android, Anda membutuhkan untuk memiliki Android Studio terpasang. Selain itu, jika Anda berencana untuk mendistribusikan aplikasi Anda di toko aplikasi, Anda perlu mendaftar di Program Pengembang Apple untuk iOS dan Google Play Console untuk Android.
Jika Anda baru dalam pengembangan mobile native, Anda dapat menggunakan Capacitor CLI untuk dengan mudah membuka proyek native berikut:
npx cap open ios
npx cap open androidSetelah Anda telah mengatur proyek native Anda, mengdeploy aplikasi Anda ke perangkat terhubung sangat mudah. Di Android Studio, Anda hanya perlu menunggu sampai segalanya siap, dan Anda dapat mengdeploy aplikasi Anda ke perangkat terhubung tanpa mengubah pengaturan apa pun. Contoh berikut:
Di Xcode, Anda perlu mengatur akun tanda tangan Anda untuk mengdeploy aplikasi Anda ke perangkat nyata bukan hanya simulator. Jika Anda belum pernah melakukannya sebelumnya, Xcode akan mengarahkan Anda melalui prosesnya (tetapi lagi, Anda perlu mendaftar di Program Pengembang). Setelah itu, Anda hanya perlu menekan tombol play untuk menjalankan aplikasi di perangkat terhubung, yang dapat Anda pilih di bagian atas. Contoh berikut:
Selamat! Anda telah berhasil mengdeploy aplikasi web React Anda ke perangkat mobile. Contoh berikut:
Tapi tunggu dulu, ada cara yang lebih cepat untuk melakukannya selama pengembangan...
Capacitor Reload Hidup
Dengan demikian, Anda mungkin sudah terbiasa dengan memiliki reload panas dengan semua kerangka kerja modern, dan kabar baiknya adalah bahwa Anda dapat memiliki fungsi yang sama pada perangkat seluler dengan sedikit usaha!
Aktifkan akses ke aplikasi Anda yang dihosting secara lokal dengan reload hidup pada jaringan Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu.
Langkah pertama adalah menentukan alamat IP lokal Anda. Jika Anda menggunakan Mac, Anda dapat menemukan informasi ini dengan menjalankan perintah berikut di terminal:
ipconfig getifaddr en0Di Windows, jalankan :
ipconfigLalu cari alamat IPv4.
Kita dapat menginstruksikan Capacitor untuk memuat aplikasi secara langsung dari server dengan menambahkan entri lain ke file kami: capacitor.config.ts file:
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;Pastikan Anda menggunakan alamat IP dan port yang benar, saya telah menggunakan port React default dalam contoh ini.
Sekarang, kita dapat menerapkan perubahan-perubahan ini dengan menyalinnya ke proyek native kita:
npx cap copyPerintah ini mirip dengan copy , tetapi hanya akan syncmenyalin perubahan-perubahan yang dibuat ke folder web dan konfigurasi, tanpa memperbarui proyek native. Anda dapat menyelesaikan pengembangan aplikasi Anda 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-perubahan! the app will automatically reload and show the changes!
Perlu diingat bahwa jika Anda menginstal plugin baru seperti kamera, masih memerlukan rebuild projek native Anda. Ini karena file native telah berubah, dan tidak dapat dilakukan secara langsung.
Penting untuk diingat bahwa Anda harus menggunakan IP dan port yang benar dalam konfigurasi Anda. Blok code di atas menunjukkan port React default untuk keperluan demonstrasi.
Menggunakan Capacitor Plugins
Mari kita lihat 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 plugin Pengiriman, tetapi plugin ini tetap saja menampilkan dialog pengiriman native! Untuk ini, kita hanya perlu mengimport paket dan memanggil share() 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;Asasnya, 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 native yang indah dalam aksi!
Selanjutnya, Anda dapat membuat aplikasi terasa lebih native pada iOS dan Android dengan Capgo navigasi dan transisi, serta memperbaiki masalah layout iOS yang umum menyebabkan overflow horizontal atau area aman yang dipotong.
Antarmuka UI yang terasa native dengan Capgo Navigasi dan Transisi Native
Saya telah bekerja selama beberapa tahun dengan Ionic untuk membangun aplikasi multi-platform, tetapi mengintegrasikannya dengan React adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.
Untuk merasakan mobile native dalam aplikasi React + Capacitor, gunakan plugin Capgo daripada kit UI web saja seperti Konsta UI:
- @capgo/capacitor-native-navigation — navbar native, Liquid Glass tab bar pada iOS, dan gaya tab bar yang diboroskan pada Android. Pengaturan router React Anda tetap; plugin ini yang menguasai chrome native.
- @capgo/capacitor-transitions — Transisi halaman Ionic-style dan pengembalian iOS edge swipe di layer WebView, tanpa menerapkan UI Ionic.
Install 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',
},
});Render tab bar kaca cair (iOS menggunakan rendering milik 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>;
}Wrap halaman yang diarahkan dalam cap-router-outlet, cap-pagedan cap-contentdan panggil setDirection('forward') atau setDirection('back') context
HTML fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `alternatives_cta_questions`). Halaman/area: Halaman perbandingan alternatif Capacitor live-update. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman alternatives.astro. Simpan produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `alternatives_cta_questions` (Pertanyaan Tindakan Alternatif). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `appflow_cta_questions`). Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman ionic-appflow.astro. Simpan produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `appflow_cta_questions` (Pertanyaan Tindakan Appflow). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `capwesome_cta_questions`). Halaman/area: Halaman perbandingan Capawesome. Peran: Paragraf pemasaran atau hukum yang panjang. Dilihat di: halaman capwesome.astro. Simpan produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `capwesome_cta_questions` (Pertanyaan Tindakan Capwesome). | Fragment teks HTML dari string UI Capgo yang lebih panjang (kunci induk `consulting_faq_subtitle`). Halaman/area: Halaman layanan konsultasi. Peran: Judul atau tagline bagian. Dilihat di: halaman consulting.astro. Simpan produk/brand dan istilah developer Capgo secara tepat. Kunci pesan `consulting_faq_subtitle` (Judul FAQ Layanan Konsultasi). | Halaman/area: Halaman perbandingan/migrasi pemasaran Appflow. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman ionic-appflow.astro, halaman ionic-enterprise-plugins.astro, halaman solusi/ionic-enterprise-plugins.astro. Kunci pesan `appflow_plugins_or` (Appflow Plugins Atau). Using @capgo/capacitor-native-navigation dan Gunakan @capgo/capacitor-transisi.
Wilayah aman dengan Tailwind
Untuk wilayah aman perangkat di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai) tailwind-capacitor di npm. Ini menyediakan safe-areas fasilitas dan plugin-plugin Tailwind yang Capacitor-ramah:
bun add -D tailwind-capacitorDalam 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 menaburkannya env(safe-area-inset-*) oleh tangan. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan React Anda, buka PR di GitHub.
Pengaturan Layout iOS (Viewport, Area Aman, dan Horizontal Overflow)
Jika konten terlihat dipotong, bergeser, atau dapat di-scroll secara horizontal di 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 diterapkan dengan benar
Tambahkan tag meta viewport di index.html di dalam <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Pengaturan Area Aman iOS dari satu wrapper root saja
Buatlah shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-komponen nested yang berbeda:
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);
}Selimuti semua konten halaman di dalam .app-shellPengaturan 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 di shell tunggal itu.
Set Capacitor iOS contentInset ke never pertama
Dalam capacitor.config.ts, lebih baik menggunakan inset asli dan biarkan CSS (atau Native Navigation’s) contentInsetMode: 'css') mengontrol area aman:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
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 sebenarnya mengalami overflow
Penyebab biasanya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau kontainer yang sangat lebar min-width.
In 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 bila memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screen, padding area aman yang digandakan, atau kontainer dengan lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
Capacitor adalah pilihan yang sangat baik untuk membuat aplikasi native berdasarkan proyek web yang sudah ada, menawarkan cara sederhana untuk berbagi code dan menjaga UI yang konsisten.
Dan dengan penambahan CapgoMengapa lebih mudah lagi menambahkan pembaruan hidup ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur-fitur terbaru dan perbaikan bug.
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 CI/CD for the product workflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations untuk alur kerja produk di Integrasi Capgo Integrasi CI/CD context":"Halaman/area: Halaman Pembangun Capgo / halaman produk cloud asli. Peran: Label UI pendek atau item navigasi. Pesan kunci `native_build_feature_ci_cd` (Native Build Feature Ci Cd)." GitHub Actions Integration GitHub Integrasi Aksi
