가이드
Capacitor에서 Native Navigation 사용법
@capgo/capacitor-native-navigation 사용하기
@capgo/capacitor-native-navigation 단일 전체 화면 Capacitor WebView 위에 네이티브 상단 네비게이션, 하단 탭 크롬, 라우트 전환 셸을 렌더링합니다. 라우트와 콘텐츠는 기존 웹 프레임워크가 관리하고, 앱 프레임은 네이티브가 담당합니다.
설치 및 동기화
npm install @capgo/capacitor-native-navigation
npx cap sync
네이티브 프레임 설정
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
colors: {
tint: '#0f172a',
inactiveTint: '#64748b',
},
});
네이티브 navbar 렌더링
await NativeNavigation.setNavbar({
title: 'Inbox',
subtitle: 'Native chrome',
transparent: true,
backButton: { visible: false },
rightItems: [
{
id: 'compose',
title: 'Compose',
icon: {
svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z"/></svg>',
},
},
],
});
navbar 하단에 멀티 레벨 세그먼트 행 추가
전달하세요: segments 대상 setNavbar 바 아래에 네이티브 세그먼트 행을 쌓는 기능입니다. 예를 들어 위에는 스코프 스위처, 아래에는 섹션 탭을 둘 수 있습니다. 행은 위에서 아래로 그려지고, 각 행은 navbar와 보고되는 insets에 44pt(iOS) 또는 48dp(Android)를 더합니다. iOS는 UISegmentedControl 그리고 글래스 필을 사용하며, Android는 Material segmented buttons와 filter chips를 사용합니다.
| iOS | Android |
|---|---|
 |
 |
