ページネーション

Misskey はカーソルベースのページネーションを採用しています。リストを返す API はページネーションパラメータを直接受け取り、List<T> を返します。ラッパー型は存在しません。呼び出し側でパラメータを渡し、返却されたリストの件数を見て次ページの有無を判断します。

ページネーションパラメータ

パラメータ	型	説明
`sinceId`	String	このノート/オブジェクト ID より新しい結果を返す
`untilId`	String	このノート/オブジェクト ID より古い結果を返す
`sinceDate`	int	このUnixタイムスタンプ（ms）より新しい結果を返す
`untilDate`	int	このUnixタイムスタンプ（ms）より古い結果を返す
`limit`	int	返却する最大件数（通常 1〜100）
`offset`	int	指定件数をスキップする（オフセット方式の API のみ）

すべての API がすべてのパラメータに対応しているわけではありません。各エンドポイントの API リファレンスを参照してください。

カーソルベースのページネーション（ID による）

古いページを取得するには untilId、新しいページを取得するには sinceId を使用します。

古いページの取得

// 最初のページ — 最新の通知
List<MisskeyNotification> page = await client.notifications.list(limit: 20);

// 次のページ — 前ページの最後のアイテムより古いもの
while (page.isNotEmpty) {
  final oldestId = page.last.id;
  final next = await client.notifications.list(
    limit: 20,
    untilId: oldestId,
  );
  if (next.isEmpty) break;
  page = next;
}

新しいページの取得

// 最後に取得した最新 ID を保持する
String? latestId;

Future<List<MisskeyNote>> pollNewNotes() async {
  final notes = await client.notes.timelineHome(
    limit: 20,
    sinceId: latestId,
  );
  if (notes.isNotEmpty) {
    latestId = notes.first.id;
  }
  return notes;
}

タイムスタンプベースのページネーション

ID ではなく時刻でページングしたい場合は sinceDate / untilDate を使用します。

final now = DateTime.now().millisecondsSinceEpoch;
final oneDayAgo = now - const Duration(days: 1).inMilliseconds;

final notes = await client.notes.timelineLocal(
  limit: 30,
  sinceDate: oneDayAgo,
  untilDate: now,
);

オフセットベースのページネーション

一部の API はカーソルパラメータの代わりに offset に対応しています。カーソルによるナビゲーションが使えない場合に利用します。

const pageSize = 50;
var offset = 0;

while (true) {
  final users = await client.users.list(
    limit: pageSize,
    offset: offset,
  );
  // users を処理する...
  if (users.length < pageSize) break; // 最終ページ
  offset += users.length;
}

最終ページの判定

hasNext のようなフラグはありません。返却件数が limit を下回った場合が最終ページです。

const limit = 20;
final page = await client.blocking.list(limit: limit);
final isLastPage = page.length < limit;

全ページを取得する

Future<List<MisskeyNote>> fetchAllFavorites() async {
  const limit = 100;
  final all = <MisskeyNote>[];
  String? untilId;

  while (true) {
    final page = await client.account.favorites(
      limit: limit,
      untilId: untilId,
    );
    all.addAll(page);
    if (page.length < limit) break;
    untilId = page.last.id;
  }

  return all;
}

自動ページネーションのヘルパー

一部の API には、上記の untilId ループを代わりに実行し、遅延評価される Stream を返すヘルパーがあります。現在はドライブの一覧取得ヘルパーが該当します。

client.drive.files.listAll() — 1つのフォルダ内のファイル
client.drive.folders.listAll() — 1つの親フォルダ内のフォルダ
client.drive.streamAll() — すべてのフォルダにわたるファイル

await for (final file in client.drive.files.listAll(pageSize: 100)) {
  print(file.name);
}

リクエストはストリームを listen した時点で開始され、購読をキャンセルすると以降のリクエストは停止します。結果は常に ID の新しい順です。途中で打ち切るには maxItems を使用します。詳細はドライブヘルパーを参照してください。