Capacitor을 사용한 Pure React.js와 모바일 앱 개발

이 튜토리얼에서는 React와 Capacitor를 사용하여 모바일 애플리케이션을 제작하는 방법을 안내합니다. 튜토리얼을 마치면 React.js 웹 앱을 네이티브 모바일 애플리케이션으로 변환하고 Capacitor 네이티브 네비게이션과 Capgo 전환을 추가하여 네이티브한 느낌을 줄 수 있습니다.

Capacitor는 React.js 웹 앱을 네이티브 모바일 애플리케이션으로 변환하는 것을 쉽게 해주며, React Native와 같은 새로운 전략을 배울 필요 없이 네이티브 모바일 앱을 제작할 수 있습니다.

변환 프로세스는 단순한 몇 가지 단계로 이루어져 있으며, React.js 앱을 완전하게 작동하는 모바일 애플리케이션으로 변환할 수 있습니다. 따라서 이 여정을 따라가며 __CAPGO_KEEP_0__에 대한 개요를 안내해 드리겠습니다.

Capacitor 개요

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

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 앱 설정

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를 개발 의존성으로 설치하고 프로젝트 내에서 설정합니다. 설정 중에는 이름과 번들 ID에 대한 기본값을 수락하기 위해 “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 프로젝트에 접근하기 위해서는 Android Studio 를 설치해야 합니다. iOS는 Mac에서 사용할 수 있으며 Xcode

를 설치해야 합니다. 다음으로 업데이트를 진행하겠습니다.The ios.

and 웹 디렉토리 당신의 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

The npm run build 명령어는 React.js 프로젝트를 빌드합니다. npx cap sync 명령어는 웹 code를 네이티브 플랫폼의 정확한 위치에 맞춰서 배치하여 앱에서 실행할 수 있도록 합니다.

이제, 조금의 운과 오류가 없다면, React.js 앱이 기기에 출시 준비가 된 것입니다!

네이티브 앱 빌드 및 배포

iOS 앱 개발은 XcodeiOS 및 Android 앱이 필요합니다. Android StudioiOS와 Android을 위한 앱 스토어에 앱을 배포하려면 Apple Developer Program에 가입하고 Google Play Console에 가입해야 합니다.

Capacitor CLI은 iOS와 Android의 원시 프로젝트를 열기 위한 과정의 단순화를 지원합니다.

npx cap open ios
npx cap open android

원시 프로젝트가 설정되면, 연결된 장치에 앱을 배포하는 것은 단순한 과정입니다.

Android Studio의 경우, 모든 것을 로드하기만 기다리면 연결된 장치에 앱을 배포할 수 있습니다.

Xcode의 경우, 실제 장치에 앱을 배포하기 위해 서명 계정을 설정해야 합니다. 그 후에 단순히 플레이 버튼을 클릭하여 연결된 장치에서 앱을 실행할 수 있습니다. 실행할 장치를 위쪽에서 선택할 수 있습니다.

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

Capacitor Live Reload

최신 개발 프레임워크는 대부분 핫 리로드를 지원합니다. Capacitor도 마찬가지로 지원하지만 핫 리로드는 모바일 장치에서만 지원됩니다.!

로컬 호스트 애플리케이션에 접근할 수 있도록 네트워크 내에서 라이브 리로드를 지원하려면 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;

를 실행하여 이러한 변경 사항을 우리의 네이티브 프로젝트에 적용하세요. npx cap copy Android Studio 또는 Xcode를 통해 앱을 다시 배포한 후, React 앱의 변경 사항이 자동으로 로드되고 앱에 표시됩니다!

새로운 플러그인인 카메라와 같은 것이 설치된 경우, 네이티브 프로젝트를 다시 빌드해야 합니다. 이는 네이티브 파일이 변경되었기 때문입니다. 이러한 변경 사항을 실시간으로 업데이트할 수 없습니다.

__CAPGO_KEEP_0__ 플러그인 사용

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

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

Capgo 패키지를 import하고, 앱에서 해당 함수를 호출하세요. Capgo의 기능을 사용하기 위해, import하고, 앱에서 해당 함수를 호출하세요. share() Capgo의 기능을 사용하기 위해, import하고, 앱에서 해당 함수를 호출하세요. 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;

새로운 플러그인을 설치한 후, React 프로젝트를 다시 sync하세요. npx cap sync.

iOS와 Android에서 더 자연스러운 앱을 만들기 위해, Capgo 네비게이션과 전환을 사용하세요. 또한, iOS에서 발생하는 수평 스크롤이나 안전 영역이 잘려서 보이는 문제를 해결하세요.

10년 이상 Ionic을 사용하여, 크로스 플랫폼 앱을 개발해 왔습니다. 하지만, React와 통합하는 것은 복잡하고, 자주 사용하지 않습니다. 이미 Tailwind CSS를 사용하고 있기 때문입니다. React 앱에서 네이티브 모바일 느낌을 원한다면, __CAPGO_KEEP_0__ 플러그인을 사용하세요. 웹 전용 UI 키트인 Konsta UI 대신에. React 앱에서 네이티브 모바일 느낌을 원한다면, __CAPGO_KEEP_1__ 플러그인을 사용하세요. 웹 전용 UI 키트인 Konsta UI 대신에. React 앱에서 네이티브 모바일 느낌을 원한다면, __CAPGO_KEEP_1__ 플러그인을 사용하세요. 웹 전용 UI 키트인 Konsta UI 대신에..

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-네비게이션 iOS에서 Liquid Glass 탭바를, 안드로이드에서 흐릿한 탭바 스타일을 지원합니다. React 라우터는 경로 상태를 유지하고, 플러그인은 네이티브 창을 관리합니다.
@capgo/capacitor-transition — Ionic 스타일의 페이지 전환 및 iOS 에지 스와이프 백 기능을 WebView layer 에서 사용할 수 있습니다. Ionic UI 를 채택하지 않고도.

