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은 React.js 웹 앱을 네이티브 모바일 애플리케이션으로 변환하는 간단한 단계를 포함하고 있습니다. 따라서 이 여정을 안내하는 동안 지켜보세요.

__CAPGO_KEEP_0__ 개요

Capacitor Overview

CapacitorJS는 게임 체이너입니다. 웹 프로젝트와 완벽하게 통합할 수 있으며 앱을 네이티브 웹 뷰로.wrap하고 Xcode 및 Android Studio 프로젝트를 생성하는 native 프로젝트를 생성할 수 있습니다. 또한 플러그인을 통해 JS 브리지를 통해 카메라와 같은 네이티브 장치 기능에 접근할 수 있습니다.

Capacitor은 네이티브 모바일 애플리케이션을 만들기 위한 단순하고 직관적인 방법을 제공합니다. API과 streamlined 기능으로 프로젝트에 쉽게 통합할 수 있습니다.

React.js 앱 설정

React 애플리케이션을 시작하는 가장 단순한 방법을 사용해 보겠습니다. npm 패키지 관리자를 사용하여 새로운 React 앱을 생성할 것입니다:

npx create-react-app my-app

프로젝트를 네이티브 모바일 앱으로 변환하기 위해서는 export 앱이 필요합니다.

이것에 대해 다시 돌아올 것입니다. 먼저, Capacitor을 React 앱에 통합하는 방법을 이해해 보겠습니다.

Capacitor을 React.js 앱에 통합

초기 설정 단계가 조금 복잡할 수 있지만, 네이티브 앱 wrapper를 업데이트하는 것은 단순히 명령을 실행하는 것만큼 간단합니다. sync 먼저, __CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 개발 의존성으로 설치하고 프로젝트 내에서 설정합니다. 설정 중 이름과 번들 ID에 대한 기본값을 수락하기 위해 “enter”를 눌러주세요.

Capacitor은 CLI을 개발 의존성으로 설치하고 프로젝트 내에서 설정합니다.

다음으로, 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

The ios and android 디렉토리는 이제 React.js 프로젝트에 존재합니다.

애플리케이션을 나중에 Android 프로젝트에 접근하기 위해 Android Studio를 설치하세요. iOS는 Mac이 필요하며 Xcode를 설치해야 합니다.다음으로, 업데이트를.

해주세요. 웹 디렉토리 당신의 capacitor.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

명령어를 실행하면 React.js 프로젝트를 빌드하고 __CAPGO_KEEP_0__을 정확한 위치에 맞춰서 네이티브 플랫폼에 동기화시킵니다. npm run build 이제, 조금의 행운과 오류가 없다면, 당신의 React.js 앱은 기기에서 실행할 수 있도록 준비되어야 합니다! npx cap sync will align the web code in the accurate places of the native platforms so they can be executed in an app.

iOS 앱 개발을 위해서는

Xcode

Xcode Xcode그리고 안드로이드 앱이 필요합니다. 안드로이드 스튜디오앱을 스토어에 배포하려면 iOS는 Apple Developer Program에, 안드로이드는 Google Play Console에 등록해야합니다.

Capacitor CLI은 native 프로젝트를 열기 위한 과정을 단순화합니다.

npx cap open ios
npx cap open android

native 프로젝트가 설정되면 앱을 연결된 기기로 배포하는 것은 간단한 과정입니다.

안드로이드 스튜디오의 경우, 모든 것을 로드하고 나면 연결된 기기에서 앱을 배포하세요.

Xcode의 경우, 앱을 실제 기기에서만 실행할 수 있도록 signing 계정 설정을 하세요. 그 후에 단순히 play를 클릭하여 연결된 기기에서 앱을 실행하세요. 기기를 선택할 수 있습니다.

모든 것이 잘 진행되면, React.js 웹 앱을 native 모바일 애플리케이션으로 변환할 수 있습니다!

Capacitor Live Reload

최신 개발 프레임워크는 대부분 hot reload를 제공합니다. Capacitor도 마찬가지로 제공되지만 모바일 기기에서!

로컬 호스트 애플리케이션을 네트워크에서 접근할 수 있도록 live reload를 사용하여 Capacitor 앱이 특정 URL에서 콘텐츠를 로드할 수 있습니다.

첫 번째로, 로컬 IP 주소를 결정하세요. 맥에서 이 작업을 수행하려면 터미널에서 ipconfig getifaddr en0 를 실행하세요. 윈도우에서 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;

앱을 다시 한 번 Android Studio 또는 Xcode를 통해 배포하면 React 앱의 변경 사항이 자동으로 다시 로드되고 앱에 표시됩니다! npx cap copy 새로운 플러그인을 설치한 경우, 카메라와 같은 경우, 네이티브 프로젝트를 다시 빌드해야 합니다. 이는 네이티브 파일이 변경되었기 때문입니다. 동적으로 업데이트할 수 없습니다.

__CAPGO_KEEP_0__ 플러그인 사용

__CAPGO_KEEP_0__ 플러그인을 사용하는 방법에 대해 간단히 살펴보겠습니다. 간단한 플러그인인

Using Capacitor Plugins

Let’s take a quick look at how to use a Capacitor plugin. Let’s install a simple one, the __CAPGO_KEEP_0__ 플러그인 사용하기native share dialog을 호출하는 것을 유도하는 것은:

npm i @capacitor/share

