Dalam tutorial ini, kami akan memandu Anda melalui proses mengonversi aplikasi web Vue menjadi aplikasi mobile native menggunakan Capacitor. Anda juga dapat menambahkan Capgo Navigasi dan Transisi Native untuk merasakan aplikasi mobile asli, serta menggunakan tailwind-capacitor untuk area aman.
Tentang Capacitor
Capacitor adalah alat yang mengubah permainan yang memungkinkan Anda untuk dengan mudah mengintegrasikan Capacitor ke dalam proyek web apa pun dan mengonversi aplikasi Anda menjadi aplikasi mobile native. Alat ini menghasilkan proyek Xcode dan Android Studio native untuk Anda dan memberikan akses ke fitur perangkat native seperti kamera melalui jembatan JavaScript.
Mempersiapkan Aplikasi Vue
Terlebih dahulu, buatlah sebuah aplikasi Vue dengan menjalankan perintah berikut:
vue create my-app
cd my-app
npm installMengatur aplikasi Vue Anda untuk pengembangan mobile native, Anda akan perlu mengexport proyek Anda. Tambahkan skrip di file package.json untuk membangun dan menyalin proyek Vue:
{
"scripts": {
// ...
"build": "vue-cli-service build"
}
}Setelah menjalankan build perintah, Anda harus melihat sebuah folder baru di direktori root proyek Anda. Folder ini akan digunakan oleh Capgo nanti. dist folder in your project’s root directory. This folder will be used by Capacitor later.
Adding Capacitor to Your Vue App
Instalasi Capgo dan __CAPGO_KEEP_1__ sebagai dependensi pengembangan dan atur dalam proyek Anda. Terima nilai default untuk nama dan ID aplikasi selama proses pengaturan.
-
Install the Capacitor CLI as a development dependency and set it up within your project. Accept the default values for name and bundle ID during the setup.
-
Tambahkan platform, dan Capgo akan membuat folder untuk setiap platform di root proyek Anda:
-
Capacitor
# Install the Capacitor CLI locally
npm install -D @capacitor/cli
# Initialize Capacitor in your Vue 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 androidSekarang Anda harus melihat folder baru iOS dan android dalam proyek Vue Anda.
Perbarui file capacitor.config.json untuk mengarahkan webDir ke hasil perintah build Anda:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Sekarang, Anda dapat membangun proyek Vue Anda dan sinkronkan dengan Capacitor:
npm run build
npx cap syncBuat dan Deploy Aplikasi Native
Untuk mengembangkan aplikasi iOS, Anda membutuhkan Xcode terinstal, dan untuk aplikasi Android, Anda membutuhkan Android Studio terinstal. Selain itu, Anda perlu mendaftar ke Program Pengembang Apple untuk iOS dan Console Google Play untuk Android untuk mendistribusikan aplikasi Anda di toko aplikasi.
Gunakan Capacitor CLI untuk membuka proyek native baik:
npx cap open ios
npx cap open androidDeploy aplikasi Anda ke perangkat terhubung menggunakan Android Studio atau Xcode.
Capacitor Live Reload
Aktifkan ulang hidup pada perangkat mobile Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu di jaringan Anda.
Temukan alamat IP lokal Anda dan update file dengan alamat IP dan port yang benar: capacitor.config.ts Terapkan perubahan-perubahan ini dengan menyalinnya ke proyek native Anda:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'dist',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:8080',
cleartext: true
}
};
export default config;Sekarang, aplikasi Anda akan secara otomatis reload dan menampilkan perubahan ketika Anda memperbarui aplikasi Vue Anda.
npx cap copyMenggunakan __CAPGO_KEEP_0__ Plugins
Pasang plugin Capacitor seperti plugin Share dan gunakan di aplikasi Vue Anda:
Install a Capacitor plugin, such as the Share plugin, and use it in your Vue app:
npm i @capacitor/shareImpor paket dan panggil share() fungsi di aplikasi Anda:
<template>
<div>
<h1>Welcome to Vue and Capacitor!</h1>
<button @click="share">Share now!</button>
</div>
</template>
<script setup lang="ts">
import { Share } from '@capacitor/share';
async function share() {
await Share.share({
title: 'Open Youtube',
text: 'Check new video on youtube',
url: 'https://www.youtube.com',
dialogTitle: 'Share with friends'
});
}
</script>Setelah menginstal plugin baru, jalankan perintah ini dan redeploy aplikasi ke perangkat Anda: sync Selanjutnya, Anda dapat membuat aplikasi terasa lebih native di iOS dan Android dengan __CAPGO_KEEP_0__ navigasi dan transisi, dan memperbaiki masalah tata letak iOS yang umum yang menyebabkan overflows horizontal atau area aman yang dipotong.
npx cap syncAntarmuka native dengan Capgo Navigasi dan Transisi Native
Native-feeling UI with Capgo Native Navigation and Transitions
Ionic untuk membangun aplikasi lintas platform, tetapi mengintegrasikannya dengan Vue adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS Untuk merasakan mobile native di aplikasi Vue + __CAPGO_KEEP_0__ gunakan plugin __CAPGO_KEEP_1__ bukan kit UI web saja seperti Konsta UI:.
@Capacitor/Capgo-native-navigation
- @capgo/capacitor-native-navigation —
- Transisi @capgo/capacitor-transisi --- Transisi halaman Ionic gaya dan iOS swipe-back di lapisan WebView, tanpa menerima UI Ionic.
Instal keduanya:
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 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 }) => {
router.push(`/${id}`);
});Tambahkan transisi halaman native di shell aplikasi:
<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';
initTransitions({ platform: 'auto' });
const router = useRouter();
const outletRef = ref(null);
onMounted(() => {
if (outletRef.value) {
setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
}
});
const openSettings = () => {
setDirection('forward');
router.push('/settings');
};
</script>
<template>
<cap-router-outlet ref="outletRef">
<router-view />
</cap-router-outlet>
</template>Langkapi halaman yang dilalui dengan 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-transitions.
Wilayah aman dengan Tailwind
Untuk wilayah perangkat aman di Tailwind CSS, gunakan @capgo/tailwind-capacitor (diterbitkan sebagai tailwind-capacitor di npm). Ini menyediakan safe-areas utilitas dan plugin-plugin lainnya yang Capacitor-ramah Tailwind:
bun add -D tailwind-capacitorDalam src/assets/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Gunakan utilitas seperti pt-safe, pb-safe, dan px-safe bukan dengan menyebarkan secara manual. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan Vue 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
atau mengatur tag viewport saja biasanya tidak dapat memperbaikinya. Kerjakan periksaan-periksaan ini secara berurutan. overflow-x: hidden Pastikan tag meta viewport diterapkan dengan benar
Tambahkan tag meta viewport di
dalam index.html Atasi Area Aman iOS dari satu wrapper root saja <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Buatlah shell aplikasi tunggal dan aplikasikan padding area aman di sana — bukan di komponen-komponen nested yang banyak:
Bungkus semua konten halaman di dalam
html,
body,
#app {
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);
}Mengatasi Masalah Tata Letak iOS (Viewport, Area Aman, dan Overflows Horizontal) .app-shell. Padding area yang aman di header, modal, dan wrapper layout sering membuat UI terlihat dipotong atau terlalu besar.
Dengan @capgo/tailwind-capacitor, Anda dapat mengungkapkan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe di dalam cangkang tunggal itu.
Atur Capacitor iOS contentInset ke never pertama
Dalam capacitor.config.ts, prefer inset konten asli tidak aktif dan biarkan CSS (atau Native Navigation’s contentInsetMode: 'css') mengendalikan 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-*) jeda adalah penyebab umum dari penambahan baris ganda.
Temukan elemen yang sebenarnya mengalami overflown
Biasanya, penyebabnya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau besar min-width.
Di 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 overflown horizontal berasal dari 100vw / w-screen, padding area aman yang diulang, atau kontainer lebar tetap — bukan dari tag meta viewport itu sendiri.
Kesimpulan
Capacitor adalah pilihan yang bagus untuk membuat aplikasi native berdasarkan proyek web yang sudah ada. Dengan penambahan Capgo, bahkan lebih mudah untuk menambahkan pembaruan hidup ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur dan perbaikan bug terbaru.
Pelajari bagaimana Capgo dapat membantu Anda membangun aplikasi yang lebih baik dengan lebih cepat, daftar diri untuk akun gratis hari ini.
Teruskan dari Membangun Aplikasi Mobile dengan Vue dan Capacitor
Jika Anda menggunakan Membangun Aplikasi Mobile dengan Vue dan Capacitor untuk merencanakan perilaku media dan interface 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-pemain-video untuk kemampuan asli di Menggunakan @capgo/capacitor-video-player, @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.
