이 튜토리얼에서, 우리는 새로운 React 앱에서 시작하여 Capacitor를 사용하여 네이티브 모바일 개발로 전환할 것입니다. Capgo 네이티브 네비게이션 및 전환을 추가하여 네이티브 모바일 느낌을 얻을 수 있고, 안전한 영역을 위해 tailwind-capacitor를 사용할 수 있습니다.
Capacitor는 React 웹 애플리케이션을 네이티브 모바일 앱으로 쉽게 변환할 수 있도록 해줍니다. 네이티브 모바일 앱으로 변환하는 데 필요한 수정이나 새로운 기술을 배우지 않아도 됩니다.
React 애플리케이션의 대부분은 몇 가지 단순한 단계만으로 네이티브 모바일 앱으로 변환할 수 있습니다.
이 튜토리얼에서는 새로운 React 앱에서 시작하여 Capacitor를 사용하여 네이티브 모바일 앱으로 전환하는 과정을 안내합니다. Capgo 네이티브 네비게이션, 전환, 및 tailwind-capacitor를 사용하여 안전한 영역을 얻을 수도 있습니다.
Capacitor에 대해 알아보기
CapacitorJS는 게임 체이저입니다! __CAPGO_KEEP_0__를 웹 프로젝트에 쉽게 통합할 수 있으며, 네이티브 웹뷰로 애플리케이션을.wrap하고, 네이티브 Xcode 및 Android Studio 프로젝트를 생성합니다. 플러그인은 JS 브리지를 통해 카메라와 같은 네이티브 장치 기능에 접근할 수 있습니다.
Capacitor를 사용하면 복잡한 설정이나 steep 러닝 커브 없이도 훌륭한 네이티브 모바일 앱을 얻을 수 있습니다. API가 얇고 Capacitor가 streamlined 기능을 제공하여 프로젝트에 쉽게 통합할 수 있습니다. Capacitor를 사용하면 네이티브 앱을 완전히 기능하는 앱으로 만들 수 있습니다.
React 앱을 준비하기
이 튜토리얼에서 가장 단순한 방법으로 React 애플리케이션을 시작하는 방법에 대해 설명합니다.
npx create-react-app my-appnative 모바일 앱을 만들기 위해서는 프로젝트의 __CAPGO_KEEP_0__ 을 export해야 합니다. 따라서 package.json에 단순한 스크립트를 포함하여 React 프로젝트를 빌드하고 export할 수 있도록 하겠습니다. 이제 __CAPGO_KEEP_0__
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}을 실행할 수 있습니다. npm run build 이 폴더는 __CAPGO_KEEP_0__
This folder will be used by Capacitor later on, but for now, we must set it up correctly.
Adding Capacitor to Your React App
React 앱에 __CAPGO_KEEP_0__ sync 를 추가하는 방법
우선적으로 우리는 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이 시점에서 React 프로젝트 내에서 새로운 ios 및 android 폴더를 관찰할 수 있어야 합니다.
그것들은 실제 네이티브 프로젝트입니다!
Android 프로젝트에 나중에 접근하려면 안드로이드 스튜디오. iOS의 경우 Mac가 필요하고 Xcode.
또한 프로젝트에서 capacitor.config.ts file in your project, which contains some fundamental Capacitor settings utilized during the sync. The only thing you need to pay attention to is the __CAPGO_KEEP_0__설정들이 포함되어 있습니다. 주의할 것은
webDir capacitor.config.json 이 값을 정확하게 하기 위해서는 __CAPGO_KEEP_0__.config.json:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}다음 명령어를 실행하여 시도해 보세요:
npm run build
npx cap sync첫 번째 명령어는 npm run build React 프로젝트를 빌드하고 정적 빌드를 내보내만 합니다.
두 번째 명령어는 npx cap sync 웹 code을 네이티브 플랫폼의 올바른 위치에同步시켜 앱에서 표시되도록합니다.
또한 Sync 명령어는 네이티브 플랫폼을 업데이트하고 플러그인을 설치할 수 있으므로 새로운 Capacitor 플러그인을 설치하면 다시 실행해야합니다. npx cap sync 알지 못한 채로 이제 실제로 완료되었습니다. 따라서 기기를 통해 앱을 확인해 보세요!
네이티브 앱 빌드 및 배포
iOS 앱을 개발하려면
네이티브 앱을 빌드하고 배포하는 데 필요한 iOS 앱을 만들려면 Xcode가 설치되어 있어야 하며, Android 앱을 만들려면 Android Studio가 설치되어 있어야 합니다. 또한 iOS와 Android 앱을 앱 스토어에 배포하려면 Apple Developer Program에 가입하고 Google Play Console에 가입해야 합니다. native 모바일 개발에 새로운 사람이라면 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__을 사용하여 쉽게 iOS와 Android의 native 프로젝트를 열 수 있습니다.
If you’re new to native mobile development, you can use the Capacitor CLI to easily open both native projects:
npx cap open ios
npx cap open androidandroid-studio-run
xcode-run
react-mobile-app
__CAPGO_KEEP_0__ __CAPGO_KEEP_1__
Capacitor Live Reload
__CAPGO_KEEP_0__ Live Reload __CAPGO_KEEP_0__ Live Reload __CAPGO_KEEP_0__ Live Reload
로컬로 호스팅된 애플리케이션에 대한 접근을 활성화하고 네트워크 내에서 Capacitor 앱이 특정 URL에서 콘텐츠를 로드하도록
__CAPGO_KEEP_0__ 앱이 특정 URL에서 콘텐츠를 로드하도록
ipconfig getifaddr en0__CAPGO_KEEP_0__ 앱이 특정 URL에서 콘텐츠를 로드하도록
ipconfig로컬 IP 주소를 찾는 첫 번째 단계입니다.
We can instruct Capacitor to load the app directly from the server by adding another entry to our capacitor.config.ts 윈도우즈에서 :를 실행하세요.
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'my-app',
webDir: 'out',
bundledWebRuntime: false,
server: {
url: 'http://192.168.x.xx:3000',
cleartext: true
}
};
export default config;정확한 IP 주소와 포트를 사용하십시오. 이 예시에서는 기본 React 포트를 사용했습니다.이제 이러한 변경 사항을 원시 프로젝트로 복사할 수 있습니다:
명령어는
npx cap copy와 유사하지만, copy 웹 폴더와 설정만 복사하고 원시 프로젝트를 업데이트하지 않습니다. sync이제 Android Studio 또는 Xcode를 통해 앱을 다시 배포할 수 있습니다. 그 후에, React 앱에서 변경 사항을 수정하면, 자동으로 앱이 다시 로드되고 변경 사항이 표시됩니다! __CAPGO_KEEP_0__
__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ __CAPGO_KEEP_0__
__CAPGO_KEEP_0__ 새로운 플러그인(카메라 등)을 설치하면 native 프로젝트를 다시 빌드해야 합니다. 이는 native 파일이 변경되었기 때문입니다. 빌드 작업은 즉시 수행할 수 없습니다.
정확한 IP와 포트를 사용하여 구성해야 합니다. code 블록은 React 기본 포트를 데모 목적으로 보여주고 있습니다.
Capacitor 플러그인 사용
이전에도 언급한 Capacitor 플러그인을 실제로 사용해 보겠습니다. 이를 위해 우리는 간단한 플러그인을 설치할 수 있습니다. 설치 방법은 다음과 같습니다.
npm i @capacitor/shareShare 플러그인은 특별한 기능이 없지만 native 공유 대화상자를 열 수 있습니다. 이 플러그인을 사용해 보겠습니다. Share 플러그인을 사용하기 위해서는 패키지를 임포트하고 해당 함수를 호출하면 됩니다. 앱의src/App.js share() 파일을 다음과 같이 변경해 보겠습니다. 새로운 플러그인을 설치하면 sync 작업을 수행하고 앱을 다시 배포해야 합니다. 이 작업을 수행하려면 다음 명령어를 실행해 주세요. 이 작업은 __CAPGO_KEEP_0__ 플러그인을 사용하는 것과 같습니다.
import React from 'react';
import { Share } from '@capacitor/share';
function App() {
const share = async () => {
await Share.share({
title: 'Open Youtube',
text: 'Check new video on youtube',
url: 'https://www.youtube.com',
dialogTitle: 'Share with friends'
});
};
return (
<div>
<h1>Welcome to React and Capacitor!</h1>
<p>
<h2>Cool channel</h2>
<button onClick={() => share()}>Share now!</button>
</p>
</div>
);
}
export default App;이 플러그인을 사용하기 위해서는 __CAPGO_KEEP_0__ 함수를 호출하면 됩니다.
npx cap sync버튼을 클릭한 후, 아름다운 네이티브 공유 대화창을 실제로 볼 수 있습니다!
다음으로, 앱이 iOS와 Android에서 더 네이티브하게 느껴지도록 Capgo 네비게이션과 전환을 사용하고, 일반적인 iOS 레이아웃 문제를 해결할 수 있습니다. 이 문제는 수평적 오버플로우 또는 잘린 안전 영역을 일으킵니다.
Capgo 네이티브 네비게이션과 전환으로 네이티브-feeling UI를 만들 수 있습니다.
10년 이상 동안 Ionic 을 사용하여 크로스 플랫폼 애플리케이션을 개발했지만, React와 통합하는 것은 복잡하고 드물게 가치가 있습니다. 이미 Tailwind CSS.
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 플러그인을 사용하는 것이 좋습니다. 웹 전용 UI 키트인 Konsta UI와 같은 대신: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-native-navigation
- @capgo/capacitor-transitions — iOS 스타일 페이지 전환 및 WebView layer에서 iOS 에지 스와이프-백을 사용할 수 있습니다. Ionic UI 를 채택하지 않습니다.
두 가지를 설치하십시오:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncCSS inset 모드를 사용하여 네이티브 네비게이션을 구성하여 웹 콘텐츠가 네이티브 바를 존중하십시오:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});리퀴드 글라스 탭 바를 렌더링하십시오 (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>;
}루트된 페이지를 cap-router-outlet, cap-page, cap-content, setDirection('forward') , setDirection('back') ,
, Using @capgo/capacitor-native-navigation __Korean__ @capgo/capacitor-transitions.
안전 영역에 대한 Tailwind
Tailwind CSS에서 장치 안전 영역을 사용하기 위해 @capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 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";Use utilities such as pt-safe, pb-safe, and px-safe 대신에 Tailwind의 다양한 기능을 사용합니다. env(safe-area-inset-*) 손으로 만들었습니다. 이 프로젝트는 활발하게 개발되고 있으므로, React 설정에 필요한 항목이 누락된 경우 GitHub에 PR을 열어주세요..
iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤)
iOS에서 콘텐츠가 잘려나가거나-shifted-되거나 가로 스크롤이 가능한 경우, 추가적인 overflow-x: hidden 또는 뷰포트 태그만 조정하는 것만으로 문제를 해결할 수 없습니다. 이러한 체크를 순서대로 진행하세요.
뷰포트 메타 태그가 올바르게 적용되었는지 확인하세요.
뷰포트 메타 태그를 추가하세요. index.html 내부에 <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />iOS 안전 영역을 하나의 루트 wrapper에서만 처리하세요.
싱글 앱 셸을 생성하고 안전 영역 패딩을 적용하세요. 여러 개의 중첩된 컴포넌트에서 패딩을 적용하는 것은 좋지 않습니다.
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);
}모든 페이지 콘텐츠를 내부에 wrapping하세요. .app-shell. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 적용된 경우 UI가 잘려나가거나 너무 큰 경우가 발생합니다.
__CAPGO_KEEP_0__ @capgo/tailwind-capacitor__CAPGO_KEEP_0__ pt-safe pb-safe px-safe __CAPGO_KEEP_0__
Capacitor contentInset __CAPGO_KEEP_0__ never __CAPGO_KEEP_0__
__CAPGO_KEEP_0__ capacitor.config.ts__CAPGO_KEEP_0__ contentInsetMode: 'css'__CAPGO_KEEP_0__
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Capacitor env(safe-area-inset-*) __CAPGO_KEEP_0__
__CAPGO_KEEP_0__의 실제 넘치는 요소를 찾으세요
The usual culprit는 요소가 사용하는 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,
}));, w-screen Tailwind의 경우 w-full , 100vw / w-screen가능한 경우에
,
Capacitor is an excellent option for building native applications based on an existing web project, offering a simple way to share code and maintain a consistent UI.
, Capgo최신 기능과 버그 수정을 포함하여 항상 최신 버전의 앱에 접근할 수 있도록하는 라이브 업데이트를 추가하는 것이 __CAPGO_KEEP_0__보다도 더 쉬워졌습니다.
Capgo을 React 앱에 추가하는 방법을 배우고 싶다면, 다음 기사를 참조하세요.
React와 Capacitor를 사용하여 모바일 앱을 빌드하는 것에서 계속 진행하세요.
__CAPGO_KEEP_0__을 사용하고 있다면 React와 Capacitor를 사용하여 모바일 앱을 빌드하는 것 __CAPGO_KEEP_0__ CI/CD Capgo CI/CD의 제품 워크플로우 Capgo Native Builds Capgo Native Builds의 제품 워크플로우 Capgo Integrations Capgo 제품 워크플로우에서 Capgo 통합에 대해 CI/CD 통합 __CAPGO_KEEP_0__ 통합에 대한 구현 세부 정보 GitHub 액션 통합 GitHub 액션 통합에 대한 구현 세부 정보
