使用实时更新、Quasar 和 Capacitor 创建移动应用。

在本教程中，我们将从创建一个新的 Web 应用开始，使用 Quasar。稍后，我们将学习如何将其转换为移动应用，使用 Capacitor。如果您想让您的应用在移动设备上看起来更好。

使用 Capacitor，您可以将 Quasar Web 应用转换为移动应用，无需进行大量繁琐的工作或学习一种全新的应用开发方式，如 React Native。

本教程将指导您完成整个过程，首先是创建一个新的 Quasar 应用，然后将 Capacitor 整合到移动应用中。另外，您还将使用 Capgo 秒内将live update发送到您的应用程序。

关于Capacitor

CapacitorJS确实是一个革命性的产品！您可以轻松将其整合到任何Web项目中，它将您的应用程序包装在一个本机Webview中，生成Xcode和Android Studio项目。其插件还提供了通过JS桥接访问本机设备功能的能力，如摄像头。

With Capacitor, you get a fantastic native mobile app without any complicated setup or steep learning curve. Its slim API and streamlined functionality make it a breeze to integrate into your project. Trust me, you’ll be amazed at how effortless it is to achieve a fully functional native app with Capacitor!

准备您的Quasar应用程序

要创建一个新的Quasar应用程序，请运行以下命令：

npm init quasar

选择“Quasar应用程序CLI”选项，然后选择“Quasar v2”。

为了创建一个本机移动应用程序，我们需要导出我们的项目。因此，让我们在我们的项目中添加一个简单的脚本。 导出 导出我们的项目 package.json 用于构建和复制 Quasar 项目的包:

{
  "scripts": {
    // ...
    "build": "quasar build"
  }
}

执行命令后 generate你应该能够在项目根目录看到一个新的 dist 这个文件夹将由 __CAPGO_KEEP_0__ 后续使用，但现在我们必须正确设置它。

将 Capacitor 添加到 Quasar 应用程序中

在您的 Quasar 应用程序中添加 Capacitor

首先，我们可以将 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 安装为开发依赖项，然后在项目中设置它。在设置过程中，您可以按“回车”键以接受名称和包 ID 的默认值。 sync package.json

用于构建和复制 Quasar 项目的包: Capacitor CLI 你应该能够在项目根目录看到一个新的

接下来，我们需要安装核心包和针对iOS和Android平台的相关包。

最后，我们可以添加平台，Capacitor会在项目根目录创建每个平台的文件夹：

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your Quasar 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 和 android 文件夹在您的Quasar项目中。

这些是真正的本机项目！

要访问Android项目，必须安装 安卓Studio。对于iOS，需要Mac，并且应该安装 Xcode.

另外，您应该找到一个 capacitor.配置文件 项目中找到一个文件，包含一些基本的Capacitor设置，用于同步过程。您需要注意的是 webDir,必须指向您的构建命令的结果。当前它是不准确的。

为了解决这个问题，请打开 capacitor.配置文件 文件并更新 webDir:

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

您可以通过执行以下命令来尝试它:

npm run generate
npx cap sync

第一个命令 npm run generate 会简单地构建您的 Quasar 项目并复制静态构建，而第二个命令 npx cap sync 会同步所有 web code 到原生平台的正确位置，以便在应用中显示。

此外，同步命令可能会更新原生平台并安装插件，因此当您安装新 Capacitor 插件 context npx cap sync again.

它的时间

再次运行。

没有注意到，您现在实际上已经完成了，所以让我们在设备上看看应用! 构建和部署原生应用 为了开发 iOS 应用，您需要安装 Xcode 已安装。另外，如果您打算在应用商店上发布您的应用程序，则需要在 iOS 中注册 Apple Developer Program，在 Android 中注册 Google Play Console。

如果您是新手，想开始native移动开发，可以使用Capacitor CLI轻松打开native项目。

npx cap open ios
npx cap open android

设置好原生项目后，部署应用程序到连接设备很容易。在 Android Studio 中，只需等待所有内容就绪，然后您可以在不更改任何设置的情况下将应用程序部署到连接设备。以下是示例：

在 Xcode 中，您需要设置签名账户才能将应用程序部署到真实设备，而不是仅在模拟器上运行。如果您以前没有这样做过，Xcode 会指导您完成此过程（但请再次注意，您需要注册开发者计划）。完成后，您可以简单地点击播放以在连接设备上运行应用程序，您可以在顶部选择设备。以下是示例：

恭喜！您已成功将 Quasar web 应用程序部署到移动设备。以下是示例：

但请稍等，开发期间还有更快的方法……

Capgo Live Update

Capgo Live Update 是一个服务，允许开发者在不通过传统应用商店提交过程的情况下部署应用程序更新。这可以是一个方便的方法来快速修复 bug 或对应用程序进行小型更新，而不必等待应用商店的审查过程。

在您的Quasar应用程序中集成Capgo是一个直接的过程，赋予您实时更新的力量。这一步一步的指南将指导您完成Capgo和Live Update的集成和实现，使您能够提供无缝更新。

注册并访问Capgo控制台:

是时候注册并获取您的API密钥来上传您的第一个版本！从 注册一个Capgo账户.

安装CapgoSDK:

从命令行直接在您的Capacitor应用程序的根目录中运行:

npm i @capgo/capacitor-updater && npx cap sync 将插件安装到您的Capacitor应用程序中。

然后将code添加到您的应用程序中，取代CodePush：

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

这将告诉原生插件安装成功。

登录Capgo云:

