Building Mobile Apps with SvelteKit and Capacitor

在本教程中，我们将从头开始 SvelteKit 使用 SvelteKit 和 Capacitor 开发移动应用，之后可以转向使用 Capacitor 的原生移动开发。您还可以添加 Capgo 原生导航和过渡，实现原生移动体验，并使用 tailwind-capacitor 来安全区域。

Capacitor让您轻松将SvelteKit Web应用转换为原生移动应用，无需进行重大修改或学习新的技能，如React Native。

使用SvelteKit和Capacitor创建移动应用，步骤如下：将您的SvelteKit应用转换为移动应用，支持Capacitor，可选Capgo原生导航、过渡效果和iOS布局指南。

About Capacitor

CapacitorJS 是一个革命性的工具！ 它可以轻松地与任何 web 项目集成，包裹您的应用程序在一个原生 webview 中，并为您生成原生 Xcode 和 Android Studio 项目。 它的插件提供了访问原生设备功能的 JavaScript 桥，例如通过 JavaScript 桥访问摄像头。

Capacitor enables you to create a fantastic native mobile app without any complicated setup or steep learning curve. Its slim API and streamlined functionality make it easy to integrate into your project. You’ll be amazed at how simple it is to achieve a fully functional native app with Capacitor!

准备 SvelteKit 应用

在 SvelteKit 中创建一个新应用，执行以下命令：

npm create svelte@latest my-app
cd my-app
npm install
npm run build

Capgo build command，您应该看到一个新的 dist 项目根目录下的文件夹。

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

在您的 SvelteKit 应用中添加 Capacitor

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

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

下一步，安装核心包和iOS和Android平台相关的包。

最后，添加平台，Capacitor将在您的项目根目录创建每个平台的文件夹：

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

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

这些是真正的本机项目！

要访问Android项目，需要安装 安卓 studio。对于iOS，需要Mac，并应安装 Xcode.

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

要修复此问题，请打开 capacitor.config.ts 文件并更新 webDir:

import { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'build',
}

export default config

我们已经更新了Capacitor设置后，让我们将Sveltekit项目更改为静态应用程序，通过下载适当的静态适配器包:

npm i -D @sveltejs/adapter-static

安装包后，我们需要修改 svelte.config.js 文件从自动适配器到静态：

import adapter from '@sveltejs/adapter-static'
import { vitePreprocess } from '@sveltejs/kit/vite'

/** @type {import('@sveltejs/kit').Config} */
const config = {
// Consult https://kit.svelte.dev/docs/integrations#preprocessors
// for more information about preprocessors
  preprocess: vitePreprocess(),

  kit: {
    // adapter-auto only supports some environments, see https://kit.svelte.dev/docs/adapter-auto for a list.
    // If your environment is not supported or you settled on a specific environment, switch out the adapter.
    // See https://kit.svelte.dev/docs/adapters for more information about adapters.
    adapter: adapter({
      // default options are shown. On some platforms
      // these options are set automatically — see below
      pages: 'build',
      assets: 'build',
      fallback: null,
      precompress: false,
      strict: true
    })
  }
}

export default config

与此同时 svelte.config.js 更新后，我们需要添加一个 预渲染 选项 通过创建一个 +layout.js 页面到 src/routes 通过创建一个:

export const prerender = true

并仅在其中添加以下导出 通过创建一个 我们需要在此页面上添加我们的移动平台，重新构建我们的项目以创建 构建 文件夹

您可以通过运行以下命令来完成

npm run build
npx cap sync

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

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

您已经完成了这个过程而不自知，所以让我们在设备上看看应用

创建和部署原生应用

为了开发iOS应用，需要安装 Xcode ，并且为了开发Android应用，需要安装 安卓 Studio 。此外，如果您打算在应用商店上发布应用，则需要在iOS上注册Apple Developer Program，在Android上注册Google Play Console。

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

npx cap open ios
npx cap open android

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

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

恭喜！您成功将SvelteKit Web应用部署到移动设备。以下是示例:

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

Capacitor 实时重载

到目前为止，您可能已经习惯了所有现代框架都具有热重载的功能，而好消息是您可以在移动设备上实现相同的功能 仅需最少的努力！ 通过在您的网络上启用对本地托管应用程序的访问，实时重载

在您的网络上 通过让__CAPGO_KEEP_0__应用程序从特定URL加载内容。 通过让Capacitor应用加载特定URL的内容。

在Windows上运行：

ipconfig getifaddr en0

然后查找IPv4地址。

ipconfig

__CAPGO_KEEP_0__

