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

In本教程中，我们将从创建一个新的Web应用程序开始 Quasar. Later on, we’ll learn how to turn it into a mobile app using Capacitor. If you want to make your app look better on mobile.

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

本教程将指导您完成整个过程，首先是创建一个新的Quasar应用程序，然后将Capacitor引入到移动应用程序的世界中。此外，您还将使用Capacitor Capgo 关于__CAPGO_KEEP_0__

About Capacitor

使用__CAPGO_KEEP_0__，您可以获得一个功能齐全的本机移动应用程序，无需进行复杂的设置或陡峭的学习曲线。其__CAPGO_KEEP_1__和功能流线化，使其轻松地集成到您的项目中。相信我，您将惊叹于如何轻松地实现一个功能齐全的本机应用程序!

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应用程序，请运行以下命令：

CapacitorJS

npm init quasar

选择“带有 Quasar CLI”选项，然后选择“Quasar v2”。

为了创建一个原生移动应用，我们需要一个 export 项目的 我们的项目中包含一个直接的脚本，以便可以构建和复制 Quasar 项目: 执行命令后，您应该能够在项目根目录看到一个新的

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

文件夹。 generate这个文件夹将由 __CAPGO_KEEP_0__ 后续使用，但现在我们必须正确设置它。 dist 将 __CAPGO_KEEP_0__ 添加到您的 Quasar 应用中

在您的 Quasar 应用中添加 Capacitor

在您的 Quasar 应用中添加 Capacitor

为了将任何Web应用打包到原生移动容器中，我们必须遵循几个初始步骤，但之后只需执行一个命令即可。 sync 首先，我们可以将__CAPGO_KEEP_0__ __CAPGO_KEEP_1__安装为开发依赖项，然后在项目中设置它。在设置过程中，您可以按“回车”键以接受名称和包ID的默认值。

接下来，我们需要安装核心包和iOS和Android平台的相关包。 Capacitor CLI 初始化__CAPGO_KEEP_0__

此时您应该能够观察到新创建的

Finally, we can add the platforms, and Capacitor will create folders for each platform at the root of our project:

# 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

Android iOS 和 Android 在您的 Quasar 项目中，需要创建文件夹。

这些是真正的本机项目！

要在之后访问 Android 项目，您必须安装 Android Studio. 对于 iOS，您需要一台 Mac，并应安装 Xcode.

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

要修复这个问题，请打开 capacitor.config.json 文件和更新 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 插件 时， npx cap sync 重新运行

它是时候看看应用了！

构建和部署原生应用

为了开发 iOS 应用，您需要安装 Xcode ，并且对于 Android 应用，您需要安装 Android Studio 。此外，如果您打算在应用商店上发布您的应用，则需要为 iOS 和 Android 分别加入 Apple Developer Program 和 Google Play Console。

如果您是原生移动开发的新手，可以使用 Capacitor CLI 来轻松打开两种原生项目:

npx cap open ios
npx cap open android

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

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

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

但是，开发过程中还有更快的方法……

Capgo 实时更新

Capgo 实时更新是一项服务，允许开发者在不通过传统的App Store提交流程的情况下，将更新部署到移动应用中。这可以成为快速修复bug或对应用进行小幅度更新而不必等待App Store审查流程的便捷方式。

将Capgo集成到Quasar应用中是一个简单的过程，能够让您充分利用实时更新的力量。这一步步指南将指导您完成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 present in your account to log in with the CLI:

`npx @capgo/cli@latest login YOU_KEY`

apikey:

Let’s get started by first creating an app in Capgo Cloud with the CLI.

    npx @capgo/cli@latest app add

This command will use all variables defined in the Capacitor config file to create the app.

让我们从创建一个应用程序开始__CAPGO_KEEP_0__ Cloud中使用__CAPGO_KEEP_1__。:

Run the command to build your code and send it to Capgo with:

npx @capgo/cli@latest bundle upload`

上传您的第一个版本

运行命令来构建您的__CAPGO_KEEP_0__并将其发送到__CAPGO_KEEP_1__： 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 更新您的应用程序。

接收实时更新:

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

  npx cap run [ios | android]

打开应用，放到后台再打开，日志中应该能看到应用已经更新。

恭喜！ 🎉 您成功部署了第一个实时更新。 这只是实时更新的开始。 为了了解更多，请查看完整的 实时更新文档.

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

点击按钮后，您可以看到美丽的原生分享对话框在行动!

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

Native-feeling UI with Capgo Native Navigation and Transitions

我已经工作了几年， Ionic 来构建跨平台应用程序，但将其与Quasar集成起来很hacky，并且很少值得在您已经有 Tailwind CSS.

在Quasar + Capacitor应用程序中实现原生移动感知，使用Capgo插件而不是仅限Web的UI套件，如Konsta UI:

• @capgo/capacitor-native-navigation ——原生导航栏、Liquid Glass iOS标签栏和Android模糊标签栏样式。您的Quasar路由器保留路由状态；插件拥有原生浏览器。
• @capgo/capacitor-transitions ——Ionic样式页面过渡和iOSWebView层的边缘滑动返回，未采用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',
  },
});

渲染液态玻璃标签栏（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>

Wrap routed pages in cap-router-outlet, cap-page，并且 cap-content，并且调用 setDirection('forward') 或 setDirection('back') context

See the full guides: Using @capgo/capacitor-native-navigation 或 使用@capgo/capacitor-转换.

安全区域与Tailwind

在Tailwind CSS中，使用设备安全区域 @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设置 在 GitHub 上提交一个 PR.

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

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

在

（或您的 Quasar HTML 模板中），在 index.html 从根包装器中处理 iOS 安全区域 <head>:

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

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

将所有页面内容包装在

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);
}

在头部、模态窗口和布局包装器中重复应用安全区域填充通常会使 UI 看起来被裁切或过大。 .app-shell使用

With @capgo/tailwind-capacitor,你可以使用类似于 pt-safe pb-safe px-safe 的样式来实现相同的填充效果。

Set Capacitor iOS contentInset 设置__CAPGO_KEEP_0__ iOS never 到

首先 capacitor.config.ts在 contentInsetMode: 'css',优先使用原生边距禁用并让 CSS（或 Native Navigation 的）

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-*) 混合__CAPGO_KEEP_0__的自动内容边距与 CSS

填充是双倍间距的常见原因。

通常的罪魁祸首是使用 100vw, Tailwind w-screen, 固定像素宽度, 或者一个很大的 min-width.

In 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 with w-full 当可能时。许多水平溢出问题来自 100vw / w-screen, 重复的安全区域填充, 或者一个固定宽度的容器 —— 不是来自视口元标签本身。

结论

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

并且通过添加 Capgo，甚至更容易将实时更新添加到您的应用程序中，确保您的用户始终可以访问最新的功能和 bug 修复。

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

继续从使用 Quasar 和 Capacitor 创建具有实时更新的移动应用程序。

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