Capgo를 설치하세요:

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

Liquid Glass 탭바를 렌더링하세요 (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>;
}

페이지를 라우팅한 페이지를 wrapping합니다. cap-router-outlet, cap-page, 그리고 cap-content, 그리고 호출하세요. setDirection('forward') or setDirection('back') 이전으로 이동하기 전에 웹 헤더나 푸터를 중복하지 마십시오. 네이티브 네비게이션이 해당 표면을 소유하고 있다면.

자세한 설명서를 참조하십시오: @capgo/capacitor-네이티브-네비게이션을 사용하는 방법 및 @capgo/capacitor-트랜지션을 사용하는 방법.

Tailwind에서 안전한 영역

Tailwind CSS에서 장치 안전 영역을 사용하려면 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 출판됨). 이 도구는 tailwind-capacitor npm-친화적인 Tailwind 플러그인을 포함하여 safe-areas 유용한 기능과 기타 Capacitor-친화적인 Tailwind 플러그인을 제공합니다.

bun add -D tailwind-capacitor

In src/index.css:

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

Use utilities such as pt-safe, pb-safe, 및 px-safe 대신에 env(safe-area-inset-*) 수동으로 open a PR on GitHub.

__CAPGO_KEEP_0__

Fixing iOS Layout Issues (Viewport, Safe Area, and Horizontal Overflow) overflow-x: hidden iOS에서 콘텐츠가 잘려나거나-shifted 또는 가로 스크롤이 가능하다면

Viewport 태그만 수정하는 것만으로는 해결되지 않습니다. 이러한 체크를 순서대로 진행하세요.

Viewport meta 태그가 올바르게 적용되어 있는지 확인하세요. index.html Viewport meta 태그를 <head>:

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

내부에 추가하세요.

단일 앱 셸을 만들고 거기에 안전한 영역 패딩을 적용하십시오 — 여러 개의 중첩된 컴포넌트에 적용하지 마십시오:

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_KEEP_0__/tailwind-__CAPGO_KEEP_1__'를 사용하여 @capgo/tailwind-capacitoriOS의 __CAPGO_KEEP_0__를 pt-safe pb-safe px-safe 첫 번째로

Set Capacitor iOS `contentInset` , Native Navigation의 CSS (또는 Native Navigation의) `never` 첫 번째로

첫 번째로 capacitor.config.ts첫 번째로 contentInsetMode: 'css'안전 영역을 소유합니다:

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

Capacitor의 자동 콘텐츠 인셋과 CSS를 혼합하는 것은 일반적입니다. env(safe-area-inset-*) 패딩이 중복 간격의 일반적인 원인은 패딩입니다.

실제로 초과하는 요소를 찾으십시오.

일반적으로 초과 요인은 100vwTailwind 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 태그 자체가 아닙니다.

__CAPGO_KEEP_0__

Capacitor offers a seamless means of building native apps based on an existing web project, providing a simple way to share code and have consistent UI.

Capacitor

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ __CAPGO_KEEP_0__

Capacitor

__CAPGO_KEEP_0__ Capacitor __CAPGO_KEEP_0__ Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities capgo/capacitor-live-활동의 구현 세부 사항 Using @capgo/capacitor-video-player capgo/capacitor-video-player의 원생 기능을 사용하여 @capgo/capacitor-video-player capgo/capacitor-video-player의 구현 세부 사항 및 Using @capgo/capacitor-native-navigation capgo/capacitor-native-navigation의 원생 기능을 사용하여

Capacitor를 사용한 React.js로만 빌드하는 모바일 앱

Capacitor 개요

React.js 앱 설정

Capacitor를 React.js 앱에 통합하는 방법

네이티브 앱 빌드 및 배포

Capacitor Live Reload

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

Capgo 네이티브 네비게이션과 전환을 사용하여, iOS와 Android에서 더 자연스러운 앱을 만들세요.

Tailwind에서 안전한 영역

__CAPGO_KEEP_0__

Viewport 태그만 수정하는 것만으로는 해결되지 않습니다. 이러한 체크를 순서대로 진행하세요.

내부에 추가하세요.

Set Capacitor iOS `contentInset` , Native Navigation의 CSS (또는 Native Navigation의) `never` 첫 번째로

실제로 초과하는 요소를 찾으십시오.

__CAPGO_KEEP_0__

Capacitor

Capacitor를 사용한 React.js로만 빌드하는 모바일 앱

Capacitor 개요

React.js 앱 설정

Capacitor를 React.js 앱에 통합하는 방법

네이티브 앱 빌드 및 배포

Capacitor Live Reload

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

Capgo 네이티브 네비게이션과 전환을 사용하여, iOS와 Android에서 더 자연스러운 앱을 만들세요.

Tailwind에서 안전한 영역

__CAPGO_KEEP_0__

Viewport 태그만 수정하는 것만으로는 해결되지 않습니다. 이러한 체크를 순서대로 진행하세요.

내부에 추가하세요.

Set Capacitor iOS contentInset , Native Navigation의 CSS (또는 Native Navigation의) never 첫 번째로

실제로 초과하는 요소를 찾으십시오.

__CAPGO_KEEP_0__

Capacitor

Set Capacitor iOS `contentInset` , Native Navigation의 CSS (또는 Native Navigation의) `never` 첫 번째로