VirtualList · Tinyrack Design System

큰 가변 크기 선형 목록을 lazy하게 렌더링하면서 데이터와 항목 크기가 바뀌어도 보이는 항목의 위치를 안정적으로 유지해요.

핵심 속성

속성	설명
식별	`itemKey`는 고유하고 안정적인 key를 반환해야 해요. key는 항목 상태를 보존하고 삽입, 삭제, 재정렬, 크기 변경에서 anchor를 정해요.
측정	`estimatedItemExtent`가 아직 측정하지 않은 항목의 초기값을 제공해요. 자연 layout이 각 예상값을 교체하므로 측정이 끝나기 전 전체 extent와 스크롤바 thumb는 근사값이에요.
끝 따라가기	`follow`는 읽는 사람이 해당 논리적 끝에 있을 때만 고정돼요. 끝에서 벗어나면 보이는 anchor를 보존하고, 다시 끝에 도달하면 따라가기를 재개해요. disclosure 크기 변경이 한 번만 따라가기를 우선해야 한다면 변경 전에 `holdVisibleAnchorForNextLayout()`을 호출하세요.
로딩	leading·trailing edge request는 `requestKey`마다 소비자에게 한 번 알리고 측정되는 상태 슬롯을 렌더링할 수 있어요. fetch, 오류, 재시도 attempt, cursor, 완료 상태는 소비자가 소유해요.
복원	opaque `initialSnapshot`을 전달하거나 `pageStorageId`를 설정하세요. 호환되는 snapshot은 `initialPosition`보다 우선하고 key가 없으면 초기 위치로 돌아가요.
접근	보이는 범위와 cache 범위만 widget tree에 존재해요. 화면 밖 로컬 상태, 전체 문서 검색, 인쇄, 선택, 보조 기술의 virtual cursor 접근은 소비자가 다뤄야 해요. 전체 문서가 계속 필요하면 비가상 렌더링을 사용하세요.

목록은 하나의 제한된 viewport를 소유하고 데이터를 정방향으로 유지해요. 살아남은 보이는 항목 wrapper 하나를 viewport 기준 같은 좌표에 보존해요. 변경 지점이 보이는 범위를 가로지르면 모든 보이는 항목을 동시에 고정할 수는 없어요.

설치

패키지를 추가한 뒤 공개 라이브러리를 가져오세요.

flutter pub add tinyrack_ui

import 'package:tinyrack_ui/tinyrack_ui.dart';

플레이그라운드

Flutter 미리보기를 불러오는 중이에요

사용법

import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';

TRVirtualList<Message, String>(
  items: messages,
  itemKey: (message) => message.id,
  estimatedItemExtent: (message, index) => TRMeasurements.measureSm,
  initialPosition: const TRVirtualListInitialPosition.trailing(),
  follow: TRVirtualListFollow.trailing,
  itemBuilder: (context, message, index) => MessageRow(message),
)

예시

읽는 위치를 움직이지 않고 이전 행 로드 고유 링크

cursor나 재시도 attempt마다 requestKey를 바꾸세요. 소비자가 fetch와 상태 슬롯을 소유하고 목록은 보이는 anchor를 보존해요.

Flutter 미리보기를 불러오는 중이에요

API

TRVirtualList 속성

Prop	타입 / 기본값	용도
`items / itemKey / itemBuilder`	`List<T> / K Function(T) / Widget Function(...) · required`	순서가 있는 데이터, 안정적인 식별값, lazy row builder를 제공해요.
`estimatedItemExtent`	`double Function(T, int) · required`	아직 측정하지 않은 항목의 주축 extent를 예상해요.
`axis / initialPosition / follow`	`Axis / TRVirtualListInitialPosition<K> / TRVirtualListFollow`	세로·가로 layout, fallback 시작 위치, 선택적인 논리적 끝 따라가기를 정해요.
`leadingEdgeRequest / trailingEdgeRequest`	`TRVirtualListEdgeRequest? · null`	각 끝에 가까워졌음을 알리고 선택적으로 상태 슬롯을 렌더링해요.
`initialSnapshot / pageStorageId`	`TRVirtualListSnapshot<K>? / String?`	stable-key anchor를 직접 또는 PageStorage를 통해 복원해요.
`controller`	`TRVirtualListController<K>? · null`	index, key, edge로 이동하고 snapshot을 캡처하거나 한 번의 layout anchor를 고정해요.