이 튜토리얼에서는 Vue 웹 애플리케이션을 native 모바일 앱으로 변환하는 과정을 안내합니다. Capacitor를 사용하여 native 모바일 앱을 만들 수 있습니다. 또한 Capgo Native Navigation 및 Transitions를 추가하여 native 모바일 느낌을 줄 수 있고, tailwind-capacitor를 사용하여 안전한 영역을 사용할 수 있습니다.
Capacitor에 대해 알아보세요
Capacitor는 웹 프로젝트에 쉽게 통합할 수 있는 게임 체이닝 도구입니다. Capacitor를 사용하여 애플리케이션을 native 모바일 앱으로 변환할 수 있습니다. 또한 native Xcode 및 Android Studio 프로젝트를 생성하고 native 장치 기능에 접근할 수 있습니다.
Vue 앱 준비
첫 번째로, Vue 앱을 생성하기 위해 다음 명령어를 실행하세요:
vue create my-app
cd my-app
npm install자연스러운 모바일 배포를 위해 Vue 앱을 준비하려면 프로젝트를 내보내야 합니다. package.json 파일에 스크립트를 추가하여 Vue 프로젝트를 빌드하고 복사하세요: package.json 명령어를 실행한 후 프로젝트의 루트 디렉토리에 새로운 폴더가 생성되어야 합니다. 이 폴더는 __CAPGO_KEEP_0__에 의해 나중에 사용됩니다.
{
"scripts": {
// ...
"build": "vue-cli-service build"
}
}__CAPGO_KEEP_0__를 Vue 앱에 추가하기 build __CAPGO_KEEP_0__를 사용하여 웹 앱을 모바일 컨테이너로 변환하려면 다음 단계를 따르세요: dist Capacitor __CAPGO_KEEP_1__을 개발 의존성으로 설치하고 프로젝트 내에서 설정하세요. 이름과 번들 ID에 대한 기본값을 수락하세요.
Capacitor의 핵심 패키지와 iOS 및 Android 플랫폼에 대한 관련 패키지를 설치하세요.
__CAPGO_KEEP_0__를 추가하고, __CAPGO_KEEP_0__는 프로젝트의 루트 디렉토리에 각 플랫폼에 대한 폴더를 생성합니다:
-
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.
-
__CAPGO_KEEP_1__
-
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 android이제 새로운 iOS 및 안드로이드 폴더를
Vue 프로젝트 capacitor.config.json __CAPGO_KEEP_0__ 빌드 명령어의 결과로 Vue 프로젝트를 빌드하고 __CAPGO_KEEP_0__와 동기화할 수 있습니다.
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Now, you can build your Vue project and sync it with Capacitor:
npm run build
npx cap syncBuild and Deploy Native Apps
iOS 앱을 개발하려면 Xcode가 설치되어 있어야 하며 Android 앱을 개발하려면 Android Studio가 설치되어 있어야 합니다. 또한 iOS는 Apple Developer Program에, Android는 Google Play Console에 등록하여 앱 스토어에 앱을 배포해야 합니다.
Capacitor CLI을 사용하여 두 개의 네이티브 프로젝트를 열 수 있습니다.
npx cap open ios
npx cap open androidAndroid Studio 또는 Xcode를 사용하여 앱을 연결된 기기에서 배포합니다.
Capacitor Live Reload
네이티브 앱이 특정 네트워크 URL에서 콘텐츠를 로드하도록 Capacitor 앱을 통해 모바일 기기에서 라이브 리로드를 활성화합니다.
로컬 IP 주소를 찾고 파일에 올바른 IP 주소와 포트를 업데이트하십시오: capacitor.config.ts 이 변경 사항을 적용하려면 네이티브 프로젝트에 복사하십시오:
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;Vue 앱을 업데이트하면 앱이 자동으로 리로드되고 변경 사항을 표시합니다.
npx cap copy__CAPGO_KEEP_0__ 플러그인을 설치하고, 예를 들어 공유 플러그인을 설치하여 Vue 앱에서 사용하십시오:
Capacitor 패키지를 임포트하고 함수를 호출하십시오:
Capacitor
npm i @capacitor/share__CAPGO_KEEP_1__ share() 애플리케이션 내에서 함수:
<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>새 플러그인을 설치한 후 다음 명령어를 실행하고 애플리케이션을 다시 장치에 배포하세요: sync 애플리케이션을 다시 장치에 배포한 후 다음 명령어를 실행하세요:
npx cap sync다음으로, iOS 및 Android에서 애플리케이션에 더 원생스러운 UI를 제공하기 위해 Capgo 네비게이션 및 전환을 사용하고, 수평 스크롤이나 안전 영역이 잘려나가는 문제를 해결하세요.
원생스러운 UI를 위한 Capgo 네이티브 네비게이션 및 전환
여러 해 동안 Ionic을 사용하여 크로스 플랫폼 애플리케이션을 개발해 왔습니다. 그러나 Vue와 통합하는 것은 Ionic을 사용하는 것보다 Vue와 Tailwind CSS를 사용하는 것이 더 좋습니다. Vue + __CAPGO_KEEP_0__ 애플리케이션에서 원생스러운 모바일 UI를 제공하기 위해, 웹 전용 UI 키트인 Konsta UI 대신 __CAPGO_KEEP_1__ 플러그인을 사용하세요: __CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation — iOS에서 Liquid Glass 탭바 스타일, Android에서 흐린 탭바 스타일, 네이티브 네비게이션 바를 사용하세요. Vue 라우터는 라우트 상태를 유지하고 플러그인은 네이티브 창을 관리합니다..
For a native mobile feel in a Vue + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- @capgo/capacitor-native-navigation Tailwind CSS
- @capgo/capacitor-transition — iOS와 Android에서 WebView layer에서 Ionic-style 페이지 전환 및 iOS edge swipe-back을 사용할 수 있습니다. Ionic UI를 채택하지 않습니다.
설치 BOTH:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync자연스러운 네이티브 네비게이션을 위해 CSS inset 모드를 구성하여 웹 콘텐츠가 네이티브 바를 존중합니다:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});리퀴드 글라스 탭 바를 렌더링합니다 (iOS는 시스템 소유 렌더링을 사용하고 Android는 흐린 WebView 배경을 사용합니다):
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}`);
});네이티브 페이지 전환을 앱 셸에 추가합니다:
<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>페이지를 wrapping하는 cap-router-outlet, cap-page그리고 cap-content또는 setDirection('forward') 또는 setDirection('back') 또는
또는 Using @capgo/capacitor-native-navigation 및 Using @capgo/capacitor-transitions.
Tailwind에서 안전한 영역
Tailwind CSS에서 장치 안전 영역을 사용하려면 @capgo/tailwind-capacitor Tailwind CSS에서 tailwind-capacitor on npm). It provides safe-areas utilities and other Capacitor-friendly Tailwind plugins:
bun add -D tailwind-capacitorTailwind CSS의 유용한 기능 src/assets/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";, 및 pt-safe, pb-safeCapacitor-친화적인 Tailwind 플러그인 px-safe 대신 뿌려주지 말고 env(safe-area-inset-*) 수동으로 뿌려주지 말고. 이 프로젝트는 활발하게 개발되고 있으니, Vue 설정에 필요한 것이 빠진 경우 GitHub 에 PR을 열어보세요.
iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤)
iOS에서 콘텐츠가 잘려나거나-shifted되거나 가로 스크롤이 가능하다면, 뷰포트 태그만 추가하거나 조정하는 것만으로는 해결되지 않습니다. 이 순서대로 체크해 보세요. overflow-x: hidden 뷰포트 메타 태그가 올바르게 적용되어 있는지 확인하세요
뷰포트 메타 태그를 추가하세요
내부에 index.html iOS 안전 영역을 하나의 루트 wrapper에서만 처리하세요 <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />싱글 앱 셸을 생성하고 안전 영역 패딩을 적용하세요 — 여러 개의 중첩된 컴포넌트에서만 적용하지 마세요:
모든 페이지 콘텐츠를 내부에 wrapping하세요
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);
}Wrap all page content inside .app-shell. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 적용되어 UI가 잘린 것처럼 보이거나 너무 크게 보이는 문제가 있습니다.
With @capgo/tailwind-capacitor, __CAPGO_KEEP_0__의 유용한 유틸리티를 사용하여 동일한 패딩을 표현할 수 있습니다. pt-safe pb-safe px-safe Set __CAPGO_KEEP_0__ iOS
Set Capacitor iOS contentInset 첫 never In
, 원래의 안전 영역을 비활성화하고 CSS (또는 Native Navigation의) capacitor.config.ts)가 안전 영역을 관리하도록 합니다. contentInsetMode: 'css'Mixing __CAPGO_KEEP_0__의 자동 콘텐츠 인셋과 CSS
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Capacitor env(safe-area-inset-*) padding은 일반적인 두 줄 간격의 원인입니다.
실제로 넘치는 요소를 찾으세요.
일반적으로 원인은 요소가 사용하는 100vw, Tailwind w-screen, 고정 픽셀 너비 또는 큰 min-width.
Safari Web Inspector에서 실행하세요:
[...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,
}));Tailwind와 함께 w-screen 가능한 경우 w-full 수평 방향으로 넘치는 문제의 많은 경우는 100vw / w-screen, duplicated safe-area padding, 또는 고정 너비 컨테이너 — viewport meta 태그 자체에서부터가 아니라.
결론
Capacitor은 기존 웹 프로젝트에 기반한 네이티브 애플리케이션을 빌드하는 데 훌륭한 옵션입니다. Capgo을 추가함으로써, 앱에 실시간 업데이트를 추가하는 것이 thậm chí 더 쉬워졌습니다. 사용자들이 항상 최신 기능과 버그 수정에 접근할 수 있도록 보장합니다.
Capgo을 사용하여 더 나은 앱을 더 빠르게 빌드하는 방법을 알아보세요. 무료 계정으로 가입하세요. 오늘.
Vue와 Capacitor을 사용하여 모바일 앱을 계속 빌드하세요.
Vue와 __CAPGO_KEEP_0__을 사용하는 경우 native 미디어 및 인터페이스 동작을 계획하는 데 사용하는 경우 Capacitor와 함께 연결하세요. __CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activities를 사용하여 native 기능을 연결하세요. capgo/capacitor-live-activities capgo/capacitor-live-activities capgo/capacitor-video-player를 사용하여 capgo/capacitor-live-activities의 구현 세부 정보를 연결하세요. capgo/capacitor-live-activities를 사용하여 capgo/capacitor-live-activities의 native 기능을 연결하세요. capgo/capacitor-live-activities Capgo의 원시 기능을 사용하는 @capgo/capacitor-video-player @capgo/capacitor-video-player Capgo의 구현 세부 정보를 사용하는 @capgo/capacitor-video-player, 그리고 Capgo의 원시 기능을 사용하는 @capgo/capacitor-native-navigation Capgo의 원시 기능을 사용하는 @capgo/capacitor-native-navigation.
