本教程将从创建一个新 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"
}
}folder generate, you should be able to spot a fresh dist folder at your project’s root.
This folder will be used by Capacitor later on, but for now, we must set it up correctly.
Adding Capacitor to Your Quasar App
为了将任何Web应用打包到原生移动容器中，我们必须遵循几个初始步骤，但之后只需执行一个命令。 sync 首先，我们可以将Capgo和Capacitor安装为开发依赖项，然后在项目中设置它们。在设置过程中，您可以按“回车”键以接受名称和包ID的默认值。
接下来，我们需要安装核心包和iOS和Android平台的相关包。 Capacitor CLI 初始化Capgo
到目前为止，您应该能够观察到新文件夹
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
ios ios 和 安卓 在您的Quasar项目中找到文件夹
这些是真正的本机项目!
要访问安卓项目， 安卓Studio， 要访问iOS项目，您需要一个Mac并且应该安装.
Xcode capacitor.config.ts Capacitor.config.ts 文件在您的项目中，它包含一些基本的__CAPGO_KEEP_0__设置，在同步过程中使用。您需要注意的唯一事情是文件夹的位置：，必须指向您的构建命令的结果。当前，它是不准确的。
为了纠正这个问题，请打开 capacitor.config.json 文件并更新 webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}context
npm run generate
npx cap sync您可以通过执行以下命令来尝试它： npm run generate 第一个命令 npx cap sync will sync all the web code into the right places of the native platforms so they can be displayed in an app.
将同步所有的web __CAPGO_KEEP_0__ 到native平台的正确位置，以便它们可以在应用中显示。 Capacitor plugins __CAPGO_KEEP_0__ 插件时， npx cap sync 再次.
你已经完成了,所以让我们看看在设备上的应用!
构建和部署原生应用
为了开发iOS应用,你需要安装 Xcode 并且为了开发Android应用,你需要安装 Android Studio 此外,如果你打算在应用商店上发布你的应用,你需要在iOS上注册Apple Developer Program,在Android上注册Google Play Console。
如果你是原生移动开发的新手,你可以使用Capacitor CLI轻松打开两个原生项目:
npx cap open ios
npx cap open android一旦你设置好了原生项目,就可以轻松地将应用部署到连接的设备上。在Android Studio中,你只需要等待所有内容就绪,然后你就可以在不改变任何设置的情况下将应用部署到连接的设备上。以下是一个例子:
在Xcode中,你需要设置你的签名账户才能将应用部署到真实设备,而不是仅仅在模拟器上运行。如果你之前没有做过, Xcode会指导你完成这个过程(但再次,你需要注册开发者计划)。之后,你只需要点击播放按钮就可以在连接的设备上运行应用,你可以在顶部选择设备。以下是一个例子:
恭喜！您已成功将 Quasar 网页应用部署到移动设备。以下是一个示例：
但是，开发期间还有更快的方法……
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`添加您的第一个应用:
让我们从创建一个应用开始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 到这里：
<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布局问题，导致水平溢出或裁剪安全区域。
使用Capgo原生导航和过渡的原生感知UI
我已经工作了几年，使用 Ionic 来构建跨平台应用，但将其与Quasar集成起来很hacky，并且当您已经有 Tailwind CSS.
时，集成起来并不值得。要在Quasar + Capacitor应用中实现原生移动感受，请使用Capgo插件代替仅限Web的UI套件，如Konsta UI：
- capgo/capacitor-native-navigation —原生导航栏，Liquid Glass iOS上的滑动式标签栏，以及Android上的模糊标签栏样式。您的Quasar路由器保留路由状态；插件拥有原生浏览器。
- @capgo/capacitor-转换 —— 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',
},
});渲染液态玻璃标签栏（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
HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `alternatives_cta_questions`）。页面/区域：Capacitor 实时更新替代方案比较页面。角色：长期营销或法律段落。见于：页面 alternatives.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `alternatives_cta_questions`（替代方案 CTA 问题）。 | HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `appflow_cta_questions`）。页面/区域：Appflow 比较/迁移营销复制。角色：长期营销或法律段落。见于：页面 ionic-appflow.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `appflow_cta_questions`（Appflow CTA 问题）。 | HTML 文本片段来自更长的 Capgo UI 字符串（父级键 `capwesome_cta_questions`）。页面/区域：Capawesome 比较页面。角色：长期营销或法律段落。见于：页面 capwesome.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `capwesome_cta_questions`（Capwesome CTA 问题）。 | 页面/区域：咨询服务页面。角色：段落标题或标语。见于：页面 consulting.astro。保留 Capgo 产品/品牌和开发者术语完全不变。消息键 `consulting_faq_subtitle`（咨询 FAQ 标题）。 | 页面/区域：Appflow 比较/迁移营销复制。角色：短 UI 标签或导航项。见于：页面 ionic-appflow.astro、页面 ionic-enterprise-plugins.astro、页面 solutions/ionic-enterprise-plugins.astro。消息键 `appflow_plugins_or`（Appflow 插件或）。 使用@capgo/capacitor-native-navigation 和 使用@capgo/capacitor-transitions.
安全区域
对于Tailwind CSS中的设备安全区域，使用 @capgo/tailwind-capacitor (发布于 tailwind-capacitor @npm safe-areas utilities and other Capacitor-friendly Tailwind plugins:
npm add -D tailwind-capacitor实用工具和其他 src/css/app.scss:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";@__CAPGO_KEEP_0__ pt-safe, pb-safe-友好的Tailwind插件： px-safe 避免手动添加 env(safe-area-inset-*) 手动添加会很麻烦。该项目正在积极开发中 — 如果您的Quasar设置中缺少某些功能，请 在GitHub上提交PR.
解决iOS布局问题（视口、安全区域和水平溢出）
如果iOS内容被裁切、偏移或水平滚动，请尝试 overflow-x: hidden 或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。
确保视口元标签正确应用
在 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')来控制安全区域：
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist/spa',
ios: {
contentInset: 'never',
},
};混合Capacitor的自动内容内边距与 CSS env(safe-area-inset-*) padding 是双倍间距的常见原因。
找到真正溢出的元素
通常的凶手是使用 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 替换 w-full 当可能时，许多水平溢出问题来自 100vw / w-screen, 重复的安全区域填充，或一个固定宽度的容器 —— 不是来自视口元标签本身。
结论
Capacitor 是一个基于现有 Web 项目构建原生应用的优秀选择，提供了一个简单的方式来共享 code 并保持一致的 UI。
和Capgo的集成后 Capgo这使得您可以轻松地将实时更新添加到您的应用程序中，确保您的用户始终可以访问最新的功能和bug修复。
如果您想学习如何将Capgo添加到您的Next.js应用程序中，请查看下一篇文章：
继续阅读《创建具有实时更新的移动应用程序，Quasar和Capacitor》。
如果您正在使用 《创建具有实时更新的移动应用程序，Quasar和Capacitor》 来规划原生插件工作，连接它到 Capgo插件目录 Capgo插件目录中的产品工作流程 Capacitor插件由Capgo Capacitor插件由Capgo中的实现细节 添加或更新插件 为添加或更新插件的实现细节 Ionic企业插件替代品 为Ionic企业插件替代品的产品工作流程 Capgo原生构建 为Capgo原生构建的产品工作流程
