VirtualList · Tinyrack Design System

大きな可変サイズの線形リストを遅延描画し、データや項目サイズが変わっても表示中の項目位置を安定して保ちます。

主なプロパティ

プロパティ	説明
識別	`itemKey` は一意で安定した key を返す必要があります。key は項目の状態を保ち、挿入、削除、並べ替え、サイズ変更時のアンカーを定義します。
計測	`estimatedItemExtent` は未計測項目の初期値です。自然な layout が各推定値を置き換えるため、計測が終わるまで全体の extent とスクロールバー thumb は近似値です。
端の追従	`follow` は読み手がその論理端にいる間だけ固定されます。端から離れると表示アンカーを保ち、端へ戻ると追従を再開します。開閉によるサイズ変更で 1 回だけ追従よりアンカーを優先する場合は、変更前に `holdVisibleAnchorForNextLayout()` を呼び出してください。
読み込み	leading・trailing edge request は `requestKey` ごとに 1 回 consumer へ通知し、計測対象の状態 slot を描画できます。fetch、エラー、再試行 attempt、cursor、完了状態は consumer が管理します。
復元	opaque な `initialSnapshot` を渡すか `pageStorageId` を設定してください。互換性のある snapshot は `initialPosition` より優先され、key がない場合は初期位置へフォールバックします。
アクセス	表示範囲と cache 範囲だけが widget tree に存在します。画面外のローカル状態、文書全体の検索、印刷、選択、支援技術の virtual cursor アクセスは consumer 側で扱います。文書全体を常に利用できる必要がある場合は、非仮想描画を使用してください。

リストは 1 つの領域内 viewport を所有し、データを順方向に保ちます。存続する表示項目の wrapper 1 つを 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 を変更してください。consumer が fetch と状態 slot を管理し、リストは表示アンカーを保ちます。