跳过主要内容
CapgoLogo
教程

使用 Vue 和 Capacitor 构建移动应用

了解如何使用 Vue、Capacitor 和可选地增强 Capgo Native Navigation、Transitions 和 iOS 布局最佳实践创建移动应用

马丁·多纳迪厄

马丁·多纳迪厄

内容营销人员
使用 Vue 和 Capacitor 构建移动应用

在本教程中，我们将指导您将 Vue 网站应用转换为使用 Capacitor 的原生移动应用。您还可以添加 Capgo Native Navigation 和 Transitions 以获得原生移动体验，并使用 tailwind-capacitor 来安全区域

关于 Capacitor

Capacitor 是一个改变游戏规则的工具，它使您能够轻松将其集成到任何 web 项目中，并将应用转换为原生移动应用。它为您生成原生 Xcode 和 Android Studio 项目，并提供通过 JavaScript 桥访问原生设备功能，如相机的访问

准备您的 Vue 应用

首先，通过运行以下命令创建一个新的 Vue 应用：

vue create my-app
cd my-app
npm install

为了让您的 Vue 应用准备好用于原生移动部署，您需要导出您的项目。 在您的 package.json 文件中添加一个脚本来构建和复制 Vue 项目：

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

运行命令后，您应该在项目根目录中看到一个新的 build 文件夹。 这个文件夹将由 __CAPGO_KEEP_0__ 后续使用。 dist 将 Capacitor 添加到您的 Vue 应用中

Adding Capacitor to Your Vue App

安装 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 作为开发依赖项，并在您的项目中设置它。 在设置过程中，接受默认的名称和包 ID 值。

  1. 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.

  2. 添加平台，并 __CAPGO_KEEP_0__ 将为每个平台在您的项目根目录中创建文件夹：

  3. Install the Capacitor __CAPGO_KEEP_1__ as a development dependency and set it up within your project. Accept the default values for name and bundle ID during the setup.

# 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

You should now see new iOS 和 android 文件夹在您的Vue项目中。

更新 capacitor.config.json 文件，指向您的构建命令的结果： 现在，您可以构建您的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 sync

__CAPGO_KEEP_0__

为了开发iOS应用，需要安装Xcode，开发Android应用需要安装Android Studio。另外，需要在Apple Developer Program中注册以便于在iOS上发布应用，同样需要在Google Play Console中注册以便于在Android上发布应用。

使用Capacitor和CLI来打开两个本机项目：

npx cap open ios
npx cap open android

使用Android Studio或Xcode将应用部署到连接的设备上。

Capacitor实时重载

在移动设备上启用实时重载，通过让Capacitor应用从网络上的特定URL加载内容。

找到本地IP地址并更新 capacitor.config.ts 文件，确保IP和端口正确：

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;

将这些更改复制到本机项目中：

npx cap copy

现在，应用将自动重载并显示更新的Vue应用内容。

使用Capacitor插件

安装一个Capacitor插件，例如分享插件，并在Vue应用中使用它：

npm i @capacitor/share

导入包并调用 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 下一步，您可以通过使用__CAPGO_KEEP_0__导航和过渡来使应用程序在iOS和Android上感觉更原生，并解决常见的iOS布局问题，例如水平溢出或裁切安全区域。

npx cap sync

原生感知UI使用Capgo原生导航和过渡

Native-feeling UI with Capgo Native Navigation and Transitions

使用Ionic 来构建跨平台应用程序，但将其与Vue集成时需要hack并且很少值得一试，尤其是当您已经有 Tailwind CSS 在Vue + __CAPGO_KEEP_0__应用程序中实现原生移动感知UI时，使用__CAPGO_KEEP_1__插件而不是仅限Web的UI套件，如Konsta UI：.

@Capacitor/Capgo-native-navigation

开始一个：

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

配缩给子算言纷为子算言纷的尾为子算言纷：

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

