使用 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.

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

为 Vue 应用做好准备

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

vue create my-app
cd my-app
npm install

要为原生移动部署做好准备，您需要导出您的项目。将一个脚本添加到您的 文件中，用于构建和复制 Vue 项目： 在运行后

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

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

将 Capacitor 添加到您的 Vue 应用程序

将您的 Vue 网页应用程序转换为原生移动容器，请遵循以下步骤：

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

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

3. 添加平台，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

您现在应该在 Vue 项目中看到新的 iOS 和 安卓 文件夹。

更新 capacitor.配置文件 将 webDir context

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

构建命令的结果:

现在，您可以构建您的 Vue 项目并同步它与 __CAPGO_KEEP_0__:

使用Capacitor和CLI打开本地项目。

npx cap open ios
npx cap open android

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

使用 Capacitor __CAPGO_KEEP_1__ 打开两款原生项目:

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

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

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

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

npm i @capacitor/share

安装新插件后，运行命令并将应用程序重新部署到您的设备： share() 接下来，您可以使应用程序在 iOS 和 Android 上感觉更原生，使用__CAPGO_KEEP_0__导航和过渡，并修复常见的 iOS 布局问题，导致水平溢出或裁切安全区域。

<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__原生导航和过渡创建原生感觉的 UI sync 使用__CAPGO_KEEP_0__原生导航和过渡创建原生感觉的 UI

npx cap sync

使用Capgo原生导航和过渡创建原生感觉的 UI

使用Capgo原生导航和过渡创建原生感觉的 UI

I的工作已经多年了 Ionic 用来构建跨平台应用 但是.

为了在 Vue + Capacitor 应用中实现原生移动体验，使用 Capgo 插件而不是仅限于 web 的 UI 套件，如 Konsta UI。

• @capgo/capacitor-原生导航 并且
• @capgo/capacitor-过渡 Tailwind CSS

在一个Vue + __CAPGO_KEEP_0__应用中

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

为了获得native mobile的感觉

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

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

使用__CAPGO_KEEP_1__插件而不是web-only UI kits like Konsta UI：

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>

在 Vue 移动应用中使用 Capacitor cap-router-outlet, cap-page, 和 cap-content, 并调用 setDirection('forward') 或 setDirection('back') context

HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `alternatives_cta_questions`）。页面/区域：Capacitor live-update 替代方案比较页面。角色：长期营销或法律段落。见于：页面 alternatives.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `alternatives_cta_questions`（替代方案 CTA 问题）。| HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `appflow_cta_questions`）。页面/区域：Appflow 比较/迁移营销复制。角色：长期营销或法律段落。见于：页面 alternatives/ionic-appflow.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `appflow_cta_questions`（Appflow CTA 问题）。| HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `capwesome_cta_questions`）。页面/区域：Capawesome 比较页面。角色：长期营销或法律段落。见于：页面 alternatives/capawesome.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `capwesome_cta_questions`（Capwesome CTA 问题）。| 页面/区域：咨询服务页面。角色：小型 UI 标签或导航项。见于：页面 consulting.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `consulting_faq_subtitle`（咨询 FAQ 副标题）。| 页面/区域：Appflow 比较/迁移营销复制。角色：短 UI 标签或导航项。见于：页面 alternatives/ionic-appflow.astro，页面 ionic-enterprise-plugins.astro，页面 solutions/ionic-enterprise-plugins.astro。消息键 `appflow_plugins_or`（Appflow 插件或）。 使用@capgo/capacitor原生导航 查看完整指南： 使用 @capgo/capacitor-native-navigation.

和

context @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 上，则添加更多

__CAPGO_KEEP_0__ overflow-x: hidden 或调整 viewport 标签通常无法解决问题。按照以下顺序逐步检查。

确保 viewport 元信息标签正确应用

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

With @capgo/Tailwind-capacitor@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ pt-safe pb-safe px-safe ，您可以使用类似于

设置CapacitoriOS contentInset 到 never 首先

在 capacitor.config.ts, 优先使用原生 inset 并让 CSS (或 Native Navigation 的) contentInsetMode: 'css') 来控制安全区域：

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

混合Capacitor的自动内容 inset 与 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 如何帮助您快速构建更好的应用 立即注册免费账户 今天。

继续 Building Mobile Apps with Vue 和 Capacitor

如果您正在使用 使用 Vue 和 Capacitor 构建移动应用 为计划原生媒体和界面行为，连接它 使用 @capgo/capacitor-live-activities 为原生能力在使用 @capgo/capacitor-live-activities @capgo/capacitor-实时活动 为实现细节在 @capgo/capacitor-live-activities 使用 @capgo/capacitor-video-player 为原生能力在使用 @capgo/capacitor-video-player @capgo/capacitor-视频播放器 为实现细节在 @capgo/capacitor-video-player，和 使用 @capgo/capacitor-native-navigation 为原生能力在使用 @capgo/capacitor-native-navigation