Pull To Refresh
사용자가 화면을 아래로 당겨 콘텐츠를 새로고침하는 컴포넌트입니다.
Installation
의존성 설치
아래 코드를 복사 후 붙여넣고 사용하세요
요구 사항
SEED의 최소 지원 Lynx Engine은 3.6입니다. Pull To Refresh는 @lynx-js/gesture-runtime의 NativeGesture를 사용하므로 앱의 기존 React 플러그인 설정에 enableNewGesture: true를 추가하세요.
enableNewGesture의 Since 2.16은 엔진 설정의 도입 기록입니다. SEED의 최소 지원 엔진을 뜻하지 않습니다. 설정 위치와 생략 조건은 Feature Flags에서 확인하세요.
Props
PullToRefreshRoot
Prop
Type
onPtrPullStart?((context: PullToRefreshContext) => void) | undefinedonPtrPullMove?((context: PullToRefreshContext) => void) | undefinedonPtrReady?(() => void) | undefinedonPtrRefresh?(() => Promise<void>) | undefineddisabled?boolean | undefinedonPtrRefresh에 새로고침 작업을 반환하는 비동기 함수를 전달하세요. threshold의 기본값은 88, displacementMultiplier의 기본값은 0.75입니다. 당긴 변위가 threshold를 넘은 상태에서 놓으면 새로고침을 시작합니다. Promise가 완료되거나 실패하면 콘텐츠가 원래 위치로 돌아옵니다.
PullToRefreshIndicator
고유 prop이 없습니다.
PullToRefreshContent
Prop
Type
Content는 세로 <scroll-view>입니다. 항목이 많아 가상화가 필요하면 Content 대신 PullToRefreshListContent를 사용하세요. Root에 높이를 지정하고 화면의 세로 스크롤은 Content나 ListContent 하나로 구성하세요. 중첩된 세로 스크롤 컨테이너는 당김 제스처와 경합할 수 있습니다.
PullToRefreshListContent
Prop
Type
ListContent는 세로 <list>입니다. children은 <list-item>으로 구성하세요. <list>의 나머지 속성은 그대로 전달됩니다.
custom-list-name의 기본값은"list-container"입니다. iOS의 기본 list 구현은 당김 제스처가 native 스크롤을 막지 못해 당기는 중 list가 함께 스크롤될 수 있습니다. 다른 값으로 바꾸면 iOS에서 이 문제가 다시 생길 수 있습니다.- Content와 같이
bounces의 기본값은false이며 iOS 아래쪽 경계의 bounce도 꺼집니다. - 최상단 판정은 list의
scroll이벤트가 보내는scrollTop을 따르고scrolltoupper이벤트로 보완합니다. list의scroll이벤트는 간격을 두고 보내져 최상단에 닿은 마지막 값이 빠질 수 있습니다. 두 이벤트가 모두 늦게 오면 빠르게 최상단까지 스크롤한 직후의 당김이 시작되지 않을 수 있습니다.scroll-event-throttle을 낮춰도 iOS list-container에서는 적용이 보장되지 않습니다.
Examples
Pull To Refresh in Tabs
가로로 넘길 수 있는 Tabs Carousel의 Tab 1에만 Pull To Refresh를 배치합니다. Tab 2에서는 새로고침하지 않습니다.
List
PullToRefreshListContent로 <list>를 당겨서 새로고침합니다.
Disabled
disabled prop으로 Pull To Refresh를 비활성화할 수 있습니다. 당기는 도중 비활성화하면 당김이 취소됩니다. 이미 시작한 새로고침은 반환한 Promise가 끝날 때까지 유지됩니다.
Prevent Pull
Root 안의 특정 영역에서 당김을 막으려면 usePullToRefreshPreventPull()이 반환한 props를 해당 <view>에 전달하세요. 같은 요소에 main-thread:bindtouchstart를 함께 지정하지 마세요.
웹 버전과의 차이
- Lynx는 Root가 배치와 clipping을 맡고 Content(
<scroll-view>)나 ListContent(<list>)가 세로 스크롤을 담당합니다.asChild는 지원하지 않습니다. - Content 내부의 중첩 스크롤 영역을 자동으로 탐지하지 않습니다.
- 스크롤하다 최상단에 도달한 경우 손을 뗀 뒤 다시 당겨야 새로고침이 시작됩니다.
Last updated on