const sections = {
account: ['General', 'Notifications', 'Password', 'Two-factor'],
organization: ['General', 'Members', 'Plans', 'Usage', 'Credits', 'Billing', 'Security', 'Webhooks'],
};
const selection = { scope: 'account', section: 'general' };
const renderNavbar = () =>
NativeNavigation.setNavbar({
title: 'Settings',
segments: [
{
id: 'scope',
selectedId: selection.scope,
items: [
{ id: 'account', title: 'Account' },
{ id: 'organization', title: 'Organization' },
],
},
{
id: 'section',
style: 'scroll', // scrolling chips; `auto` uses `segmented` for up to 4 items
selectedId: selection.section,
items: sections[selection.scope].map((title) => ({ id: title.toLowerCase(), title })),
},
],
});
await NativeNavigation.addListener('navbarSegmentSelect', async ({ groupId, id }) => {
if (groupId === 'scope') {
selection.scope = id;
selection.section = 'general'; // the second level depends on the first one
} else {
selection.section = id;
}
await renderNavbar();
});
await renderNavbar();
사용자가 탭하면 선택 항목이 네이티브로 이동하지만, setNavbar 호출할 때마다 selectedId 다시 적용됩니다. 선택한 id를 state에 유지하고 이후의 모든 setNavbar 호출 시 전달하세요. 선택을 거부하려면 이전 값을 selectedId로 보내세요. 항목은 다음도 받습니다 icon, accessibilityLabel, 그리고 enabled. 전달하세요 segments: [] 행을 제거하려면 사용하세요. 8.13.0부터 사용 가능합니다.
네이티브 tabbar 렌더링
await NativeNavigation.setTabbar({
selectedId: 'inbox',
labelVisibilityMode: 'selected',
icons: true,
colors: {
dynamic: true,
tint: '#0f172a',
inactiveTint: '#64748b',
},
tabs: [
{
id: 'inbox',
title: 'Inbox',
icon: {
svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16v16H4z"/><path d="m4 13 4 4h8l4-4"/></svg>',
},
},
{
id: 'search',
title: 'Search',
icon: {
svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"/><path d="m20 20-3-3"/></svg>',
},
},
],
});
네이티브 이벤트를 라우터에 연결
네이티브 바가 intent를 발화합니다. 라우터가 여전히 라우트 변경을 수행합니다:
await NativeNavigation.addListener('navbarBack', () => {
router.back();
});
await NativeNavigation.addListener('navbarItemTap', ({ id }) => {
if (id === 'compose') router.push('/compose');
});
await NativeNavigation.addListener('tabSelect', ({ id }) => {
router.push(`/${id}`);
});
라우트 변경 애니메이션
일반적인 웹 라우트 업데이트 주위에 transition transaction을 사용하세요:
const transition = await NativeNavigation.beginTransition({
direction: 'forward',
});
router.push('/message/42');
await router.ready?.();
await NativeNavigation.setNavbar({
title: 'Message',
backButton: { visible: true, title: 'Inbox' },
});
await NativeNavigation.finishTransition({
id: transition.id,
direction: 'forward',
});
줌 전환 효과 추가
카드, 그리드 항목, 미디어 미리보기에서 열리는 라우트에 zoom 헬퍼를 사용하세요.
import { beginZoomTransition, finishZoomTransition } from '@capgo/capacitor-native-navigation';
const card = document.querySelector('[data-message-card]');
if (card) {
const transition = await beginZoomTransition(card, { cornerRadius: 18 });
router.push('/message/42');
await router.ready?.();
await NativeNavigation.setNavbar({
title: 'Message',
backButton: { visible: true, title: 'Inbox' },
});
await finishZoomTransition(undefined, {
id: transition.id,
cornerRadius: 18,
});
}
네이티브 인셋으로 콘텐츠 여백 조정
시기 contentInsetMode 이며 css, 플러그인은 네이티브 바용 CSS 변수를 씁니다:
.page {
padding-top: var(--cap-native-navigation-top);
padding-bottom: var(--cap-native-navigation-bottom);
}
아이콘 선택 옵션
아이콘은 React나 Vue 노드가 아니라 네이티브 디스크립터입니다. 네이티브 에셋을 번들하지 않으려면 SVG를 사용하세요:
const icon = {
svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
template: true,
ios: { sfSymbol: 'house.fill' },
android: { resource: 'ic_menu_view' },
};
인라인 SVG는 다음을 지원합니다 path, line, polyline, polygon, circle, 그리고 rect, Lucide와 Feather 같은 주요 아이콘 세트를 커버합니다.
@capgo/capacitor-transitions와 함께 사용
네이티브 navbar, tabbar, safe-area inset, 네이티브 intent 이벤트에는 Native Navigation을 사용하세요. 또한 @capgo/capacitor-transitions 해당 네이티브 크롬 아래의 WebView 페이지 스택용입니다.
npm install @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npx cap sync
두 패키지를 한 번만 초기화하세요:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
import '@capgo/capacitor-transitions';
import { initTransitions, setupRouterOutlet, setDirection } from '@capgo/capacitor-transitions/react';
initTransitions({ platform: 'auto' });
const outlet = document.querySelector('cap-router-outlet');
if (outlet) {
setupRouterOutlet(outlet, { platform: 'auto', swipeGesture: 'auto' });
}
await NativeNavigation.configure({
contentInsetMode: 'css',
});
transition outlet이 페이지에만 집중하도록 하고, 웹 바를 중복하지 마세요:
<cap-router-outlet platform="auto" swipe-gesture="auto">
<cap-page>
<cap-content slot="content" fullscreen>
<main class="page">Inbox content</main>
</cap-content>
</cap-page>
</cap-router-outlet>
동일한 라우터 액션으로 두 패키지를 모두 제어하세요:
async function openMessage(id: string) {
setDirection('forward');
await router.push(`/messages/${id}`);
await NativeNavigation.setNavbar({
title: 'Message',
backButton: { visible: true, title: 'Inbox' },
});
}
await NativeNavigation.addListener('navbarBack', () => {
setDirection('back');
router.back();
});
await NativeNavigation.addListener('tabSelect', ({ id }) => {
setDirection('root');
router.push(`/${id}`);
});
경로 변경마다 애니메이션 레이어는 하나만 선택하세요. 일반적인 @capgo/capacitor-transitions 페이지 push에는 애니메이션을 적용하고, Native Navigation의 zoom helper는 shared-element나 zoom 경로에만 사용하세요.
전체 레퍼런스
- GitHub: https://github.com/Cap-go/capacitor-native-navigation/
- 문서: /docs/plugins/native-navigation/
@capgo/capacitor-native-navigation 사용하기에서 계속하기
사용 중이라면 @capgo/capacitor-native-navigation 사용하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-native-navigation 구현 세부 사항은 @capgo/capacitor-native-navigation에서, 시작하기 Getting Started의 구현 상세 내용은 @capgo/capacitor-live-activities 사용 @capgo/capacitor-live-activities 사용에서의 네이티브 기능, @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항은, 그리고 @capgo/capacitor-video-player 사용 @capgo/capacitor-video-player. 사용하기에서의 네이티브 기능은