首先使用 all apikey 在您的帐户中可用以使用 CLI 登录:

`npx @capgo/cli@latest login YOU_KEY`

添加您的第一个应用:

让我们从创建一个 Capgo 云中的应用开始，使用 CLI。

    npx @capgo/cli@latest app add

该命令将使用 Capacitor 配置文件中定义的所有变量来创建应用。

上传您的第一个版本:

运行命令以构建您的 code 并将其发送到 Capgo:

npx @capgo/cli@latest bundle upload`

默认情况下，版本名称将来自您的 package.json 文件。

检查入 Capgo 如果构建存在。

您甚至可以使用我的 移动沙盒应用进行测试.

设为默认频道:

您将应用程序发送到Capgo后，需要将频道设为默认频道，以便应用程序可以从Capgo接收更新。

npx @capgo/cli@latest channel set production -s default

配置应用程序验证更新:

将此配置添加到主JavaScript文件中。

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

然后执行 npm run build && npx cap copy 更新应用程序。

接收Live Update:

为了让您的应用程序从Deploy接收live update，您需要在设备或模拟器上运行应用程序。最简单的方法是使用以下命令在模拟器或连接到计算机的设备上启动本地应用程序。

  npx cap run [ios | android]

打开应用程序，放到后台，然后再次打开它，您应该在日志中看到应用程序已更新。

恭喜！🎉 您已成功部署第一个Live Update。这只是您可以使用Live Updates的开始。要了解更多信息，请查看完整的 Live Updates文档.

使用Capacitor插件

让我们看看如何使用一个 Capacitor 插件的实例，之前我们提到过几次。要实现这一点，我们可以通过运行以下命令来安装一个相当简单的插件：

npm i @capacitor/share

没有什么特别的关于 " 分享插件"",但是它仍然会弹出原生分享对话框！为了实现这一点，我们现在只需要导入包并从我们的应用中调用相应的 share() 函数，所以让我们修改 pages/index.vue" 文件到如下内容：

<template>
  <div>
    <h1>Welcome to Quasar 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>

如前所述，当安装新插件时，我们需要执行同步操作，然后重新部署应用到设备上。要实现这一点，请运行以下命令：

npx cap sync

点击按钮后，您可以亲眼目睹美丽的原生分享对话框!

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

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

我已经与 ionic 构建跨平台应用程序，但将其与Quasar集成起来很hacky，并且当您已经有 Tailwind CSS.

在Quasar + Capacitor应用程序中获得原生移动体验，使用Capgo插件而不是仅限Web的UI套件，如Konsta UI:

• @capgo/capacitor原生导航 —原生导航栏、Liquid Glass iOS标签栏和Android模糊标签栏样式。您的Quasar路由器保留路由状态；插件拥有原生浏览器。
• @capgo/capacitor-过渡效果 —在WebView层中实现Ionic样式页面过渡和iOS边缘滑动返回，且不采用Ionic UI。

安装它们:

npm add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npmx cap sync

配置原生导航栏的CSS inset模式，以便Web内容尊严原生导航栏:

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

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

渲染Liquid Glass标签栏（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') 在导航之前。请勿在原生导航拥有这些表面的情况下重复网页头部或底部。

在导航之前 使用@capgo/capacitor原生导航 and 使用@capgo/capacitor过渡.

使用@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

安全区域使用Tailwind @capgo/Tailwind-capacitor （发布于“ tailwind-capacitor 在 npm 上。它提供了 safe-areas 工具和其他 Capacitor 友好的 Tailwind 插件：

npm add -D tailwind-capacitor

在 src/css/app.scss:

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

使用工具，如 pt-safe, pb-safe，和 px-safe 代替手动添加 env(safe-area-inset-*) 。该项目正在积极开发中 — 如果您的 Quasar 设置中缺少某些内容，请在 __CAPGO_KEEP_0__ 上 在GitHub上提交一个PR.

如果内容看起来被裁剪、偏移或水平滚动在 iOS 上，仅添加或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。

修复 iOS 布局问题（视口、安全区域和水平溢出） overflow-x: hidden 如果内容看起来被裁剪、偏移或水平滚动在 iOS 上，仅添加或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。

确保视口元标签正确应用

在 index.html (或您的Quasar HTML模板) <head>:

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

设置视口元标签

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

html,
body,
#q-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 ，您可以使用类似于

设置Capacitor iOS contentInset 前往 never 首先

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

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'dist/spa',
  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 项目构建原生应用的优秀选择，提供了一个简单的方式来共享 code 并保持一致的 UI。

并且通过添加 Capgo，即使是添加实时更新到您的应用中，也变得更加容易，从而确保您的用户始终可以访问最新的功能和 bug 修复。

如果您想学习如何将 Capgo 添加到您的 Next.js 应用中，请查看下一篇文章：

继续阅读 Creating Mobile Apps with 实时更新，Quasar 和 Capacitor。

如果您正在使用 使用 Capacitor 和 Quasar 创建移动应用，支持实时更新。 为了规划原生插件的工作，连接它与 Capgo 插件目录 在 Capgo 插件目录中了解产品工作流程 Capacitor 插件由 Capgo 提供 了解在 Capacitor 插件由 Capgo 提供中的实现细节 添加或更新插件 了解在添加或更新插件中的实现细节 Ionic Enterprise 插件的替代方案 了解在 Ionic Enterprise 插件的替代方案中的产品工作流程 Capgo 原生构建 了解在 Capgo 原生构建中的产品工作流程