跳过主要内容
CapgoLogo
教程

使用 Vue 和 Capacitor 构建移动应用

学习如何使用 Vue、Capacitor 和可选地增强 Capgo 原生导航、过渡和 iOS 布局最佳实践

Martin Donadieu

Martin Donadieu

内容营销人员
使用 Vue 和 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.

关于 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"
  }
}

运行命令后，您应该在项目根目录中看到一个新的文件夹。这个文件夹将由 __CAPGO_KEEP_0__ 后来使用。 build 在 Vue 应用中添加 __CAPGO_KEEP_0__ dist folder in your project’s root directory. This folder will be used by Capacitor later.

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

安装核心包和 iOS 和 Android 平台的相关包。

  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. 您现在应该看到新的

  3. Add the platforms, and Capacitor will create folders for each platform at the root of your project:

# 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

文件夹 文件夹 和 安卓 您的 Vue 项目中的文件夹。

更新 capacitor.config.json 文件指向您的构建命令的结果： 现在，您可以使用 __CAPGO_KEEP_0__ 构建和同步您的 Vue 项目： 构建和部署原生应用

{
  "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__ __CAPGO_KEEP_1__ 打开两个原生项目：

为了开发 iOS 应用，您需要安装 Xcode，并且为了 Android 应用，您需要安装 Android Studio。另外，您需要在 Apple Developer Program 中注册 iOS 和 Google Play Console 中注册 Android 以在应用商店中分发您的应用。

Use the Capacitor CLI to open both native projects:

npx cap open ios
npx cap open android

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

Capacitor 实时重载

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

找到您的本地 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__ 插件

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

Install a Capacitor plugin, such as the Share plugin, and use it in your Vue app:

npm i @capacitor/share

安装新插件后，请运行 share() __CAPGO_KEEP_0__

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

__CAPGO_KEEP_0__ sync command and redeploy the app to your device:

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.

Native-feeling UI with Capgo Native Navigation and Transitions

我已经多年来与 Ionic 一起工作， build cross-platform applications.

For a native mobile feel in a Vue + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

安装双方:

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

使用 CSS inset 模式配置原生导航，以便 web 内容尊严地尊严原生导航条:

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

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

呈现 Liquid Glass tab 条 (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>

将路由页面包裹在 cap-router-outlet, cap-page,和 cap-content,并调用 setDirection('forward') 或 setDirection('back') 在导航之前。不要在原生导航拥有这些表面的情况下重复 web 头部或底部。

参见完整指南: 使用 @capgo/capacitor-native-navigation 和 使用 @capgo/capacitor-transitions.

使用 Tailwind 的安全区域

在使用 Tailwind CSS 设备安全区域时，请使用 @capgo/tailwind-capacitor (已发布于 tailwind-capacitor 在 npm 上发布。它提供 safe-areas 的实用工具和其他 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 代替手动添加 env(safe-area-inset-*) 如果您的 Vue 设置缺少某些内容，项目正在积极开发中 在 GitHub 上打开一个 PR.

修复 iOS 布局问题 (视口、安全区域和水平溢出)

如果 iOS 上的内容被裁剪、偏移或水平滚动，仅添加或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。 overflow-x: hidden 确保视口元标签正确应用

在

内添加视口元标签 index.html 仅从一个根容器中处理 iOS 安全区域 <head>:

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

创建一个单独的应用 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 看起来被裁剪或过大。

With @capgo/tailwind-capacitor,你可以用类似这样的工具来表示相同的填充 pt-safe pb-safe px-safe 在单个shell中

设置Capacitor iOS contentInset 到 never 首先

在 capacitor.config.tsprefer native inset disabled 和让 CSS (或 Native Navigation 的) contentInsetMode: 'css'拥有安全区域：

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

混合Capacitor的自动内容内边距与 CSS env(safe-area-inset-*) 填充是双倍间距的常见原因

找到真正溢出的元素

通常的罪魁祸首是使用 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种安全最佳实践

查看我们的博客中的所有内容