导航一个答以尾端给算言纷为子算言纷的尾为子算言纷：

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>

导航答以尾端给算言纷。 cap-router-outlet, cap-page导航答以尾端给算言纷。 cap-content导航答以尾端给算言纷。 setDirection('forward') 导航答以尾端给算言纷。 setDirection('back') 导航答以尾端给算言纷。

导航答以尾端给算言纷。 使用 @capgo/capacitor-native-navigation 和 使用 @capgo/capacitor-transitions.

安全区域使用 Tailwind

在 Tailwind CSS 中使用设备安全区域，请使用 @capgo/tailwind-capacitor (已发布在 tailwind-capacitor npm）上。它提供 safe-areas Tailwind 的实用程序和其他 Capacitor-友好 Tailwind 插件：

bun add -D tailwind-capacitor

在 src/assets/main.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

使用实用程序，如 pt-safe, pb-safe, 和 px-safe 而不是手动添加。该项目正在积极开发中 — 如果您的 Vue 设置中缺少某些功能, env(safe-area-inset-*) 在 __CAPGO_KEEP_0__ 上打开一个 PR open a PR on GitHub.

如果内容在 iOS 上被裁切、偏移或水平滚动,添加更多

或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。 overflow-x: hidden 确保视口元标签正确应用

在

添加视口元标签 index.html 内部 <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

仅从根包装器中处理 iOS 安全区域

创建一个单独的应用程序 shell 并在其中应用安全区域填充 — 不要在多个嵌套组件中:

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);
}

将所有页面内容包装在内部 .app-shell. 重复的安全区域填充在标题、模态和布局包装中经常会使 UI 看起来被裁剪或过大。

使用 @capgo/tailwind-capacitor,您可以使用类似于 pt-safe pb-safe px-safe 的工具来表示相同的填充。

Set Capacitor iOS contentInset 设置__CAPGO_KEEP_0__ iOS never 为

首选 capacitor.config.ts在 contentInsetMode: 'css',优先使用原生 inset 禁用并让 CSS (或 Native Navigation 的

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-*) 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, 重复的安全区域填充, 或固定宽度容器 —— 不是来自视口元标签本身。

结论

Capacitor 是基于现有 web 项目构建原生应用的绝佳选择。通过添加 Capgo, 即使更容易为您的应用添加实时更新, 确保您的用户始终可以访问最新的功能和 bug 修复。

了解如何让 Capgo 帮助您更快地构建更好的应用程序 注册免费账户 今天。

继续使用 Vue 和 Capacitor 构建移动应用

如果您正在使用 使用 Vue 和 Capacitor 构建移动应用 来规划原生媒体和界面行为，连接它与 使用 @capgo/capacitor-live-activities 为使用 @capgo/capacitor-live-activities 的原生能力 @capgo/capacitor-live-activities 为 @capgo/capacitor-live-activities 的实现细节 使用 @capgo/capacitor-video-player 使用 @capgo/capacitor-video-player 的原生能力 @capgo/capacitor-video-player 使用 @capgo/capacitor-video-player 的实现细节 使用 @capgo/capacitor-native-navigation 使用 @capgo/capacitor-native-navigation 的原生能力

Capacitor 实时更新

当 web 层面 bug 活跃时，通过 Capgo 将修复推送到用户，而不是等待几天的应用商店审批。用户在后台接收更新，而本机更改保持在正常审批路径中。

立即开始

最新博客

Capgo 为您提供创建真正专业移动应用所需的最佳见解。

Capacitor 应用中的双向通信
开发 移动 +1
2025 年 4 月 26 日

Capacitor 应用中的双向通信

5种避免OTA更新的常见错误
开发 安全 +1
2025年4月13日

5种避免OTA更新的常见错误

移动应用程序实时更新的5种安全最佳实践
开发 移动 +1
2025年1月14日

移动应用程序实时更新的5种安全最佳实践

查看所有博客文章