使用Vue和Capacitor构建移动应用

In 这个教程中，我们将指导您完成将 Vue 网页应用程序转换为原生移动应用程序的过程使用 Capacitor。您还可以添加 Capgo 原生导航和过渡效果，使用 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 应用程序中

Capacitor 是一个颠覆性的工具，允许您轻松将其集成到任何 web 项目中，并将应用程序转换为原生移动应用程序。它为您生成原生 Xcode 和 Android Studio 项目，并提供通过 JavaScript 桥访问原生设备功能，如相机。

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

安装 Capacitor CLI 作为开发依赖项，并在您的项目中设置它。接受名称和包 ID 的默认值以完成设置。
安装核心包和 iOS 和 Android 平台的相关包。
添加平台，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 和 android 文件夹。

更新 capacitor.config.json 文件以指向 webDir 到构建命令的结果:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

现在，您可以构建您的Vue项目并将其同步到Capacitor:

npm run build
npx cap sync

构建和部署原生应用

要开发iOS应用，您需要安装Xcode，并且要开发Android应用，您需要安装Android Studio。此外，您需要在Apple Developer Program中注册以在App Store上发布iOS应用，并在Google Play Console中注册以在Google Play Store上发布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 命令并将应用程序重新部署到设备：

npx cap sync

接下来，您可以使应用程序在 iOS 和 Android 上感觉更原生，使用 Capgo 导航和过渡，修复常见的 iOS 布局问题，导致水平溢出或裁剪安全区域。

我已经工作了几年， Ionic 来构建跨平台应用程序，但将其与 Vue 集成是hacky的，并且在您已经有它的情况下很少值得。 Tailwind CSS.

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

@capgo/capacitor-native-navigation — 原生导航栏、iOS Liquid Glass tab bar 和 Android 模糊 tab bar 风格。您的 Vue 路由器保留路由状态；插件拥有原生浏览器。
@capgo/capacitor-transitions — 在 WebView层中实现Ionic样式页面过渡和iOS边缘滑动返回，且不采用Ionic 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 bar（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-原生导航和使用 @capgo/capacitor-过渡.

安全区域与 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-*) 而不是手动添加。该项目正在积极开发中—if 您的 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" />

只需从一个根包装器中处理 iOS 安全区域

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

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` 设置为

In capacitor.config.ts, 优先使用原生 inset 并让 CSS (或 Native Navigation) 控制安全区域： contentInsetMode: 'css'混合 __CAPGO_KEEP_0__ 自动内容 inset 与 CSS

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-*) 找到真正溢出的元素

通常的罪魁祸首是使用

, Tailwind 100vw, 固定像素宽度或较大的 w-screen在 Safari Web Inspector 中运行： min-width.

使用 Tailwind，替换

[...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,
  }));

为 w-screen with w-full 当可能时。许多水平溢出问题来自 100vw / w-screen，重复的安全区域填充或固定宽度容器 — 而不是来自视口元标签本身。

结论

Capacitor 是基于现有 Web 项目构建原生应用的绝佳选择。通过添加 Capgo，甚至更容易将实时更新添加到您的应用中，从而确保您的用户始终可以访问最新的功能和 bug 修复。

了解如何使用 Capgo 构建更好的应用更快注册免费账户今天。

继续 Building Mobile Apps with Vue 和 Capacitor

如果您正在使用 Building Mobile Apps with Vue 和 Capacitor 来规划原生媒体和界面行为，连接它与使用 @capgo/capacitor-live-activities For native capability in Using capgo/capacitor-live-activities, capgo/capacitor-live-activities For implementation detail in capgo/capacitor-live-activities, Using capgo/capacitor-video-player For native capability in Using capgo/capacitor-video-player, capgo/capacitor-video-player For implementation detail in capgo/capacitor-video-player, and Using capgo/capacitor-native-navigation For native capability in Using capgo/capacitor-native-navigation.

使用Vue和Capacitor构建移动应用

关于 Capacitor

为 Vue 应用程序做准备

Capacitor 是一个颠覆性的工具，允许您轻松将其集成到任何 web 项目中，并将应用程序转换为原生移动应用程序。它为您生成原生 Xcode 和 Android Studio 项目，并提供通过 JavaScript 桥访问原生设备功能，如相机。

构建和部署原生应用

Capacitor实时重载

使用 Capacitor 插件

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

安全区域与 Tailwind

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

确保视口元标签正确应用

只需从一个根包装器中处理 iOS 安全区域

Set Capacitor iOS contentInset 将__CAPGO_KEEP_0__ iOS never 设置为

通常的罪魁祸首是使用

结论

继续 Building Mobile Apps with Vue 和 Capacitor

Set Capacitor iOS `contentInset` 将__CAPGO_KEEP_0__ iOS `never` 设置为