Capacitor를 사용하려면 패키지를 임포트하고 앱에서 해당 함수를 호출하세요. 앱의 __CAPGO_KEEP_0__을 고려하세요. share() App.js 새 플러그인을 설치한 후 React 프로젝트를 다시 동기화하세요. 다음으로, iOS와 Android에서 __CAPGO_KEEP_0__ 네비게이션과 전환을 사용하여 앱을 더 원시적인 느낌으로 만들 수 있고, 수평 스크롤이나 안전 영역이 잘려나가는 iOS 레이아웃 문제를 해결할 수 있습니다.:

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;

__CAPGO_KEEP_0__ 네이티브 네비게이션과 전환으로 원시적인 UI를 만들기 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.

React + Capgo 앱에서 원시적인 모바일 느낌을 원한다면, Konsta UI와 같은 웹 전용 UI 키트 대신 __CAPGO_KEEP_1__ 플러그인을 사용하세요.

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_0__ __CAPGO_KEEP_1__.

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

• @capgo/capacitor-native-navigation — 네이티브 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일. React 라우터는 경로 상태를 유지하고 플러그인은 네이티브 창을 소유합니다.
• @capgo/capacitor-transitions — Ionic-style 페이지 전환 및 iOS 에지 스와이프-백 뷰 뷰어 레이어에서, Ionic UI를 채택하지 않고.

설치 BOTH:

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

네이티브 네비게이션을 CSS inset 모드와 구성하여 웹 콘텐츠가 네이티브 바를 존중하도록:

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

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

리퀴드 글라스 탭 바를 렌더링하십시오 (iOS는 시스템 소유 렌더링을 사용하고 Android는 흐린 웹 뷰 백그라운드 스타일을 사용합니다):

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 routed pages in cap-router-outlet, cap-page페이지를 Wrap routed pages in cap-contentor setDirection('forward') 또는 setDirection('back') 이전으로 이동하기 전에. 웹 헤더나 푸터를 중복해서 사용하지 마세요. 네이티브 네비게이션에서 해당 표면을 소유하고 있기 때문입니다.

전체 가이드를 참조하세요: Using @capgo/capacitor-native-navigation 그리고 Using @capgo/capacitor-transitions.

안전 영역에 Tailwind 사용하기

Tailwind CSS에서 디바이스 안전 영역을 사용하려면 Capacitor-capgo-tailwind-capacitor Capacitor-__CAPGO_KEEP_0__ tailwind-capacitor Capacitor-npm safe-areas Capacitor-Capacitor

bun add -D tailwind-capacitor

In src/index.css:

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

React와 Capacitor을 사용하여 모바일 앱을 만들기 pt-safe, pb-safe, 및 px-safe 대신 수동으로 뿌리지 말고 env(safe-area-inset-*) 프로젝트는 활발하게 개발되고 있으므로, React 설정에 필요한 것이 빠진 경우 GitHub.

iOS 레이아웃 문제를 해결하는 방법 (뷰포트, 안전 영역, 가로 스크롤)

iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤이 가능하다면, overflow-x: hidden 또는 뷰포트 태그를 조정하는 것만으로는 해결되지 않는다. 이러한 체크를 순서대로 진행하십시오.

뷰포트 메타 태그가 올바르게 적용되었는지 확인하십시오.

뷰포트 메타 태그를 index.html 내부에 <head>:

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

iOS 안전 영역을 한 개의 루트 wrapper에서 처리하십시오.

React와 Capacitor를 사용하여 단일 앱 쉘을 만들고 안전 영역 패딩을 적용하십시오. 여러 중첩된 컴포넌트에서 패딩을 적용하지 마십시오:

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. 헤더, 모달, 레이아웃 wrapper에 중복된 안전 영역 패딩이 있는 경우 UI가 잘린 것처럼 보이거나 너무 크게 보입니다.

Capacitor와 함께 @capgo/tailwind-capacitor를 사용하여, 단일 쉘에 패딩을 적용할 수 있습니다. pt-safe pb-safe px-safe CSS (또는 Native Navigation의)

Set Capacitor iOS contentInset 를 never 첫 번째로

In capacitor.config.ts에서, native inset을 비활성화하고 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-*) 실제로 부여되는 요소를 찾으십시오.

일반적으로 원인은

Tailwind 100vw, 고정 픽셀 너비, 또는 큰 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은 기존 웹 프로젝트를 기반으로 하는 네이티브 앱을 빌드하는 데 있어 매끄러운 수단을 제공하며, code을 공유하고 일관된 UI를 제공하는 간단한 방법을 제공합니다.

Thanks to technologies like Capacitor, building mobile applications from React.js web apps has never been easier. Take your web development skills to the next level by crafting impressive native mobile apps. Happy coding!

더 많은 정보를 얻으려면, __CAPGO_KEEP_0__에 무료 계정으로 가입하세요. 오늘.

Building Mobile Apps with Pure React.js와 Capacitor으로부터 계속 진행하세요.

Building Mobile Apps with Pure React.js와 __CAPGO_KEEP_0__을 사용하여 네이티브 미디어 및 인터페이스 동작을 계획하고, __CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activities와 연결하세요. Capacitor/__CAPGO_KEEP_1__-live-activities를 사용하여 네이티브 기능을 사용하세요. __CAPGO_KEEP_0__/__CAPGO_KEEP_1__-live-activities를 사용하여 네이티브 기능을 사용하세요. Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities Capgo @capgo/capacitor-live-activities 구현 세부 사항 Capgo @capgo/capacitor-video-player 사용 Capgo @capgo/capacitor-video-player의 원시 기능 @capgo/capacitor-video-player Capgo @capgo/capacitor-video-player 구현 세부 사항 및 Capgo @capgo/capacitor-native-navigation 사용 Capgo @capgo/capacitor-native-navigation의 원시 기능