feat: implement cursor-based pagination across various components and APIs

2026-05-14 20:08:38 +08:00 · 2026-05-10 00:36:41 +08:00
parent 56b48b28a1
commit f89292e451
12 changed files with 275 additions and 148 deletions
--- a/web/src/api/vfs.ts
+++ b/web/src/api/vfs.ts
@@ -13,10 +13,14 @@ export interface DirListing {
  path: string;
  entries: VfsEntry[];
  pagination?: {
-    total: number;
-    page: number;
+    mode?: 'paged' | 'cursor';
    page_size: number;
-    pages: number;
+    total?: number;
+    page?: number;
+    pages?: number;
+    cursor?: string | null;
+    next_cursor?: string | null;
+    has_next?: boolean;
  };
 }

@@ -47,7 +51,7 @@ export interface SearchResponse {
 }

 export const vfsApi = {
-  list: (path: string, page: number = 1, pageSize: number = 50, sortBy: string = 'name', sortOrder: string = 'asc') => {
+  list: (path: string, page: number = 1, pageSize: number = 50, sortBy: string = 'name', sortOrder: string = 'asc', cursor?: string | null) => {
    const cleaned = path.replace(/\\/g, '/');
    const trimmed = cleaned === '/' ? '' : cleaned.replace(/^\/+/, '');
    const params = new URLSearchParams({
@@ -56,6 +60,7 @@ export const vfsApi = {
      sort_by: sortBy,
      sort_order: sortOrder
    });
+    if (cursor) params.set('cursor', cursor);
    return request<DirListing>(`/fs/${encodeURI(trimmed)}?${params}`);
  },
  readFile: async (path: string) => {
--- a/web/src/pages/FileExplorerPage/FileExplorerPage.tsx
+++ b/web/src/pages/FileExplorerPage/FileExplorerPage.tsx
@@ -1,6 +1,6 @@
 import { memo, useCallback, useEffect, useRef, useState } from 'react';
 import { useParams } from 'react-router';
-import { theme, Pagination } from 'antd';
+import { Button, Space, theme, Pagination } from 'antd';
 import { useFileExplorer } from './hooks/useFileExplorer';
 import { useFileSelection } from './hooks/useFileSelection';
 import { useFileActions } from './hooks/useFileActions.tsx';
@@ -43,7 +43,7 @@ const FileExplorerPage = memo(function FileExplorerPage() {
  const skeletonTimerRef = useRef<number | null>(null);

  // --- Hooks ---
-  const { path, entries, loading, pagination, processorTypes, sortBy, sortOrder, load, navigateTo, goUp, handlePaginationChange, refresh, handleSortChange } = useFileExplorer(navKey);
+  const { path, entries, loading, pagination, processorTypes, sortBy, sortOrder, load, navigateTo, goUp, handlePaginationChange, refresh, handleSortChange, goCursorNext, goCursorPrev } = useFileExplorer(navKey);
  const { selectedEntries, handleSelect, handleSelectRange, clearSelection, setSelectedEntries } = useFileSelection();
  const { openFileWithDefaultApp, confirmOpenWithApp } = useAppWindows();
  const { ctxMenu, blankCtxMenu, openContextMenu, openBlankContextMenu, openContextMenuAt, closeContextMenus } = useContextMenu();
@@ -221,8 +221,10 @@ const FileExplorerPage = memo(function FileExplorerPage() {
    }
    return joined.startsWith('/') ? joined : `/${joined}`;
  }, [entryBasePath]);
-  const showFsPagination = !isSearching && pagination.total > 0;
+  const showFsPagination = !isSearching && pagination.mode === 'paged' && pagination.total > 0;
+  const showCursorPagination = !isSearching && pagination.mode === 'cursor' && (pagination.cursorHistory.length > 0 || pagination.hasNext);
  const shouldReserveBottomBar = showSearchPagination || showFsPagination;
+  const shouldReserveAnyBottomBar = shouldReserveBottomBar || showCursorPagination;

  const handleDragEnter = (e: React.DragEvent) => {
    e.preventDefault();
@@ -298,6 +300,7 @@ const FileExplorerPage = memo(function FileExplorerPage() {
        viewMode={viewMode}
        sortBy={sortBy}
        sortOrder={sortOrder}
+        paginationMode={pagination.mode}
        isMobile={isMobile}
        onGoUp={goUp}
        onNavigate={navigateTo}
@@ -325,7 +328,7 @@ const FileExplorerPage = memo(function FileExplorerPage() {
        onChange={handleDirectoryInputChange}
      />

-      <div style={{ flex: 1, overflow: 'auto', minHeight: 0, paddingBottom: shouldReserveBottomBar ? '80px' : '0' }} onContextMenu={isMobile ? undefined : openBlankContextMenu}>
+      <div style={{ flex: 1, overflow: 'auto', minHeight: 0, paddingBottom: shouldReserveAnyBottomBar ? '80px' : '0' }} onContextMenu={isMobile ? undefined : openBlankContextMenu}>
        {isSearching ? (
          <SearchResultsView
            viewMode={viewMode}
@@ -380,6 +383,19 @@ const FileExplorerPage = memo(function FileExplorerPage() {
        </div>
      )}

+      {showCursorPagination && (
+        <div style={{ position: 'absolute', bottom: 0, left: 0, right: 0, padding: '12px 16px', background: token.colorBgContainer, borderTop: `1px solid ${token.colorBorderSecondary}`, textAlign: 'center', zIndex: 10 }}>
+          <Space>
+            <Button size="small" onClick={goCursorPrev} disabled={pagination.cursorHistory.length === 0 || loading}>
+              上一页
+            </Button>
+            <Button size="small" type="primary" onClick={goCursorNext} disabled={!pagination.hasNext || loading}>
+              下一页
+            </Button>
+          </Space>
+        </div>
+      )}
+
      {showSearchPagination && (
        <div style={{ position: 'absolute', bottom: 0, left: 0, right: 0, padding: '12px 16px', background: token.colorBgContainer, borderTop: `1px solid ${token.colorBorderSecondary}`, textAlign: 'center', zIndex: 10 }}>
          <Pagination
--- a/web/src/pages/FileExplorerPage/components/Header.tsx
+++ b/web/src/pages/FileExplorerPage/components/Header.tsx
@@ -12,6 +12,7 @@ interface HeaderProps {
  viewMode: ViewMode;
  sortBy: string;
  sortOrder: string;
+  paginationMode?: 'paged' | 'cursor';
  isMobile?: boolean;
  onGoUp: () => void;
  onNavigate: (path: string) => void;
@@ -30,6 +31,7 @@ export const Header: React.FC<HeaderProps> = ({
  viewMode,
  sortBy,
  sortOrder,
+  paginationMode = 'paged',
  isMobile = false,
  onGoUp,
  onNavigate,
@@ -82,6 +84,7 @@ export const Header: React.FC<HeaderProps> = ({
    setEditingPath(false);
    setPathInputValue('');
  };
+  const sortDisabled = paginationMode === 'cursor';

  const renderBreadcrumb = () => {
    if (editingPath) {
@@ -154,6 +157,7 @@ export const Header: React.FC<HeaderProps> = ({
    {
      key: 'sort',
      label: t('Sort By') + `: ${t(sortBy === 'mtime' ? 'Modified Time' : sortBy === 'size' ? 'Size' : 'Name')}`,
+      disabled: sortDisabled,
      children: [
        { key: 'sort-name', label: t('Name'), onClick: () => onSortChange('name', sortOrder) },
        { key: 'sort-size', label: t('Size'), onClick: () => onSortChange('size', sortOrder) },
@@ -164,6 +168,7 @@ export const Header: React.FC<HeaderProps> = ({
      key: 'sort-order',
      label: sortOrder === 'asc' ? t('Ascending') : t('Descending'),
      icon: sortOrder === 'asc' ? <ArrowUpOutlined /> : <ArrowDownOutlined />,
+      disabled: sortDisabled,
      onClick: () => onSortChange(sortBy, sortOrder === 'asc' ? 'desc' : 'asc'),
    },
  ];
@@ -230,6 +235,7 @@ export const Header: React.FC<HeaderProps> = ({
          <Select
            size="small"
            value={sortBy}
+            disabled={sortDisabled}
            onChange={(val) => onSortChange(val, sortOrder)}
            style={{ width: 112 }}
            options={[
@@ -240,6 +246,7 @@ export const Header: React.FC<HeaderProps> = ({
          />
          <Button
            size="small"
+            disabled={sortDisabled}
            icon={sortOrder === 'asc' ? <ArrowUpOutlined /> : <ArrowDownOutlined />}
            onClick={() => onSortChange(sortBy, sortOrder === 'asc' ? 'desc' : 'asc')}
          />
--- a/web/src/pages/FileExplorerPage/hooks/useFileExplorer.ts
+++ b/web/src/pages/FileExplorerPage/hooks/useFileExplorer.ts
@@ -7,10 +7,14 @@ type ExplorerSnapshot = {
  path: string;
  entries: VfsEntry[];
  pagination?: {
-    total: number;
-    page: number;
+    mode?: 'paged' | 'cursor';
    page_size: number;
-    pages: number;
+    total?: number;
+    page?: number;
+    pages?: number;
+    cursor?: string | null;
+    next_cursor?: string | null;
+    has_next?: boolean;
  };
  sortBy: string;
  sortOrder: string;
@@ -30,6 +34,11 @@ export function useFileExplorer(navKey: string) {
    current: 1,
    pageSize: 50,
    total: 0,
+    mode: 'paged' as 'paged' | 'cursor',
+    cursor: null as string | null,
+    nextCursor: null as string | null,
+    cursorHistory: [] as (string | null)[],
+    hasNext: false,
    showSizeChanger: true,
    showQuickJumper: true,
    showTotal: (total: number, range: [number, number]) => `${total} ${'items'} ${range[0]}-${range[1]}`,
@@ -38,23 +47,29 @@ export function useFileExplorer(navKey: string) {
  const [sortBy, setSortBy] = useState('name');
  const [sortOrder, setSortOrder] = useState('asc');

-  const load = useCallback(async (p: string, page: number = 1, pageSize: number = 50, sb = sortBy, so = sortOrder) => {
+  const load = useCallback(async (p: string, page: number = 1, pageSize: number = 50, sb = sortBy, so = sortOrder, cursor?: string | null, cursorHistory: (string | null)[] = []) => {
    const canonical = p === '' ? '/' : (p.startsWith('/') ? p : '/' + p);
    setLoading(true);
    try {
      // Load entries and processor types concurrently
      const [res, processors] = await Promise.all([
-        vfsApi.list(canonical === '/' ? '' : canonical, page, pageSize, sb, so),
+        vfsApi.list(canonical === '/' ? '' : canonical, page, pageSize, sb, so, cursor),
        processorsApi.list()
      ]);
      setEntries(res.entries);
      const resolvedPath = res.path || canonical;
      setPath(resolvedPath);
+      const pageMode = res.pagination?.mode || 'paged';
      setPagination(prev => ({
        ...prev,
-        current: res.pagination!.page,
-        pageSize: res.pagination!.page_size,
-        total: res.pagination!.total
+        mode: pageMode,
+        current: res.pagination?.page || page,
+        pageSize: res.pagination?.page_size || pageSize,
+        total: res.pagination?.total || 0,
+        cursor: res.pagination?.cursor || null,
+        nextCursor: res.pagination?.next_cursor || null,
+        hasNext: Boolean(res.pagination?.has_next),
+        cursorHistory: pageMode === 'cursor' ? cursorHistory : [],
      }));
      setProcessorTypes(processors);
      if (typeof window !== 'undefined') {
@@ -94,8 +109,31 @@ export function useFileExplorer(navKey: string) {
    load(path, page, pageSize, sortBy, sortOrder);
  };

+  const goCursorNext = () => {
+    if (!pagination.nextCursor) return;
+    load(path, 1, pagination.pageSize, sortBy, sortOrder, pagination.nextCursor, [
+      ...pagination.cursorHistory,
+      pagination.cursor,
+    ]);
+  };
+
+  const goCursorPrev = () => {
+    if (pagination.cursorHistory.length === 0) return;
+    const nextHistory = pagination.cursorHistory.slice(0, -1);
+    const prevCursor = pagination.cursorHistory[pagination.cursorHistory.length - 1];
+    load(path, 1, pagination.pageSize, sortBy, sortOrder, prevCursor, nextHistory);
+  };
+
  const refresh = () => {
-    load(path, pagination.current, pagination.pageSize, sortBy, sortOrder);
+    load(
+      path,
+      pagination.current,
+      pagination.pageSize,
+      sortBy,
+      sortOrder,
+      pagination.mode === 'cursor' ? pagination.cursor : null,
+      pagination.mode === 'cursor' ? pagination.cursorHistory : [],
+    );
  }

  const handleSortChange = (sb: string, so: string) => {
@@ -117,6 +155,8 @@ export function useFileExplorer(navKey: string) {
    goUp,
    handlePaginationChange,
    refresh,
-    handleSortChange
+    handleSortChange,
+    goCursorNext,
+    goCursorPrev,
  };
 }