SvelteKit和Capacitor的构建

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

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

按照本教程中的逐步指南，将您的 SvelteKit 应用程序转换为使用 Capacitor 的移动应用程序，包括可选的 Capgo 原生导航、过渡和 iOS 布局指南。

关于 Capacitor

CapacitorJS 是一个革命性的工具！它可以轻松地与任何 web 项目集成，包装您的应用程序在一个原生 webview 中，并为您生成原生 Xcode 和 Android Studio 项目。其插件提供对原生设备功能的访问，例如通过 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

在运行 build 命令后，您应该看到一个新 dist 项目根目录下的文件夹。

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

Adding Capacitor to Your SvelteKit App

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

接下来，安装核心包和iOS和Android平台的相关包。 Capacitor CLI 此时，您应该看到新的

ios

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

# 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文件夹 ios文件夹 和安卓项目文件夹

这些是真正的本地项目!

为了以后访问安卓项目，您需要安装安卓Studio.对于iOS，您需要一台Mac并安装 Xcode.

此外，您应该找到一个 capacitor.config.ts file in your project, which contains some basic Capacitor settings used during the sync. The only thing you need to pay attention to is the __CAPGO_KEEP_0__设置，用于同步过程中。您需要注意的是，，必须指向您的构建命令的结果。当前情况是错误的。

为了解决这个问题，请打开 capacitor.config.ts 文件并更新 webDir:

import { CapacitorConfig } from '@capacitor/cli'

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

export default config

ow that we’ve updated our Capacitor settings, let’s change out Sveltekit project to a static application by downloading the proper static adapter package:

npm i -D @sveltejs/adapter-static

已更新__CAPGO_KEEP_0__设置后，让我们将Sveltekit项目更改为静态应用程序，通过下载适当的静态适配器包: 安装包后，我们需要修改 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 并只需在 +layout.js:

export const prerender = true

添加并更新 +layout.js 页面后，我们需要添加我们的移动平台，重新构建我们的项目以创建 build context

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

npm run build
npx cap sync

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

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

您可能已经不经意间完成了这个过程，所以让我们在设备上看看应用!

构建和部署原生应用

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

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

npx cap open ios
npx cap open android

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

android-studio-run

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

xcode-run

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

但等一下，还有更快的方法来完成开发过程……

Capacitor Live Reload

现在，你可能已经习惯了所有现代框架都有热重载的功能，好消息是你可以在移动设备上实现相同的功能 在移动设备上 只需花费最少的努力!

通过让__CAPGO_KEEP_0__应用在你的网络上实时重载 你可以让你的本地托管应用 通过让Capacitor应用从特定的URL加载内容

第一步是确定你的本地IP地址。如果你使用Mac，可以通过在终端中运行以下命令来找到它:

ipconfig getifaddr en0

在Windows上运行:

ipconfig

然后查找IPv4地址

我们可以通过在文件中添加另一个条目来指示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;

__CAPGO_KEEP_0__ 正确的IP和端口, 如上例所示。

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

npx cap copy

这个 copy 命令与 sync类似，但它只会 将对web文件夹和配置的更改复制到本地项目中，而不更新本地项目。 您现在可以通过Android Studio或Xcode再次部署您的应用。之后，如果您在Svelte应用中更改了什么东西，

应用将自动重新加载 并显示更改！ 请记住

__CAPGO_KEEP_0__ 如果您安装了新插件，如摄像头插件，它仍然需要重新构建您的原生项目。这是因为原生文件已更改，无法在实时进行。

请注意，您应该在配置中使用正确的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布局问题，导致水平溢出或裁剪安全区域。

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

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

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

渲染 Liquid Glass tab 框 (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}`);
});

在应用 shell 中添加原生页面过渡:

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

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

在导航之前进行。不要在原生导航拥有这些表面时重复 Web 头部或底部。 Using @capgo/capacitor-native-navigation 使用 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation Using @capgo/capacitor-transitions.

安全区域与Tailwind

在Tailwind CSS中使用设备安全区域，使用 @capgo/tailwind-capacitor (发布于 tailwind-capacitor 在npm上发布。它提供 safe-areas 实用程序和其他Capacitor友好的Tailwind插件：

bun add -D tailwind-capacitor

在 src/app.css:

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

使用实用程序，如 pt-safe, pb-safe,和 px-safe 代替手动 env(safe-area-inset-*) 。该项目正在积极开发中——如果您的SvelteKit设置缺少某些内容，请在__CAPGO_KEEP_0__上打开一个PR 实用程序和其他GitHub-友好的Tailwind插件：.

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

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

确保视口元标签正确应用

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

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

从根元素中处理 iOS 安全区域

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

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 在单个 shell 上

设置Capacitor iOS `contentInset` 到 `never` 首先

在 capacitor.config.ts，优先使用原生 inset 并让 CSS（或 Native Navigation 的） contentInsetMode: 'css')控制安全区域：

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

混合Capacitor的自动内容 inset 与 CSS env(safe-area-inset-*) padding 是双倍间距的常见原因。

找到实际溢出元素

通常的凶手是使用 100vw，Tailwind w-screen，一个固定的像素宽度，或者一个很大的 min-width.

在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_KEEP_0__ Capgo，甚至更容易为您的应用添加实时更新，使得您的用户始终可以访问最新的功能和bug修复。

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

学习如何使用 Capgo 快速构建更好的应用程序注册免费账户今天

继续阅读《使用 SvelteKit 和 Capacitor 构建移动应用》

如果您正在使用《使用 SvelteKit 和 __CAPGO_KEEP_0__ 构建移动应用》 Building Mobile Apps with SvelteKit and Capacitor 将其与 __CAPGO_KEEP_0__ CI/CD 连接在 Capgo CI/CD 中为产品工作流程 Capgo 原生构建在 Capgo 原生构建中为产品工作流程 Capgo 原生构建 Capgo 集成 for the product workflow in Capgo 集成 CI/CD 集成 for the implementation detail in CI/CD 集成, and GitHub 动作集成 for the implementation detail in GitHub 动作集成

Building Mobile Apps with SvelteKit and Capacitor