Membangun Aplikasi Seluler dengan Vue dan Capacitor

In this tutorial, we’ll guide you through the process of converting a Vue web application into a native mobile app using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.

Tentang Capacitor

Capacitor is a game-changing tool that allows you to easily integrate it into any web project and convert your application into a native mobile app. It generates native Xcode and Android Studio projects for you and provides access to native device features like the camera through a JavaScript bridge.

Mengsiapkan Aplikasi Vue

Pertama, buatlah aplikasi Vue baru dengan menjalankan perintah berikut:

vue create my-app
cd my-app
npm install

Mengsiapkan aplikasi Vue Anda untuk pengiriman aplikasi seluler native, Anda perlu mengexport proyek Anda. Tambahkan skrip di file package.json file untuk membangun dan menyalin proyek Vue:

{
  "scripts": {
    // ...
    "build": "vue-cli-service build"
  }
}

Setelah menjalankan build command, Anda akan melihat perintah baru dist folder baru di direktori root projek Anda. Folder ini akan digunakan oleh Capacitor nanti.

Menambahkan Capacitor ke Aplikasi Vue Anda

Untuk mengubah aplikasi web Vue Anda menjadi kontainer mobile native, ikuti langkah-langkah berikut:

1. Instal Capacitor CLI sebagai dependensi pengembangan dan atur dalam projek Anda. Terima nilai default untuk nama dan ID aplikasi selama proses pengaturan.

2. Instal paket inti dan paket relevan untuk platform iOS dan Android.

3. Tambahkan platform, dan Capacitor akan membuat folder untuk setiap platform di root projek Anda:

# 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 android

anda harus melihat folder baru iOS dan folder baru folder di proyek Vue Anda.

Perbarui file capacitor.config.json file untuk mengarahkan ke webDir kepada hasil perintah pembangunan 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 sync

Membangun dan Mengirimkan Aplikasi Nativ

To develop iOS apps, you need Xcode installed, and for Android apps, you need Android Studio installed. Additionally, you need to enroll in the Apple Developer Program for iOS and the Google Play Console for Android to distribute your app on the app store.

Buka kedua proyek native dengan menggunakan Capacitor CLI.

npx cap open ios
npx cap open android

Tunggu aplikasi Anda di perangkat yang terhubung menggunakan Android Studio atau Xcode.

Capacitor Reload Langsung

aktifkan ulang hidup di perangkat seluler Anda dengan memiliki aplikasi Capacitor memuat konten dari URL tertentu di jaringan Anda.

Cari alamat IP lokal Anda dan perbarui capacitor.config.ts file dengan IP dan port yang benar:

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;

Terapkan perubahan-perubahan ini dengan menyalinnya ke proyek asli Anda.

npx cap copy

Sekarang, aplikasi Anda akan secara otomatis reload dan menampilkan perubahan ketika Anda memperbarui aplikasi Vue Anda.

Install plugin Capacitor seperti plugin Share dan gunakan di aplikasi Vue Anda:

Pasang plugin Capacitor seperti plugin Share dan gunakan di aplikasi Vue Anda.

npm i @capacitor/share

Importkan 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 sync perintah dan redeploy aplikasi ke perangkat Anda:

npx cap sync

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.

Antarmuka yang terasa asli dengan Capgo Navigasi dan Transisi Asli

I telah bekerja selama tahun dengan Ionic untuk membangun aplikasi multi-platform, tetapi mengintegrasikannya dengan Vue adalah hacky dan jarang berharga ketika Anda sudah memiliki Tailwind CSS.

Untuk merasakan perasaan mobile asli dalam aplikasi Vue + Capacitor, gunakan plugin Capgo alih-alih UI web-only seperti Konsta UI:

• @capgo/capacitor-navigasi native — navbar native, Liquid Glass tab bar di iOS, dan gaya tab bar yang diboroskan di Android. Pengaturan rute Vue Anda tetap; plugin ini menguasai chrome native.
• @capgo/capacitor-transisi — transisi halaman Ionic dan swipe-back di lapisan WebView iOS, tanpa menerima UI Ionic.

Install kedua:

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

Konfigurasi 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 }) => {
  router.push(`/${id}`);
});

Menambahkan 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>

Terapkan halaman yang diarahkan ke cap-router-outlet, cap-page, dan cap-content, dan panggil setDirection('forward') atau setDirection('back') Sebelum navigasi. 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.

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 lainnya yang Capacitor-ramah Tailwind:

bun add -D tailwind-capacitor

Dalam 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 alih-alih menyebarkan env(safe-area-inset-*) dengan tangan sendiri. Projek ini aktif dikembangkan — jika ada sesuatu yang hilang untuk pengaturan Vue Anda, Buka PR di GitHub.

Mengatasi Masalah Tata Letak iOS (Viewport, Area Aman, dan Overflows Horizontal)

Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow) overflow-x: hidden atau mengatur tag viewport saja biasanya tidak cukup untuk memperbaiki masalah tersebut. Jalankan periksa-periksa ini dalam urutan yang tepat.

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" />

Handle 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,
#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);
}

Selimuti semua konten halaman di .app-shell. Menggunakan padding area aman yang sama di header, modal, dan wrapper layout sering membuat UI terlihat dipotong atau terlalu besar.

Dengan @capgo/tailwind-capacitorkamu bisa mengekspresikan padding yang sama dengan utilitas seperti pt-safe pb-safe px-safe pada shell tunggal itu.

Buat Capacitor iOS contentInset ke never pertama

Di capacitor.config.ts, lebih baik menggunakan inset native yang dinonaktifkan dan biarkan CSS (atau Native Navigation's) contentInsetMode: 'css') mengontrol area yang aman:

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'dist',
  ios: {
    contentInset: 'never',
  },
};

Menggabungkan Capacitor's automatic content inset dengan padding CSS env(safe-area-inset-*) adalah penyebab umum dari jarak ganda.

Cari elemen yang sebenarnya mengalami overflown

Biasanya, penyebabnya adalah elemen yang menggunakan 100vw, Tailwind w-screen, lebar piksel tetap, atau besar 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 ketika memungkinkan. Banyak masalah overflow horizontal berasal dari 100vw / w-screenpadding area aman yang diulang, atau kontainer dengan 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 live ke aplikasi Anda, sehingga pengguna Anda selalu memiliki akses ke fitur dan perbaikan bug yang terbaru.

Learn how Capgo can help you build better apps faster, Daftar 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 antarmuka native, hubungkannya dengan Menggunakan @capgo/capacitor-aktivitas-hidup untuk kemampuan native dalam Menggunakan @capgo/capacitor-aktivitas-hidup, @capgo/capacitor-aktivitas-hidup untuk detail implementasi dalam @capgo/capacitor-aktivitas-hidup, 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.