使用纯净的 React.js 和 Capacitor 构建移动应用

This tutorial will walk you through crafting a mobile application using React and Capacitor. By the end, you’ll know how to morph a React.js web app into a native mobile application with Capacitor, and add a native feel with Capgo Native Navigation and Transitions.

Capacitor enables the easy transformation of your React.js web app into a native mobile application, requiring no substantial alterations or learning of new strategies such as React Native.

该过程涉及几个简单的步骤，很快您的React.js应用将成为一个功能齐全的移动应用。因此，请继续阅读本教程的指引。

Capacitor Overview

CapacitorJS是一个革命性的工具。它可以轻松与任何Web项目集成，并将您的应用包装在一个原生Web视图中，同时生成原生Xcode和Android Studio项目。通过其插件，您可以访问像摄像头这样的原生设备功能，通过JS桥接。

Capacitor offers a straightforward way to create a native mobile application without any hassle or steep learning curve. Its simple API and streamlined functionality make it easy to incorporate into your project.

设置您的React.js应用

Let’s go for the simplest method to initiate a React application. We’ll use the npm package manager to create a new React app:

npx create-react-app my-app

为了将我们的项目转换为原生移动应用，需要一个导出我们的应用程序需要。

我们会在一会儿再回来。首先，让我们了解如何将Capacitor集成到我们的React应用程序中。

将Capacitor集成到您的React.js应用程序中

初始设置步骤可能会有点详细，但之后更新您的本机应用程序包装器只需运行一个 sync 命令。

First, we’ll install the Capacitor CLI as a development dependency and set it up within our project. During the setup, accept the default values for name and bundle ID by pressing “enter.”

接下来，我们将安装核心包和iOS和Android平台的相关包。

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

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

# Initialize Capacitor in your React 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 android 现在在您的React.js项目中有了目录。

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

接下来，请更新您的 webDir 文件，如下所示： capacitor.config.json __CAPGO_KEEP_0__.config.json

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "build",
  "bundledWebRuntime": false
}

Run the build command and sync your project with Capacitor:

npm run build
npx cap sync

执行 npm run build 将命令会构建您的 React.js 项目，而 npx cap sync 会将 web code 在本机平台的准确位置对齐，以便在应用中执行。

现在，运气好，没错误，您的 React.js 应用应该已经准备好在设备上发布!

构建和部署本机应用

开发 iOS 应用需要 Xcode, Android 应用需要 Android Studio,如果您打算在应用商店上发布应用，则必须加入 Apple Developer Program（苹果开发者计划）以便于 iOS 和 Google Play Console（谷歌应用商店控制台）以便于 Android。

Capacitor CLI 简化了打开两个本机项目的过程:

npx cap open ios
npx cap open android

一旦您的本机项目设置完成，部署应用到连接设备上就变得简单了。

对于 Android Studio，等待所有内容加载完成，然后部署应用到连接设备上。

为了在Xcode中部署应用到真机而不是模拟器，需要建立您的签名账户。完成后，只需点击播放即可在连接的设备上运行应用，选择设备位置在顶部。

如果一切顺利，您将将您的React.js Web应用转换为原生移动应用!

Capacitor Live Reload

现代开发框架通常都有热重载功能，幸运的是，您也可以在Capacitor中实现热重载 但是在移动设备上!

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

首先，确定您的本地IP地址。在Mac上，您可以通过在终端中运行 ipconfig getifaddr en0 在Windows上，执行 ipconfig 并查找IPv4地址。

然后，指示Capacitor从服务器直接加载应用程序，通过在文件中添加另一个参数 capacitor.config.ts 确保使用准确的IP和端口。然后运行

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

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

export default config;

__CAPGO_KEEP_0__ Live Reload npx cap copy 为了将这些更改应用到我们的原生项目。

通过 Android Studio 或 Xcode 部署应用程序一次后，任何 React 应用程序的更改都会自动重新加载并在应用程序中显示！

请记住，如果安装了新插件，例如相机，它需要重新构建原生项目。这是因为原生文件已经改变，并且无法在实时更新。

使用 Capacitor 插件

让我们快速了解一下如何使用 Capacitor 插件。让我们安装一个简单的插件，名为分享插件，它会弹出原生的分享对话框：

