이 튜토리얼에서 우리는 새로운 React app and transition to native mobile development using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.
Capacitor allows you to easily convert your React web application into a native mobile app without significant modifications or learning a new skill like React Native.
React 앱을 모바일 앱으로 쉽게 변환할 수 있습니다.
이 튜토리얼은 React 앱을 새로 만들고 Capacitor를 사용하여 네이티브 모바일 앱으로 이동하는 과정을 안내합니다. 또한 Capgo 네이티브 네비게이션, 전환, tailwind-capacitor를 사용하여 안전한 영역을 사용할 수 있습니다.
Capacitor에 대해 알아보세요.
__CAPGO_KEEP_0__는 게임 체이너입니다! 웹 프로젝트에 쉽게 통합할 수 있으며, 네이티브 웹뷰로 애플리케이션을.wrap하고, 네이티브 Xcode 및 Android Studio 프로젝트를 생성합니다. 또한 플러그인은 JS 브리지를 통해 카메라와 같은 네이티브 장치 기능에 접근할 수 있습니다.
Capacitor를 사용하면 복잡한 설정이나 steep 학습 곡선이 없이도 훌륭한 네이티브 모바일 앱을 얻을 수 있습니다. API가 얇고 Capacitor가 streamlined 기능을 제공하여 프로젝트에 쉽게 통합할 수 있습니다. 믿을 수 없을 정도로 Capacitor를 사용하여 네이티브 앱을 완전히 기능하는 앱을 쉽게 만들 수 있습니다.
React 앱을 준비하세요.
튜토리얼에서 제공하는 가장 단순한 방법으로 React 앱을 시작할 수 있습니다.
npx create-react-app my-appnative 모바일 앱을 만들기 위해서는 export __CAPGO_KEEP_0__는 __CAPGO_KEEP_1__를 export하는 것을 의미합니다. __CAPGO_KEEP_0__는 package.json에 포함된 스크립트를 의미합니다. __CAPGO_KEEP_0__를 실행하여 React 프로젝트를 빌드하고 export할 수 있습니다.
{
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
}
}__CAPGO_KEEP_0__를 실행하여 React 프로젝트를 빌드하고 export할 수 있습니다. npm run build 어떤 걱정 없이, 당신은 프로젝트의 루트에 새로운 폴더를 찾을 수 있어야 합니다.
이 폴더는 나중에 Capacitor에 의해 사용될 것입니다. 그러나 현재는 올바르게 설정해야 합니다.
Adding Capacitor to Your React App
웹 앱을 네이티브 모바일 컨테이너로 패키징하려면 몇 가지 초기 단계를 따르면, 나중에 단일 명령어만 실행하면 됩니다. sync command.
다음으로, iOS 및 Android 플랫폼에 대한 관련 패키지를 설치해야 합니다. Capacitor CLI 이 시점에서, 새로운 폴더를 프로젝트의 루트에 찾을 수 있어야 합니다.
ios
마지막으로 플랫폼을 추가할 수 있습니다. 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 androidios android 그리고 안드로이드 React 프로젝트의 폴더들입니다.
실제로 네이티브 프로젝트입니다!
앱을 나중에 접근하기 위해 Android 프로젝트를 설치해야 합니다. 안드로이드 스튜디오. iOS의 경우 Mac이 필요하며 Xcode를 설치해야 합니다. Xcode.
__CAPGO_KEEP_0__.config.ts 파일은 프로젝트에 기본적인 capacitor 설정을 포함하고 있습니다. 프로젝트를 동기화하는 동안 사용되는 설정입니다. 주의할 것은 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 입니다.현재, 이는 명령어의 결과로 생성된 빌드 결과를 가리키지 않습니다. 정확하지 않습니다.
이 문제를 해결하기 위해, capacitor.config.json 파일을 열고 webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "out",
"bundledWebRuntime": false
}를 업데이트 하세요.
npm run build
npx cap sync다음 명령어를 실행하여 시도해 보세요: npm run build 첫 번째 명령어는
React 프로젝트를 빌드하고 정적 빌드를 내보냅니다. npx cap sync 모바일 앱을 위한 React 앱을 Capacitor를 사용하여 만들 때, Capacitor는 웹 code을 네이티브 플랫폼의 올바른 위치로 동기화하여 앱에서 표시할 수 있도록 합니다.
웹 __CAPGO_KEEP_0__을 Capacitor plugins 이제 다시 실행하세요. npx cap sync 다시.
실제로 이제 완료되었습니다. 이제 기기에서 앱을 확인해 보세요!
자연스럽게 네이티브 앱을 빌드하고 배포하세요.
iOS 앱을 개발하려면 Xcode 설치되어 있어야 하며 안드로이드 앱의 경우에는 android-studio-run __CAPGO_KEEP_0__ : Capacitor
만약 네이티브 모바일 개발에 새로운 사람이라면 Capacitor CLI을 사용하여 네이티브 프로젝트를 쉽게 열 수 있습니다.
npx cap open ios
npx cap open androidXcode
In Xcode, 앱을 실제 기기에서 실행하기 위해 서명 계정을 설정해야 합니다. 시뮬레이터에서만 실행하는 경우가 아니라면. 이 과정을 처음으로 진행하는 경우 Xcode는 개발자 프로그램에 등록되어 있어야만 이 과정을 안내해 줍니다. 그 후에, 연결된 기기를 선택하여 위쪽에서 실행을 시작할 수 있습니다. 예시를 보겠습니다.
성공했습니다! React 웹 앱을 모바일 기기에서 성공적으로 배포했습니다. 예시를 보겠습니다.
하지만, 개발 중에는 더 빠른 방법이 있습니다.
Capacitor 실시간 리로드
이제 대부분의 프레임워크에서 사용하는热 재로드에 익숙해졌을 것입니다. 좋은 소식은 React 앱을 모바일 기기에서도 동일한 기능을 사용할 수 있다는 것입니다. 모바일 기기에서 최소한의 노력으로도 동일한 기능을 사용할 수 있습니다. 로컬 호스트 앱에 대한 접근을 활성화하고 네트워크에서 __CAPGO_KEEP_0__ 앱이 특정 URL에서 콘텐츠를 로드하도록 하세요.
__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ Capacitor
첫 번째 단계는 로컬 IP 주소를 찾는 것입니다. 맥을 사용하는 경우 터미널에서 다음 명령어를 실행하여 이를 찾을 수 있습니다:
ipconfig getifaddr en0윈도우에서 실행:
ipconfig그런 다음 IPv4 주소를 찾습니다.
Capacitor을 서버에서 앱을 직접 로드하도록 지시하기 위해 우리의 파일에 추가 항목을 추가할 수 있습니다. capacitor.config.ts file:
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;이 예에서는 기본 React 포트를 사용했습니다. 이러한 변경 사항을 적용하려면 native 프로젝트에 복사하세요:명령어는
와 유사하지만
npx cap copy만큼만 copy 명령어는 Live Update와 비슷합니다. sync하지만 그것은 단지 변경 사항을 웹 폴더에 복사하세요. 그리고 구성만 업데이트하지 마세요.
이제 Android Studio 또는 Xcode를 통해 앱을 한 번 더 배포할 수 있습니다. 그 후에, React 앱에서 변경 사항이 생기면 앱은 자동으로 다시 로드되고 변경 사항을 보여줍니다!
주의해야 할 점은 새로운 플러그인인 카메라를 설치하면 여전히 네이티브 프로젝트를 다시 빌드해야 합니다. 이는 네이티브 파일이 변경되었기 때문입니다. 이 작업은 실시간으로 수행할 수 없습니다.
주의해야 할 점은 구성에서 올바른 IP와 포트를 사용해야 한다는 것입니다. 위의 code 블록은 데모를 위해 기본 React 포트를 보여주고 있습니다.
Capacitor 플러그인 사용
Capacitor 플러그인을 사용하는 방법에 대해 살펴보겠습니다. 이를 위해 우리는 이전에 언급한 플러그인을 설치할 수 있습니다. 이를 설치하려면 다음 명령어를 실행하세요:
npm i @capacitor/share이 플러그인은 특별한 기능이 없습니다. Share 플러그인하지만 native share dialog이 나타나고 있습니다. 이 경우에는 package를 import하고 app에서 함수를 호출하는 것만 필요합니다. share() function을 호출하기 위해 app의 src/App.js를 다음과 같이 변경해 보겠습니다. src/App.js 이것으로 시작하세요
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;react-__CAPGO_KEEP_0__-share
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 네이티브 네비게이션 및 전환
react-__CAPGO_KEEP_0__-share Ionic I’ve worked for years with Ionic to build cross-platform applications, but integrating it with React is hacky and rarely worth it when you already have 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:
- @capgo/capacitor-native-네비게이션 네이티브 네비게이션 바, iOS에서 Liquid Glass 탭 바, Android에서 흐린 탭 바 스타일을 사용하세요. React 라우터는 경로 상태를 유지하고 플러그인은 네이티브 창을 관리합니다.
- @capgo/capacitor-transition iOS 에지 스와이프 백과 WebView layer에서 Ionic-style 페이지 전환을 사용하세요. Ionic UI를 채택하지 않습니다.
두 가지 모두 설치하세요.
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는 흐린 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, and cap-content그리고 호출 setDirection('forward') 또는 setDirection('back') 웹 헤더나 푸터를 중복하지 마십시오. 네이티브 네비게이션이 그 표면을 소유할 때.
자세한 안내서를 참조하십시오: capgo/capacitor-네이티브-네비게이션을 사용하는 방법 그리고 capgo/capacitor-전환을 사용하는 방법.
안전 영역에 대한 정보
디바이스의 안전 영역을 Tailwind CSS에서 사용하려면 capgo/tailwind-capacitor (__CAPGO_KEEP_0__에서 출판) tailwind-capacitor npm에서 제공하는 기능입니다. safe-areas 기능 및 기타 Capacitor-친화적인 Tailwind 플러그인:
bun add -D tailwind-capacitorIn src/index.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";사용할 수 있는 기능을 사용하십시오. pt-safe, pb-safe, 그리고 px-safe 대신에 수동으로 기능을 뿌려주지 마십시오. 프로젝트는 활발히 개발되고 있으니, React 설정에 필요한 기능이 누락된 경우 env(safe-area-inset-*) __CAPGO_KEEP_0__에 PR을 열어보십시오. GitHub에 대한 PR을 열기.
iOS에서 콘텐츠가 잘려나거나-shifted되거나 가로 스크롤이 가능하다면, 뷰포트 태그만 추가하거나 조정하는 것만으로는 해결되지 않습니다. 이 순서대로 체크해 보십시오.
뷰포트 메타 태그가 올바르게 적용되었는지 확인하십시오. overflow-x: hidden 뷰포트 메타 태그를
추가하십시오.
iOS 레이아웃 문제 해결 (뷰포트, 안전 영역, 가로 스크롤) 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);
}모든 페이지 콘텐츠를 내부에 감싸세요 .app-shell. 중복된 안전 영역 패딩이 헤더, 모달, 레이아웃 wrapper에 적용되어 UI가 잘린 것처럼 보이거나 너무 크게 보이는 문제를 해결하세요.
그리고 @capgo/tailwind-capacitor@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ pt-safe pb-safe px-safe 와 함께, 같은 패딩을 표현할 수 있는 유틸리티를 사용하세요.
Set Capacitor iOS contentInset iOS never 를
In capacitor.config.ts, native inset을 사용하고 CSS (또는 Native Navigation의 )가 safe area를 관리하도록 하세요: contentInsetMode: 'css'Mixing __CAPGO_KEEP_0__의 자동 콘텐츠 inset과 CSS padding은 일반적인 double spacing의 원인이 됩니다.
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) 일반적으로 요소가
, Tailwind
, 고정 픽셀 너비, 또는 100vw, Tailwind w-screenTailwind의 경우 min-width.
를 사용하세요
[...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,
}));with w-screen with w-full 가능할 때. 많은 가로 방향으로 넘치는 문제는 100vw / w-screen결론
Conclusion
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_KEEP_0__ Capgo__CAPGO_KEEP_0__
Capgo
Capacitor
__CAPGO_KEEP_0__ Capacitor __CAPGO_KEEP_0__ Capgo CI/CD Capgo CI/CD를 위한 제품 워크플로우 Capgo 원시 빌드 Capgo Native Builds를 위한 제품 워크플로우 Capgo 통합(Integrations) Capgo Integrations CI/CD 통합 __CAPGO_KEEP_0__ Actions Integration GitHub 액션 통합 Capacitor 구현 세부 사항에 대한 GitHub 액션 통합.
