使用Capacitor实现实时更新的移动应用开发，Quasar和Capacitor。

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

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

本教程将指导您完成整个过程，首先使用新Quasar应用程序，然后将Capacitor整合到移动应用程序中。另外，您还将使用 Capgo 来在几秒钟内向您的应用程序发送实时更新。

关于Capacitor

CapacitorJS确实是一个游戏改变者！您可以轻松将其整合到任何Web项目中，它将您的应用程序包装在一个本机Webview中，生成Xcode和Android Studio项目，并且其插件提供访问本机设备功能的JS桥，如摄像头。

使用Capacitor，您可以获得一个没有复杂设置或陡峭学习曲线的精美本机移动应用程序。其薄API和流线化功能使其轻松地与您的项目集成。相信我，您将惊讶于如何轻松地使用Capacitor实现一个功能齐全的本机应用程序！

准备Quasar应用程序

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

npm init quasar

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

为了创建一个本机移动应用程序，我们需要一个 export 我们的项目中将包含一个简单的脚本， package.json 中可以轻松地使用它来构建和复制Quasar项目：

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

执行命令后， generate你应该能够在项目根目录看到一个新的 dist 文件夹。

这个文件夹将在后续步骤中被Capacitor使用，但现在我们需要正确地设置它。

将Capacitor添加到Quasar App中

为了将任何web应用打包到原生移动容器中，我们需要遵循一些初始步骤，但之后只需执行一个 sync 命令就可以了。

首先，我们可以安装 Capacitor CLI 作为开发依赖项，并在我们的项目中设置它。在设置过程中，您可以按“回车”键以接受名称和捆绑ID的默认值。

接下来，我们需要安装核心包和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

到目前为止，您应该能够在Quasar项目中观察到新的 ios 和 android 文件夹。这些是真正的本机项目！

稍后要访问Android项目，您必须安装

Android Studio Initialize __CAPGO_KEEP_0__. For iOS, you need a Mac and should install Xcode.

另外，您应该找到一个 capacitor.config.ts file in your project, which contains some fundamental Capacitor settings utilized during the sync. The only thing you need to pay attention to is the __CAPGO_KEEP_0__设置，在同步过程中使用。您需要注意的是

webDir capacitor.config.json 为了纠正这个问题，请打开 __CAPGO_KEEP_0__.config.json:

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

文件并更新

npm run generate
npx cap sync

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

此外，同步命令可能会更新原生平台并安装插件，因此当您安装新的 Capacitor 插件 时，需要重新运行 npx cap sync 命令。

您可能没有注意到，但您现在实际上已经完成了，所以让我们在设备上查看应用！

构建和部署原生应用

为了开发 iOS 应用，您需要安装 Xcode ，而为了开发 Android 应用，您需要安装 Android Studio 已安装。另外，如果您打算在应用商店上发布您的应用程序，则需要为iOS和Android分别在Apple Developer Program和Google Play Console中注册。

如果您是native移动开发的新手，可以使用Capacitor和CLI轻松打开两个native项目：

npx cap open ios
npx cap open android

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

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

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

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

Capgo Live Update

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

在Quasar应用中集成Capgo是一个简单的过程，能够让您充分利用实时更新的能力。这个一步一步的指南将带您完成Capgo实时更新的集成和实现，帮助您实现无缝更新。

注册并访问Capgo控制台:

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

安装Capgo SDK:

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

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

然后将code添加到您的应用中，作为CodePush的替代品：

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

CapacitorUpdater.notifyAppReady()

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

登录Capgo CLOUD:

首先使用 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 如果构建存在。

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

Make channel default:

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

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

Configure app to validate updates:

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

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

CapacitorUpdater.notifyAppReady()

Then do a npm run build && npx cap copy 来更新您的应用程序。

Receive a Live Update:

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

  npx cap run [ios | android]

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

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

使用Capacitor插件

让我们看看如何使用一个 Capacitor 插件的实例，这个我们之前提到过几次。要做到这一点，我们可以通过运行：

npm i @capacitor/share

没有什么高深的关于 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

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

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

原生感知 UI 与 Capgo 原生导航和过渡

我已经与 __CAPGO_KEEP_0__ 工作了多年 Ionic 为了构建跨平台应用，但将其与 Quasar 集成起来是hacky的，并且当你已经有了 Tailwind CSS.

在 Quasar + Capacitor 应用中，为了获得原生移动的感觉，使用 Capgo 插件而不是像 Konsta UI 这样的仅限 web 的 UI 套件:

• @capgo/capacitor-native-navigation — 原生导航栏，iOS 上的 Liquid Glass tab bar，Android 上的模糊 tab bar 风格。你的 Quasar 路由器保持了路由状态；插件拥有原生浏览器。
• @capgo/capacitor-transitions — 在 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 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头部或底部。 Using @capgo/capacitor-native-navigation 使用@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-原生导航 Using @capgo/capacitor-transitions.

使用@__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-过渡

安全区域与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-*) 代替手动 open a PR on GitHub.

在 __CAPGO_KEEP_0__ 上打开一个 PR

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在头部、模态对话框和布局包装器中重复的安全区域填充通常会使UI看起来被裁剪或过大。

使用 @capgo/tailwind-capacitor,您可以使用类似 pt-safe pb-safe px-safe 在单个外壳中表达相同的填充。

设置Capacitor iOS contentInset 首先 never In

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

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) 找到真正溢出的元素

通常的原因是使用

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

In Safari Web Inspector, run:

[...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 with w-full 当出现水平溢出问题时，通常是因为 100vw / w-screen、重复的安全区域填充或固定宽度容器 — 而不是viewport meta标签本身。

结论

Capacitor 是基于现有web项目构建原生应用的优秀选择，提供了一个简单的方式来共享 code 并保持一致的UI。

并且，通过添加 Capgo”，您可以更轻松地为应用添加实时更新，确保您的用户始终可以访问最新的功能和修复。如果您想学习如何将 __CAPGO_KEEP_0__ 添加到您的Next.js应用中，请查看下一篇文章：

从创建具有实时更新的移动应用开始，Quasar和 Capgo。

Keep going from Creating Mobile Apps with live updates, Quasar and Capacitor.

__CAPGO_KEEP_0__ 使用 Quasar 和 Capacitor 创建移动应用，实时更新。 为原生插件工作做计划，连接它到 Capgo 插件目录 在 Capgo 插件目录中， Capacitor 插件由 Capgo 提供 在 Capacitor 插件由 Capgo 中， 添加或更新插件 在添加或更新插件中， Ionic Enterprise 插件替代品 在 Ionic Enterprise 插件替代品中， Capgo 原生构建 在 Capgo 原生构建中，