使用Pure React.js和Capacitor构建移动应用

本教程将带您走过使用 React 和 Capacitor 构建移动应用的过程。通过此过程，您将了解如何将 React.js 网页应用转换为 Capacitor 的原生移动应用，并使用 Capgo Native Navigation 和 Transitions 添加原生感觉。

Capacitor 可以轻松将您的 React.js 网页应用转换为原生移动应用，无需进行重大修改或学习新的策略，如 React Native。

该过程涉及几个简单的步骤，很快您的 React.js 应用将成为一个功能齐全的移动应用。因此，请继续跟随我们，了解如何完成此旅程。

Capacitor 简介

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

Capacitor 提供了一种简单的方式来创建原生移动应用，无需任何麻烦或陡峭的学习曲线。其简单的 API 和流线化的功能使其易于在您的项目中集成。

设置您的 React.js 应用

让我们使用最简单的方法来启动一个 React 应用。我们将使用 npm 包管理器来创建一个新 React 应用:

npx create-react-app my-app

为了将我们的项目转换为原生移动应用，我们需要进行一个 __CAPGO_KEEP_0__。 我们将在稍后返回这个问题。首先，让我们了解如何将 __CAPGO_KEEP_0__ 集成到我们的 React 应用中。 __CAPGO_KEEP_0__ 是一个开源的框架，用于构建跨平台移动应用。它提供了一个简单的 API，使开发者可以轻松地创建原生移动应用。

__CAPGO_KEEP_1__ 是 Capacitor 的一个关键组成部分，它提供了一个原生的 UI 组件库，使开发者可以轻松地创建原生移动应用的 UI。

在您的React.js应用中集成Capacitor

初始设置步骤可能会有点详细，但之后更新您的本机应用程序包装器只需运行一个 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 目录现在出现在您的React.js项目中。 要访问Android项目，请安装

__CAPGO_KEEP_1__ Android Studio. For iOS, you need a Mac and should install Xcode.

下一步，更新你的 webDir 在你的 capacitor.config.json 文件中如图所示：

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

运行构建命令并同步你的项目与Capacitor：

npm run build
npx cap sync

该 npm run build 命令会构建你的React.js项目，而 npx cap sync 会将webcode准确放置在原生平台的正确位置，以便在app中执行。

现在，带点运气和无错误，您的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 实时重载

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

您可以通过让您的本地托管应用在您的网络上实时重载，通过让 Capacitor app 从特定的 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: 'build',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:3000',
    cleartext: true
  }
};

export default config;

确保使用准确的 IP 和端口。运行 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.

原生感知UI使用__CAPGO_KEEP_0__原生导航和过渡： 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应用中，为了获得native mobile的感觉，使用capacitor插件而不是web-only UI kits @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
@capgo/capacitor-transitions @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-transitions

--- ionic风格的页面过渡和iOS的edge swipe-back在webview层，且不采用ionic UI

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',
  },
});

配置native navigation使用css inset模式，使web内容尊严native bars

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}`);
});

渲染液态玻璃tab bar（iOS使用系统渲染，Android使用模糊的webview背景）

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 routed pages in cap-router-outlet, cap-page, and cap-content, and call setDirection('forward') 或 setDirection('back') 在导航之前。请勿在原生导航拥有这些表面时重复网页头部或底部。

查看完整指南：使用@capgo/capacitor-native-navigation 和使用@capgo/capacitor-transitions.

安全区域使用Tailwind

为了在Tailwind CSS中使用设备安全区域，请使用 @capgo/tailwind-capacitor (发布于 tailwind-capacitor 在 npm 上 safe-areas utilities and other Capacitor-friendly Tailwind plugins:

bun add -D tailwind-capacitor

__CAPGO_KEEP_0__ 友好的 Tailwind 插件: src/index.css:

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

在 pt-safe, pb-safe使用以下工具 px-safe , 和 env(safe-area-inset-*) 而不是手动添加 open a PR on GitHub.

该项目正在积极开发中 — 如果您的 React 设置缺少某些功能

在 __CAPGO_KEEP_0__ 上打开一个 PR overflow-x: hidden 修复 iOS 布局问题 (视口、安全区域和水平溢出)

确保视口元标签正确应用

在 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 ,您可以使用类似于

Set 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, 重复的安全区域填充或固定宽度容器 —— 而不是 viewport meta 标签本身。

结论

Capacitor 提供了一个无缝的方式来基于现有的 web 项目构建原生应用，提供了一个简单的方式来共享 code 并保持一致的 UI。

感谢技术如 Capacitor，从 React.js web 应用构建移动应用已经变得更加容易。将您的 web 开发技能提升到下一个水平，通过打造出色的原生移动应用。开心编码！

要了解如何如何快速推进您的应用开发过程，请立即注册一个免费账户。继续阅读 Building Mobile Apps with Pure React.js 和 __CAPGO_KEEP_0__

Keep going from Building Mobile Apps with Pure React.js and Capacitor

__CAPGO_KEEP_0__ 使用 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-native-navigation 为原生能力在使用 @capgo/capacitor-native-navigation 中

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

Capacitor 简介

设置您的 React.js 应用

在您的React.js应用中集成Capacitor

构建和部署您的原生应用

Capacitor 实时重载

使用Capacitor插件

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

安全区域使用Tailwind

该项目正在积极开发中 — 如果您的 React 设置缺少某些功能

确保视口元标签正确应用

从根组件中只处理iOS安全区域

Set Capacitor iOS `contentInset` 到 `never` 首先

找到真正溢出的元素

结论

Keep going from Building Mobile Apps with Pure React.js and Capacitor

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

Capacitor 简介

设置您的 React.js 应用

在您的React.js应用中集成Capacitor

构建和部署您的原生应用

Capacitor 实时重载

使用Capacitor插件

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

安全区域使用Tailwind

该项目正在积极开发中 — 如果您的 React 设置缺少某些功能

确保视口元标签正确应用

从根组件中只处理iOS安全区域

Set Capacitor iOS contentInset 到 never 首先

找到真正溢出的元素

结论

Keep going from Building Mobile Apps with Pure React.js and Capacitor

Set Capacitor iOS `contentInset` 到 `never` 首先