feat(plugin-list): 列表工具栏增加手动刷新按钮 (#2634) (#2645)

* feat(plugin-list): 列表工具栏增加手动刷新按钮 (#2634)

列表(ListView)工具栏此前没有主动刷新入口,后端数据变更后只能靠浏览器
整页 reload,导致筛选/排序/分页/滚动等页面状态全部丢失。

新增「刷新」按钮:点击后仅重新拉取当前视图数据(bump refreshKey 触发
re-fetch),筛选/排序/分页/搜索均为组件内 state,刷新时自动保留。按钮
在移动端与桌面端均常驻,加载时图标旋转。

开关采用 spec 规范的 userActions.refresh(@objectstack/spec ListView),
并向后兼容 legacy showRefresh 标志,默认可见(opt-out),与其它工具栏
开关(search/sort/filter/density)行为一致。

注:数据变更后的自动刷新(onMutation 订阅)与移动端下拉刷新此前已具备,
本次补齐的是缺失的桌面端手动刷新入口。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C7Z2cbcb14wb99upTD6LNw

* refactor(plugin-list): gate refresh button purely on spec userActions.refresh

CI drift guard (list-view-spec-parity) flags new objectui-only ListView
fields and asks to promote them into @objectstack/spec instead. `refresh`
is already promoted (userActions.refresh), so drop the just-added legacy
`showRefresh` zod flag and gate the toolbar button solely on
`userActions.refresh` (read defensively; visible by default, opt-out via
`userActions.refresh: false`).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C7Z2cbcb14wb99upTD6LNw

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

packages/i18n/src/locales/en.ts

@@ -344,6 +344,7 @@ const en = {
       },
     },
     showAll: 'Show all',
+    refresh: 'Refresh',
     pullToRefresh: 'Pull to refresh',
     refreshing: 'Refreshing…',
     share: 'Share',

packages/i18n/src/locales/zh.ts

@@ -421,6 +421,7 @@ const zh = {
       },
     },
     showAll: '显示全部',
+    refresh: '刷新',
     pullToRefresh: '下拉刷新',
     refreshing: '刷新中…',
     share: '分享',

packages/plugin-list/src/ListView.tsx

@@ -245,6 +245,7 @@ const LIST_DEFAULT_TRANSLATIONS: Record<string, string> = {
   'list.hideFields': 'Hide fields',
   'list.showAll': 'Show all',
   'list.pullToRefresh': 'Pull to refresh',
+  'list.refresh': 'Refresh',
   'list.refreshing': 'Refreshing…',
   'list.dataLimitReached': 'Showing first {{limit}} records. More data may be available.',
   'list.addRecord': 'Add record',
@@ -390,10 +391,15 @@ export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
   const toolbarFlags = React.useMemo(() => {
     const ua = schema.userActions;
     const addRecordEnabled = schema.addRecord?.enabled === true && ua?.addRecordForm !== false;
+    // `refresh` is spec-canonical (`userActions.refresh`, @objectstack/spec). The
+    // installed spec type may predate the field, so read it defensively. Visible by
+    // default (opt-out via `userActions.refresh: false`), like the other toggles.
+    const uaRefresh = (ua as { refresh?: boolean } | undefined)?.refresh;
     return {
       showSearch: ua?.search !== undefined ? ua.search : schema.showSearch !== false,
       showSort: ua?.sort !== undefined ? ua.sort : schema.showSort !== false,
       showFilters: ua?.filter !== undefined ? ua.filter : schema.showFilters !== false,
+      showRefresh: uaRefresh !== undefined ? uaRefresh : true,
       showDensity: ua?.rowHeight !== undefined ? ua.rowHeight : schema.showDensity !== false,
       showHideFields: schema.showHideFields === true,
       showGroup: schema.showGroup !== false,
@@ -2147,6 +2153,25 @@ export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
             <div className="h-5 w-px bg-border/50 mx-1 shrink-0" />
           )}
 
+          {/* Refresh — re-fetch the current view from the backend without a full page
+              reload. Filters / sort / pagination / search all live in component state,
+              so bumping refreshKey re-queries while preserving the view. Always visible
+              (mobile + desktop) since reloading data is a primary list action. */}
+          {toolbarFlags.showRefresh && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-7 w-7 p-0 text-muted-foreground hover:text-primary transition-colors duration-150"
+              onClick={() => setRefreshKey(k => k + 1)}
+              disabled={loading}
+              title={t('list.refresh')}
+              aria-label={t('list.refresh')}
+              data-testid="refresh-button"
+            >
+              <RotateCw className={cn('h-3.5 w-3.5', loading && 'animate-spin')} />
+            </Button>
+          )}
+
           {/* Export */}
           {resolvedExportOptions && exportPermitted && (
             <Popover open={showExport} onOpenChange={setShowExport}>

packages/plugin-list/src/__tests__/ListView.refreshButton.test.tsx

@@ -0,0 +1,88 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * #2634 — the ListView toolbar must expose a manual "Refresh" button that
+ * re-fetches the current view from the backend without a full page reload.
+ * Clicking it re-queries the DataSource while the filter/sort/search state
+ * (held in component state) is preserved.
+ *
+ * The toggle is spec-canonical (`userActions.refresh`, @objectstack/spec) and
+ * defaults to visible (opt-out via `userActions.refresh: false`).
+ */
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { render, waitFor, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+import { ListView } from '../ListView';
+import type { ListViewSchema } from '@object-ui/types';
+import { SchemaRendererProvider } from '@object-ui/react';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'localStorage', {
+    value: (() => {
+      let store: Record<string, string> = {};
+      return {
+        getItem: (k: string) => store[k] ?? null,
+        setItem: (k: string, v: string) => { store[k] = v; },
+        clear: () => { store = {}; },
+        removeItem: (k: string) => { delete store[k]; },
+      };
+    })(),
+    configurable: true,
+  });
+});
+
+function makeDataSource() {
+  const find = vi.fn().mockResolvedValue({ data: [], total: 0 });
+  return {
+    find,
+    findOne: vi.fn(),
+    create: vi.fn(),
+    update: vi.fn(),
+    delete: vi.fn(),
+  } as any;
+}
+
+function renderList(schema: Partial<ListViewSchema>, ds: any) {
+  return render(
+    <SchemaRendererProvider dataSource={ds}>
+      <ListView
+        schema={{ type: 'list-view', objectName: 'proj', fields: ['name'], ...schema } as any}
+        dataSource={ds}
+      />
+    </SchemaRendererProvider>,
+  );
+}
+
+describe('ListView — manual refresh button (#2634)', () => {
+  it('renders a refresh button by default and re-fetches on click', async () => {
+    const ds = makeDataSource();
+    renderList({}, ds);
+
+    await waitFor(() => expect(ds.find).toHaveBeenCalled());
+    const callsBefore = ds.find.mock.calls.length;
+
+    const btn = screen.getByTestId('refresh-button');
+    expect(btn).toBeInTheDocument();
+
+    fireEvent.click(btn);
+
+    await waitFor(() => {
+      expect(ds.find.mock.calls.length).toBeGreaterThan(callsBefore);
+    });
+  });
+
+  it('hides the refresh button when userActions.refresh is false', async () => {
+    const ds = makeDataSource();
+    renderList({ userActions: { refresh: false } as any }, ds);
+
+    await waitFor(() => expect(ds.find).toHaveBeenCalled());
+    expect(screen.queryByTestId('refresh-button')).not.toBeInTheDocument();
+  });
+});