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

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

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

本教程将指导您完成整个过程，首先使用新Quasar应用程序，然后将Capacitor整合到移动应用程序中，以进入原生移动应用程序的领域。此外，您将使用 Capgo 仅需几秒钟即可将实时更新发送到您的应用程序。

关于Capacitor

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

使用Capacitor，您可以获得一个无需复杂设置或陡峭学习曲线的精美原生移动应用程序。其轻量级API和高效的功能使其成为轻松整合到您的项目中的理想选择。相信我，您将惊叹于如何轻松地使用Capacitor实现一个功能齐全的原生应用程序!

准备您的Quasar应用程序

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

npm init quasar

Quasar项目设置

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

为了创建一个原生移动应用程序，我们需要一个导出我们的项目中。因此，让我们在我们的 package.json 文件中添加一个简单的脚本，用于

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

构建和复制 Quasar 项目: generate执行命令后 dist 你应该能够在项目根目录下看到一个新的

This folder will be used by Capacitor later on, but for now, we must set it up correctly.

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

将 __CAPGO_KEEP_0__ 添加到 Quasar 应用程序中 sync 将任何 web 应用程序打包到原生移动容器中，我们必须遵循几个初始步骤，但之后只需执行一个

命令。首先，我们可以安装 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

初始化Capacitor

到目前为止，您应该能够观察到新的 ios 和 context: Page/area: Capgo marketing website. Role: Short UI label or navigation item. Seen in: page trust.astro. Message key `and` (And). android

文件夹在Quasar项目中。

这些是真正的本机项目！要在将来访问Android项目，您必须安装为了在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 已安装。另外，如果您打算在应用商店上发布您的应用程序，则需要在 Apple Developer Program 中注册 iOS 和 Google Play Console 中注册 Android。

If you’re new to native mobile development, you can use the Capacitor CLI to easily open both native projects:

npx cap open ios
npx cap open android

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

android-studio-run

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

xcode-run

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

但等一下，还有更快的方法可以在开发期间这样做……

Capgo Live Update

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

在您的 Quasar 应用程序中集成 Capgo 是一个简单的过程，能够让您利用实时 live 更新的力量。这一步步指南将指导您完成 Capgo Live Update 的集成和实现，从而让您能够提供无缝的更新。

注册并访问 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 云:

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

`npx @capgo/cli@latest login YOU_KEY`

添加您的第一个应用:

让我们从创建一个 Capgo Cloud 应用开始，使用 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 来更新您的应用程序。

接收实时更新:

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

  npx cap run [ios | android]

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

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

使用 Capacitor 插件

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

npm i @capacitor/share

这个 "Share" 插件并没有什么特别的功能，但它仍然可以弹出原生分享对话框！为了实现这个，我们现在只需要导入包并从我们的应用中调用相应的函数，所以让我们修改 "pages/index.vue" 文件如下：如前所述，当安装新插件时，我们需要执行同步操作并重新部署应用到设备上。要实现这个，请运行以下命令：点击按钮后，您可以看到美丽的原生分享对话框！ share() 接下来，您可以使用 __CAPGO_KEEP_0__ 导航和过渡使应用在 iOS 和 Android 上更具原生感，并修复常见的 iOS 布局问题，例如水平溢出或裁剪安全区域。 原生感的 UI 使用 __CAPGO_KEEP_0__ 原生导航和过渡 我已经为多年工作了

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

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

npx cap sync

这个 "Share" 插件并没有什么特别的功能，但它仍然可以弹出原生分享对话框！为了实现这个，我们现在只需要导入包并从我们的应用中调用相应的函数，所以让我们修改 "pages/index.vue" 文件如下：

Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.

接下来，您可以使用 __CAPGO_KEEP_0__ 导航和过渡使应用在 iOS 和 Android 上更具原生感，并修复常见的 iOS 布局问题，例如水平溢出或裁剪安全区域。 ionic 构建跨平台应用，但将其与quasar集成起来很hacky，并且当你已经有 tailwind css.

在quasar + Capacitor应用中，为了获得原生移动的感觉，使用Capgo插件而不是像konsta ui这样的web-only UI套件:

@capgo/capacitor-native-navigation ——原生导航栏，liquid glass tab bar在iOS上，Android上模糊的tab bar样式。你的quasar路由器保持路由状态；插件拥有原生浏览器。
@capgo/capacitor-transitions ——ionic风格的页面过渡和iOS边缘滑动返回在webview层，未采用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',
  },
});

渲染液态玻璃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>

Wrap routed pages in 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 插件：

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 设置中缺少某些内容，请 open a PR on GitHub.

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

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

确保视口元标签正确应用

In 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` 首先

在 capacitor.config.ts, 优先使用原生禁用并让 CSS (或 Native Navigation) 来控制安全区域： contentInsetMode: 'css'混合 __CAPGO_KEEP_0__ 自动内容内边距与 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.

context

[...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上下文：来自 Capgo UI 字符串（父级键 `submitting_a_pr_to_capgo`）的 HTML 文本片段。页面/区域：Capgo 市场网站。角色：网站副本。见于：页面 contributing.astro。保留 Capgo 产品/品牌和开发者术语的原始形式。

If you would like to learn how to add Capgo to your Next.js app, take a look at the next article :

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

继续阅读 Creating Mobile Apps with live updates, Quasar 和 __CAPGO_KEEP_0__。 使用 Quasar 和 Capacitor 创建实时更新的移动应用。 为原生插件工作做好准备，连接它 Capgo 插件目录在 Capgo 插件目录中了解产品工作流程 Capacitor 插件由 Capgo 在 Capacitor 插件由 Capgo 中了解实现细节添加或更新插件在添加或更新插件中了解实现细节 Ionic 企业插件替代品了解 Ionic 企业插件替代品的产品工作流程 Capgo 原生构建了解 Capgo 原生构建的产品工作流程

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

关于Capacitor

准备您的Quasar应用程序

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

构建和部署原生应用

Capgo Live Update

使用 Capacitor 插件

Native-feeling UI with Capgo Native Navigation and Transitions

安全区域与 Tailwind

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

确保视口元标签正确应用

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

设置Capacitor iOS `contentInset` 前往 `never` 首先

通常的罪魁祸首是使用

结论

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

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

关于Capacitor

准备您的Quasar应用程序

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

构建和部署原生应用

Capgo Live Update

使用 Capacitor 插件

Native-feeling UI with Capgo Native Navigation and Transitions

安全区域与 Tailwind

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

确保视口元标签正确应用

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

设置Capacitor iOS contentInset 前往 never 首先

通常的罪魁祸首是使用

结论

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

设置Capacitor iOS `contentInset` 前往 `never` 首先