시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-transitions` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

1. 패키지 설치

   npm install @capgo/capacitor-transitions

2. 웹 컴포넌트 등록

   import '@capgo/capacitor-transitions';

3. 라우팅된 페이지 감싸기

   <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>

4. 라우터가 경로를 변경하기 전에 방향을 설정하세요

   import { setDirection } from '@capgo/capacitor-transitions/react';
   
   setDirection('forward');
   router.push('/message/42');
   
   setDirection('back');
   router.back();

참고

이 패키지에는 네이티브 동기화 단계가 없습니다. Capacitor 앱의 웹 레이어에서 실행됩니다.

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}>
      {/* Your router renders cap-page children here. */}
    </cap-router-outlet>
  );
}

export function InboxPage() {
  const navigate = useNavigate();
  const pageRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (!pageRef.current) return;

    return setupPage(pageRef.current, {
      onDidEnter: () => console.log('Inbox visible'),
    });
  }, []);

  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

다음에서 import하면 @capgo/capacitor-transitions/react 다음에 대한 JSX 타입이 포함됩니다: cap-router-outlet, cap-page, cap-header, cap-content, 그리고 cap-footer. 대부분의 React 프로젝트에서는 이 import로 TSX에서 커스텀 엘리먼트가 자동으로 유효해집니다.

TypeScript에서 여전히 오류가 보고되면 Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements', 프로젝트 선언 파일을 추가하세요:

src/capgo-transitions.d.ts

import '@capgo/capacitor-transitions/react';

Vite, Create React App 및 대부분의 webpack React 앱에서는 해당 파일을 src/ 안에 두면 충분합니다. Next.js의 경우, src/ 또는 프로젝트 루트에 넣고 tsconfig.json 이 해당 파일을 포함하는지 확인하세요:

{
  "include": ["src", "src/capgo-transitions.d.ts"]
}

커스텀 TypeScript 또는 webpack 설정에서 별도의 types/ 폴더를 사용하는 경우, 대신 해당 폴더를 포함하세요:

{
  "include": ["src", "types"]
}

스와이프 백

마크업에서 iOS edge gesture를 활성화하거나 비활성화합니다:

<cap-router-outlet swipe-gesture="auto"></cap-router-outlet>
<cap-router-outlet swipe-gesture="true"></cap-router-outlet>
<cap-router-outlet swipe-gesture="false"></cap-router-outlet>

또는 JavaScript에서:

const outlet = document.querySelector('cap-router-outlet');

outlet?.setSwipeGesture('auto');
outlet?.setSwipeGesture(true);
outlet?.setSwipeGesture(false);

auto Capacitor가 native iOS runtime을 보고할 때만 제스처를 활성화합니다. 제스처 중에는 페이지 전환이 손가락 움직임을 따라갑니다. 사용자가 손을 떼면 전환이 완료되어 브라우저 히스토리가 뒤로 가거나, 전환이 취소되어 현재 페이지가 복구됩니다.

특정 요소가 제스처를 시작하지 못하게 하려면 다음을 추가하세요: data-swipe-gesture-ignore:

<button data-swipe-gesture-ignore>Open drawer</button>

Native Navigation 사용 시

사용 @capgo/capacitor-transitions 포함 @capgo/native-navigation 웹 콘텐츠는 Ionic 스타일의 페이지 모션을 유지하면서, 상단 및 하단 바는 native가 제어해야 할 때 사용합니다.

1. native navigation 패키지를 설치하고 sync 하세요:

   npm install @capgo/native-navigation
   npx cap sync

2. 네이티브 크롬 설정:

   import { NativeNavigation } from '@capgo/native-navigation';
   
   await NativeNavigation.configure({
     contentInsetMode: 'css',
   });
   
   await NativeNavigation.setNavbar({
     title: 'Inbox',
     backButton: { visible: false },
   });

3. 웹 전환 아울렛은 페이지 전환만 담당하도록 설정하세요:

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

4. 동일한 라우터 이벤트를 통해 두 시스템을 제어하세요:

   import { NativeNavigation } from '@capgo/native-navigation';
   import { setDirection } from '@capgo/capacitor-transitions/react';
   import { router } from './router';
   
   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-header>. @capgo/native-navigation 상단 바는 네이티브 상태를 유지하고, @capgo/capacitor-transitions 그 아래 WebView 페이지 콘텐츠에 사용하세요.

컴포넌트

<cap-router-outlet>

항목	유형	기본값	설명
platform	'ios' | 'android' | 'auto'	'auto'	애니메이션 스타일
duration	number	플랫폼 기본값	애니메이션 지속 시간 (ms)
keep-in-dom	boolean	true	비활성 페이지를 DOM에 유지
max-cached	number	10	최대 캐시 페이지 수
swipe-gesture	boolean | 'auto'	'auto'	iOS edge gesture 활성화, 비활성화 또는 네이티브 감지 설정

사용 가능한 메서드:

• push(element, config?)
• pop(config?)
• setRoot(element, config?)
• setSwipeGesture(true | false | 'auto')

<cap-page>

단일 페이지를 감싸며 라이프사이클 이벤트를 발생시킵니다:

• cap-will-enter
• cap-did-enter
• cap-will-leave
• cap-did-leave

<cap-content>

항목	유형	기본값	설명
fullscreen	boolean	false	헤더 뒤로 콘텐츠가 스크롤되도록 설정
scroll-x	boolean	true	가로 스크롤 활성화
scroll-y	boolean	true	세로 스크롤 활성화

Framework 헬퍼

프레임워크 엔트리포인트는 동일한 핵심 헬퍼를 제공합니다:

import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });
setDirection('forward');
setupRouterOutlet(element, { platform: 'auto', swipeGesture: 'auto' });
setupPage(element, { onWillEnter, onDidEnter, onWillLeave, onDidLeave });

사용 가능한 엔트리포인트:

• @capgo/capacitor-transitions/react
• @capgo/capacitor-transitions/vue
• @capgo/capacitor-transitions/angular
• @capgo/capacitor-transitions/svelte
• @capgo/capacitor-transitions/solid

시작하기 다음 단계

사용 중이라면 시작하기 마이그레이션과 엔터프라이즈 운영을 계획하려면 다음과 연결하세요: @capgo/capacitor-transitions 사용하기 @capgo/capacitor-transitions 사용 시 네이티브 기능 지원 Capgo 엔터프라이즈 Capgo Enterprise의 제품 워크플로우를 위해, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우를 위해, Capgo 대안 Capgo 대안의 제품 워크플로우를 위해, 그리고 Capgo 컨설팅 Capgo Consulting의 제품 워크플로우를 위해.