@capgo/capacitor-native-loader

네이티브 렌더링 경로

WebView에 비용이 많이 드는 반투명 효과 애니메이션을 요청하는 대신, UIKit 및 Android 오버레이 뷰로 로더를 표시합니다.

유연한 배치

전체 화면, 중앙, 가장자리 고정, Chrome 스타일 상단, 또는 safe-area를 고려한 WebView 주변 배치 등 다양한 설정이 가능합니다.

내장 및 에셋 로더

Siri 스타일, Siri v2 에지, Chrome 상단 프로그레스, orbit, ring, pulse, dots, bars, wave, halo, 이미지 또는 Lottie 기반 로더를 사용할 수 있습니다.

어디서든 호출 가능

공개된 native API를 통해 JavaScript, Swift, Kotlin 또는 기타 native plugin에서 로더를 실행하세요.

플랫폼 지원

플랫폼	지원	참고 사항
iOS에서는	예	네이티브
Android	예	네이티브
웹	아니요	Capacitor.getPlatform()으로 가드하세요

사용 시점

@capgo/capacitor-native-loader WebView가 작업 중이거나, 크기 조정, 탐색 중, 또는 네이티브 레이어 뒤에 숨겨져 있을 때도 매끄럽고 투명하며 네이티브한 상태를 유지해야 하는 로딩 상태를 위해 사용됩니다.

다음과 같은 경우에 사용하세요:

• 웹 콘텐츠 위의 투명한 전체 화면 로딩 레이어
• 콘텐츠를 가리지 않고 WebView 크기를 조절할 수 있는 Chrome 스타일 상단 프로그레스 바
• 앱 상단, 하단, 왼쪽, 오른쪽 가장자리의 로더
• 네이티브 콘텐츠가 화면 일부를 차지하는 동안 크기가 조정된 WebView 주변의 로더
• 무거운 웹 렌더링, 라우트 변경 또는 초기 구동 작업 중에도 유지되는 네이티브 폴백 로더
• JavaScript가 준비되기 전 다른 네이티브 플러그인이 트리거하는 공유 로더
• Lottie, 번들 이미지 또는 원격 에셋 기반 로딩 애니메이션

참고

웹 전용 라우트 애니메이션에는 다음을 사용하세요: @capgo/capacitor-transitions로딩 상태 자체를 네이티브로 구현해야 하거나, 로딩 중에 WebView 크기를 조정해야 하는 경우 Native Loader를 사용하세요.

데모 스타일

스타일	미리보기
Siri
Siri v2
Chrome 상단
Ring
Dots
Bars
Wave
Orbit
Pulse
Halo
Around
Lottie
Image

핵심 API

• show(options) 로더를 표시하고 해당 로더의 id.
• update(options) 오버레이를 제거하지 않고 기존 로더를 변경합니다.
• setProgress(options) determinate 로더 진행 상태를 업데이트합니다.
• hide(options) 로더 하나를 제거합니다.
• hideAll(options) 모든 로더를 제거합니다.
• setWebViewLayout(options) WebView/body의 크기를 조절하거나 인셋을 적용하여 네이티브 로더가 옆에 위치할 수 있게 합니다.
• resetWebViewLayout(options?) WebView/body의 원래 레이아웃으로 복구합니다.
• getState() 현재 표시 중인 로더 ID를 반환합니다.
• configure(options) 기본 스타일, 배치, 색상, 모션 및 동작을 설정합니다.

배치 모델

placement 네이티브 서피스가 나타날 위치를 제어합니다:

• fullscreen 앱 전체를 덮으며, 선택적으로 반투명하게 설정할 수 있습니다.
• center WebView 위에 컴팩트한 로더를 띄웁니다.
• top, bottom, left, 그리고 right 로더를 세이프 에어리어(safe-area)를 인식하는 가장자리에 고정합니다.
• chrome 전체 너비의 네이티브 상단 바 스타일을 사용하며 다음 항목과 잘 어울립니다: webView.mode: 'resize'.
• around 화면 프레임 주변에 로더 애니메이션을 렌더링합니다.
• custom 네이티브 플러그인 또는 스플릿 뷰(split-view) 워크플로우를 위한 명시적 프레임을 사용합니다.

사용하세요: interactionMode: 'passThrough' 사용자가 WebView와 계속 상호작용할 수 있는 경우, block 로딩 중에 탭을 방지해야 하는 경우, 또는 loaderOnly 로더 표면만 터치를 받아야 하는 경우.

@capgo/capacitor-native-loader에서 계속하기

사용 중인 경우 @capgo/capacitor-native-loader 네이티브 미디어 및 인터페이스 동작을 설계하려면, 이를 다음 항목과 연결하세요 시작하기 구현 세부 사항은, @capgo/capacitor-native-navigation 네이티브 Chrome 및 WebView 레이아웃은, @capgo/capacitor-transitions 웹 라우트 모션은, @capgo/capacitor-native-loader를 사용하여 튜토리얼을 참고하세요.