@capgo/capacitor-transitions 사용하기
@capgo/capacitor-transitions Ionic UI를 도입하지 않고도 Capacitor 앱에 Ionic 스타일의 라우트 전환 효과를 추가합니다. 웹 레이어에서 실행되어 기존 라우터를 그대로 유지하며, iOS Native Capacitor 환경에서만 iOS edge swipe-back 제스처를 자동으로 활성화할 수 있습니다.
설치
npm install @capgo/capacitor-transitions
이 패키지는 네이티브 플러그인 code을 추가하지 않으므로 별도의 네이티브 동기화 단계가 필요 없습니다.
요소 등록하기
import '@capgo/capacitor-transitions';
페이지 래핑하기
<cap-router-outlet platform="auto" swipe-gesture="auto">
<cap-page>
<cap-header slot="header">
<h1>Inbox</h1>
</cap-header>
<cap-content slot="content">
<button>Open message</button>
</cap-content>
<cap-footer slot="footer">
<nav>Tabs</nav>
</cap-footer>
</cap-page>
</cap-router-outlet>
라우터에 연결하기
일반적인 라우트 업데이트 전에 전환 방향을 설정하세요:
import { setDirection } from '@capgo/capacitor-transitions/react';
setDirection('forward');
router.push('/message/42');
setDirection('back');
router.back();
React 예제
import { useEffect, useRef } from 'react';
import { useNavigate } from 'react-router-dom';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/react';
import '@capgo/capacitor-transitions';
initTransitions({ platform: 'auto' });
export function AppShell() {
const outletRef = useRef<HTMLElement>(null);
useEffect(() => {
if (!outletRef.current) return;
setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
}, []);
return <cap-router-outlet ref={outletRef}>{/* routes */}</cap-router-outlet>;
}
export function InboxPage() {
const navigate = useNavigate();
const pageRef = useRef<HTMLElement>(null);
useEffect(() => {
if (!pageRef.current) return;
return setupPage(pageRef.current);
}, []);
return (
<cap-page ref={pageRef}>
<cap-header slot="header">
<h1>Inbox</h1>
</cap-header>
<cap-content slot="content">
<button
onClick={() => {
setDirection('forward');
navigate('/message/42');
}}
>
Open message
</button>
</cap-content>
</cap-page>
);
}
React 하위 경로에는 커스텀 요소를 위한 JSX 타이핑이 포함되어 있습니다. 만약 TypeScript에서 여전히 cap-router-outlet 이(가) 다음에서 존재하지 않는다고 표시되면: JSX.IntrinsicElements다음 파일을 추가하세요:
// src/capgo-transitions.d.ts
import '@capgo/capacitor-transitions/react';
Vite, Create React App 및 대부분의 webpack React 앱의 경우, 해당 파일을 다음 경로에 유지하세요: src/ 만으로 충분합니다. Next.js 또는 커스텀 TypeScript 구성에서는 다음을 통해 포함되어 있는지 확인하세요: tsconfig.json:
{
"include": ["src", "src/capgo-transitions.d.ts"]
}
뒤로 가기 스와이프 활성화
사용 swipe-gesture="auto" Capacitor가 iOS 네이티브 런타임을 보고할 때만 제스처를 활성화하려면:
<cap-router-outlet swipe-gesture="auto"></cap-router-outlet>
JavaScript에서 강제로 활성화할 수도 있습니다:
const outlet = document.querySelector('cap-router-outlet');
outlet?.setSwipeGesture(true);
outlet?.setSwipeGesture(false);
outlet?.setSwipeGesture('auto');
제스처는 전환 중에 손가락을 따라 움직이며, 사용자가 손을 떼면 완료되거나 취소됩니다. 다음을 추가하세요: data-swipe-gesture-ignore 에지 제스처가 시작되지 않아야 하는 버튼, 슬라이더, 드로어에 적용하세요.
네이티브 네비게이션과 함께 사용
설치 @capgo/native-navigation 네이티브 레이어가 navbar 또는 tabbar를 제어해야 하는 경우:
npm install @capgo/native-navigation
npx cap sync
네이티브 chrome을 구성한 다음, 전환은 WebView 페이지에 집중되도록 유지하세요:
import { NativeNavigation } from '@capgo/native-navigation';
import { setDirection } from '@capgo/capacitor-transitions/react';
import { router } from './router';
await NativeNavigation.configure({
contentInsetMode: 'css',
});
await NativeNavigation.setNavbar({
title: 'Inbox',
backButton: { visible: false },
});
await NativeNavigation.addListener('navbarBack', () => {
setDirection('back');
router.back();
});
async function openMessage(id: string) {
setDirection('forward');
router.push(`/message/${id}`);
await NativeNavigation.setNavbar({
title: 'Message',
backButton: { visible: true, title: 'Inbox' },
});
}
사용 cap-content 애니메이션 페이지 본문 및 인셋(insets) 처리를 위한 native-navigation CSS 변수:
<cap-router-outlet platform="auto" swipe-gesture="auto">
<cap-page>
<cap-content slot="content" fullscreen>
<main class="native-page">Inbox content</main>
</cap-content>
</cap-page>
</cap-router-outlet>
.native-page {
padding-top: var(--cap-native-navigation-top);
padding-bottom: var(--cap-native-navigation-bottom);
}
네이티브 navbar를 움직이는 웹 헤더로 중복 구현하지 마세요. @capgo/native-navigation 바(bar)를 네이티브 상태로 유지하며, @capgo/capacitor-transitions 그 아래의 페이지 콘텐츠를 애니메이션 처리합니다.
전체 레퍼런스
- GitHub: https://github.com/Cap-go/capacitor-transitions/
- 문서: /docs/plugins/transitions/
@capgo/capacitor-transitions 사용하기 다음 단계
사용 중이라면 @capgo/capacitor-transitions 사용하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-transitions @capgo/capacitor-transitions의 구현 세부 사항은 시작하기 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. 사용하기에서의 네이티브 기능은