我们可以告诉Capacitor从服务器直接加载应用程序，通过在我们的配置文件中添加另一个条目 capacitor.config.ts 文件：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:3000',
    cleartext: true
  }
};

export default config;

请确保使用 正确的IP和端口如上例所示。

现在，我们可以将这些更改应用到我们的原生项目中：

npx cap copy

命令与 copy 类似，但它只会 sync将对web文件夹和配置的更改复制到原生项目中，而不更新原生项目。 您现在可以通过Android Studio或Xcode再次部署您的应用程序。随后，如果您在Svelte应用程序中更改了什么内容, 您可以通过Live Update将这些更改应用到您的原生应用程序中。

您可以通过Live Update将这些更改应用到您的原生应用程序中。 该应用程序将自动重新加载 并显示更改!

请注意 如果您安装了新插件，如摄像头，则仍然需要重新构建您的本机项目。这是因为本机文件已更改，无法在飞行中完成。

请注意，您应该在配置中使用正确的IP和端口。上面的code块显示了示例目的地的默认SvelteKit端口。

使用Capacitor插件

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

npm i @capacitor/share

没有什么特别的关于 分享插件，但它会弹出本机分享对话框！现在，我们只需要导入包并从应用程序中调用 share() 函数，所以让我们修改 src/routes/index.svelte 到这个步骤：

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

<h1>Welcome to SvelteKit and Capacitor!</h1>
<button on:click={share}>Share now!</button>

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

npx cap sync

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

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

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

我已经工作了几年， Ionic 来构建跨平台应用，但将其与SvelteKit集成起来很hacky，并且当您已经有 Tailwind CSS.

在SvelteKit + Capacitor应用中实现原生移动感受的最佳方式是使用Capgo插件，而不是像Konsta UI这样的仅限Web UI套件：

• @capgo/capacitor-原生导航 ——原生导航栏、Liquid Glass iOS标签栏和Android模糊标签栏样式。您的SvelteKit路由器保留路由状态；插件拥有原生浏览器。
• @capgo/capacitor-过渡 — WebView层中具有Ionic风格页面过渡和iOS边缘滑动返回功能，未采用Ionic UI.

安装两者：

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx 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 }) => {
  goto(`/${id}`);
});

在应用壳中添加本机页面过渡：

<script>
  import { goto } from '$app/navigation';
  import { routerOutlet, page, setDirection } from '@capgo/capacitor-transitions/svelte';
  import '@capgo/capacitor-transitions';

  function openSettings() {
    setDirection('forward');
    goto('/settings');
  }
</script>

<cap-router-outlet use:routerOutlet>
  <cap-page use:page>
    <cap-content slot="content">
      <slot />
    </cap-content>
  </cap-page>
</cap-router-outlet>

在 SvelteKit 应用中，使用 Capacitor 的移动端应用需要将路由页面 Wrap 在一起。 cap-router-outlet, cap-page，和 cap-content，并调用 setDirection('forward') 或 setDirection('back') context

查看完整指南： 使用@capgo/capacitor-原生导航 and 使用@capgo/capacitor-过渡.

安全区域

在Tailwind CSS中，使用 @capgo/Tailwind-capacitor (发布于 tailwind-capacitor npm safe-areas utilities 和其他 Capacitor 兼容的 Tailwind 插件

bun add -D tailwind-capacitor

有用的工具和其他 src/app.css:

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

__CAPGO_KEEP_0__-友好的Tailwind插件： pt-safe, pb-safe在 px-safe 取代手动添加 env(safe-area-inset-*) 手动添加。该项目正在积极开发中 — 如果您的SvelteKit设置缺少某些功能，请 在GitHub上提交PR.

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

如果内容在iOS上被裁切、偏移或水平滚动，请尝试 overflow-x: hidden 或调整视口标签通常无法解决问题。按照以下顺序检查这些问题。

确保视口元标签正确应用

在 src/app.html中设置视口元标签 <head>:

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

正确处理iOS安全区域

从根包装器中只处理一次安全区域

html,
body,
body {
  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: 'build',
  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通过Capacitor的加入，

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

了解Capgo如何帮助您快速构建更好的应用 立即注册一个免费账户 今天

继续从使用SvelteKit和Capacitor构建移动应用

如果您正在使用 使用SvelteKit和Capacitor构建移动应用 来规划CI/CD自动化，连接它与 Capgo CI/CD 为Capgo产品工作流程在Capgo CI/CD中 Capgo原生构建 为Capgo产品工作流程在Capgo原生构建中 Capgo集成 为Capgo产品工作流程在Capgo集成中 CI/CD集成 为CI/CD集成的实现细节 GitHub动作集成 为GitHub动作集成的实现细节