npm i @capacitor/share

要使用它，需要导入包并从我们的应用程序中调用相应的 share() 函数。考虑到 App.js:

import { Share } from '@capacitor/share';

function ShareButton() {
  const share = async () => {
    await Share.share({
      title: 'React App',
      text: 'Visit this React App',
      url: 'http://localhost:3000',
      dialogTitle: 'Share with...'
    });
  };

  return (
    <button onClick={share}>
      Share
    </button>
  );
}

export default ShareButton;

安装新插件后，请记住使用 npx cap sync.

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.

我已经多年来 Ionic 来构建跨平台应用程序，但将其与 React 集成起来很hacky，并且当您已经有.

For a native mobile feel in a React + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:

在一个 React + capgo 应用程序中，为了获得原生移动的感觉，使用 capacitor 插件而不是像 Konsta UI 这样的仅限 web UI 套件: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
@capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

——在 WebView层中，采用Ionic样式的页面过渡和iOS边缘滑动返回，

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

安装它们：

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Render一个Liquid Glass 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 }) => {
  navigate(`/${id}`);
});

在您的应用程序壳中添加本机页面转换：

import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

export function AppShell() {
  const navigate = useNavigate();
  const outletRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (outletRef.current) {
      setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
    }
  }, []);

  const openSettings = () => {
    setDirection('forward');
    navigate('/settings');
  };

  return <cap-router-outlet ref={outletRef}>{/* routes */}</cap-router-outlet>;
}

Wrap路由页面在 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.

context

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

bun add -D tailwind-capacitor

在 src/index.css:

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

使用 utilities 如 pt-safe, pb-safe, 和 px-safe 代替手动添加 env(safe-area-inset-*) 。该项目正在积极开发中——如果您的React设置中缺少某些内容，请在 __CAPGO_KEEP_0__ 上打开一个PR open a PR on GitHub.

__CAPGO_KEEP_0__

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

确保视口元标签已正确应用

在 index.html 中添加视口元标签 <head>:

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

内

仅从根包装器处理 iOS 安全区域

html,
body,
#root {
  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@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__，您可以用类似于 pt-safe pb-safe px-safe 在同一壳子里。

设置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的一致性。

感谢像Capacitor这样的技术，基于React.js Web应用构建移动应用从未如此简单。将您的Web开发技能提升到下一个水平，通过打造出色的原生移动应用。开心编码！

要了解如何如何快速推进您的应用开发过程注册一个免费账户今天

继续使用 Building Mobile Apps with Pure React.js 和 Capacitor

如果您正在使用 Building Mobile Apps with Pure React.js 和 Capacitor 来规划原生媒体和界面行为，连接它与使用 @capgo/capacitor-live-activities 为原生能力在使用 @capgo/capacitor-live-activities 使用 @capgo/capacitor-live-activities 为实现细节在 @capgo/capacitor-live-activities 使用 @capgo/capacitor-video-player 为原生能力在使用 @capgo/capacitor-video-player 使用 @capgo/capacitor-video-player 为实现细节在 @capgo/capacitor-video-player，使用@capgo/capacitor-原生导航为使用@capgo/capacitor-原生导航.

Building Mobile Apps with Pure React.js and Capacitor

Capacitor Overview

设置您的React.js应用

将Capacitor集成到您的React.js应用程序中

构建和部署本机应用

Capacitor Live Reload

使用 Capacitor 插件

Native-feeling UI with Capgo Native Navigation and Transitions

context

__CAPGO_KEEP_0__

确保视口元标签已正确应用

内

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

找到真正溢出的元素

结论

继续使用 Building Mobile Apps with Pure React.js 和 Capacitor

Building Mobile Apps with Pure React.js and Capacitor

Capacitor Overview

设置您的React.js应用

将Capacitor集成到您的React.js应用程序中

构建和部署本机应用

Capacitor Live Reload

使用 Capacitor 插件

Native-feeling UI with Capgo Native Navigation and Transitions

context

__CAPGO_KEEP_0__

确保视口元标签已正确应用

内

设置Capacitor iOS contentInset 到 never 首先

找到真正溢出的元素

结论

继续使用 Building Mobile Apps with Pure React.js 和 Capacitor

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