@nokecy/qc-ui-components 2.0.0-beta.0 → 2.0.0-beta.2

package/dist/esm/ag-grid-plus/ag-gridPlus.js

@@ -1,6 +1,5 @@
-var _excluded = ["style", "loading", "params", "request", "dataSource", "treeKeyName", "treeParentName", "rowData", "gridRef", "headerTitle", "toolBarRender", "search", "hideTool", "onGridReady", "gridKey", "children", "defaultSearchExpand", "overlayNoRowsTemplateText", "queryDefaultRows", "onSelectedRowsChange", "onQueryValuesChange", "emptyState", "accessible", "enableClickSelection", "rowSelection", "useNativeTreeFilter", "entityType", "valueEnumContrast", "dateQueryPrecision"];
+var _excluded = ["style", "loading", "params", "request", "dataSource", "treeKeyName", "treeParentName", "rowData", "gridRef", "headerTitle", "toolBarRender", "search", "hideTool", "onGridReady", "gridKey", "children", "defaultSearchExpand", "overlayNoRowsTemplateText", "queryDefaultRows", "onSelectedRowsChange", "onQueryValuesChange", "autoRememberColumns", "emptyState", "accessible", "enableClickSelection", "rowSelection", "crossPageSelection", "onCrossPageSelectionChange", "defaultValueFormat", "useNativeTreeFilter", "entityType", "valueEnumContrast", "dateQueryPrecision", "headerFilter", "showQuickJumper", "showSizeChanger"];
 function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
-function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
 function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
 function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
@@ -16,6 +15,7 @@ function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o =
 function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
 function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 import { ModuleRegistry } from 'ag-grid-community';
@@ -23,17 +23,26 @@ import { AgGridReact } from 'ag-grid-react';
 import { Spin, Pagination, Card, Tag, Popover, Badge, Button, theme } from 'antd';
 import React, { useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { AllEnterpriseModule } from "ag-grid-enterprise";
+import { installAgGridLicenseNotice } from "./utils/agGridLicenseNotice";
 
-// AG-Grid v33+ 需要显式注册模块
+// AG-Grid v33+ 需要显式注册模块；组件库不内置 license key，未授权时的试用提示统一收敛
+installAgGridLicenseNotice();
 ModuleRegistry.registerModules([AllEnterpriseModule]);
 
 // 导入 AG-Grid v33 主题
 import { useAgGridTheme } from "./theme";
+import { resolveGridDensity } from "./density";
+import { deriveRowColors } from "./rowColors";
+import { createListKeyHandler } from "./utils/listKeyboard";
+import { createCrossPageSelection } from "./utils/crossPageSelection";
+import { withDefaultValueFormat } from "./utils/valueFormat";
 import { useTypeInferenceRow } from "./hooks/useTypeInferenceRow";
 import "./index.less";
 import FormRender from "./queryForm/index";
 import ToolBar from "./toolBar/index";
 import SettingItem from "./settingItem/index";
+import { useAutoColumnMemory } from "./setting/autoColumnMemory";
+import { needsDirectRequest } from "./utils/queryDispatch";
 import { RedoOutlined, FilterOutlined } from '@ant-design/icons';
 import { convertFilterModel, dateTimeValueFormatter, dateValueFormatter, flatten, toTree } from "./utils";
 import { mergeInferredColumnType, processEllipsisColumn, processEnumColumn, renderDefaultCell } from "./utils/columnProcessors";
@@ -45,6 +54,8 @@ import { useRowId } from "./hooks/useRowId";
 import _, { isArray } from 'lodash';
 import CustomGroupCellRenderer from "./_utils/customGroupCellRenderer";
 import NoRowsOverlay from "./shared/NoRowsOverlay";
+import SkeletonOverlay from "./shared/SkeletonOverlay";
+import { clampPage, formatPaginationTotal, mergeDefaultColDef, resolveInitialPageSize, sliceRowsByPage } from "./utils/pagination";
 import { DEFAULT_PAGE_SIZE_OPTIONS } from "./utils/constants";
 import { hasEffectiveFilter, resolveEmptyBranch, resolveEmptyText, resolveNoRowsOverlay } from "./utils/emptyState";
 import processColumnGroups from "./_utils/processColumnGroups";
@@ -67,6 +78,7 @@ import { getEntityExtensionColumns } from "./utils/entityExtensionColumns";
 import { message } from 'antd';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
 var getSort = function getSort(columnState) {
   return columnState ? "".concat(columnState.colId, " ").concat(columnState.sort) : "";
 };
@@ -81,8 +93,7 @@ function useDeepCompareStable(value) {
   return ref.current;
 }
 function AgGridPlus(props) {
-  var _ref, _rest$cellSelection;
-  var gridTheme = useAgGridTheme();
+  var _currentSchemes, _ref, _currentQueryScheme$q, _rest$cellSelection;
   var _theme$useToken = theme.useToken(),
     token = _theme$useToken.token; // 高级筛选入口跟随主题及客户主色。@author nokecy
   var style = props.style,
@@ -106,17 +117,27 @@ function AgGridPlus(props) {
     queryDefaultRows = props.queryDefaultRows,
     onSelectedRowsChange = props.onSelectedRowsChange,
     onQueryValuesChange = props.onQueryValuesChange,
+    _props$autoRememberCo = props.autoRememberColumns,
+    autoRememberColumns = _props$autoRememberCo === void 0 ? true : _props$autoRememberCo,
     emptyState = props.emptyState,
     _props$accessible = props.accessible,
     accessible = _props$accessible === void 0 ? true : _props$accessible,
     enableClickSelection = props.enableClickSelection,
     propsRowSelection = props.rowSelection,
+    _props$crossPageSelec = props.crossPageSelection,
+    crossPageSelection = _props$crossPageSelec === void 0 ? false : _props$crossPageSelec,
+    onCrossPageSelectionChange = props.onCrossPageSelectionChange,
+    _props$defaultValueFo = props.defaultValueFormat,
+    defaultValueFormat = _props$defaultValueFo === void 0 ? true : _props$defaultValueFo,
     _props$useNativeTreeF = props.useNativeTreeFilter,
     useNativeTreeFilter = _props$useNativeTreeF === void 0 ? false : _props$useNativeTreeF,
     entityType = props.entityType,
     _props$valueEnumContr = props.valueEnumContrast,
     valueEnumContrast = _props$valueEnumContr === void 0 ? false : _props$valueEnumContr,
     dateQueryPrecision = props.dateQueryPrecision,
+    headerFilter = props.headerFilter,
+    showQuickJumper = props.showQuickJumper,
+    showSizeChanger = props.showSizeChanger,
     rest = _objectWithoutProperties(props, _excluded);
   var _useGridPlusColumnSta = useGridPlusColumnState(),
     onSaveColumnState = _useGridPlusColumnSta.onSaveColumnState,
@@ -129,7 +150,27 @@ function AgGridPlus(props) {
     applySchemeToGlobal = _useGridPlusColumnSta.applySchemeToGlobal,
     resetToGlobal = _useGridPlusColumnSta.resetToGlobal,
     resetAllUsers = _useGridPlusColumnSta.resetAllUsers,
-    hostEntityExtensions = _useGridPlusColumnSta.hostEntityExtensions;
+    hostEntityExtensions = _useGridPlusColumnSta.hostEntityExtensions,
+    density = _useGridPlusColumnSta.density,
+    densityOverrides = _useGridPlusColumnSta.densityValues,
+    onDensityChange = _useGridPlusColumnSta.onDensityChange;
+
+  // 密度由 Provider 注入；没注入时保持出厂外观。页面 `theme` 传普通对象时叠加在 token 与密度之上，
+  // 传 AG Grid Theme 实例或字符串时仍整体替换（兼容旧用法）。@author nokecy
+  var densitySpec = useMemo(function () {
+    return resolveGridDensity(density, densityOverrides);
+  }, [density, densityOverrides]);
+  var pageThemeParams = useMemo(function () {
+    var t = rest.theme;
+    return t && _typeof(t) === 'object' && typeof t.withParams !== 'function' ? t : undefined;
+  }, [rest.theme]);
+  var gridTheme = useAgGridTheme({
+    density: densitySpec,
+    themeParams: pageThemeParams
+  });
+  var rowColors = useMemo(function () {
+    return deriveRowColors(token.colorPrimary, token.colorLink);
+  }, [token.colorPrimary, token.colorLink]);
   var gridRef = useRef(undefined);
   var apiRef = useRef(undefined);
   var allColDefsRef = useRef([]);
@@ -151,6 +192,22 @@ function AgGridPlus(props) {
   }, [props.getRowId, generateUniqueRowId]);
   var resolveRowIdRef = useRef(resolveRowId);
   resolveRowIdRef.current = resolveRowId;
+
+  // 跨页勾选：按行 ID 记住所有已勾选的行，翻页后把当前页命中的行重新勾上 @author nokecy
+  var crossPageRef = useRef(crossPageSelection);
+  crossPageRef.current = crossPageSelection;
+  var crossPage = useMemo(function () {
+    return createCrossPageSelection(function (row) {
+      return resolveRowIdRef.current({
+        data: row,
+        level: 0,
+        api: apiRef.current,
+        context: null
+      });
+    });
+  }, []);
+  var onCrossPageChangeRef = useRef(onCrossPageSelectionChange);
+  onCrossPageChangeRef.current = onCrossPageSelectionChange;
   var _useState = useState(false),
     _useState2 = _slicedToArray(_useState, 2),
     ready = _useState2[0],
@@ -165,44 +222,69 @@ function AgGridPlus(props) {
     _useState6 = _slicedToArray(_useState5, 2),
     loading = _useState6[0],
     setLoading = _useState6[1];
-  // 空态四分需要的两个事实：这次请求是不是失败了、用户有没有施加筛选。@author nokecy
-  var _useState7 = useState(null),
+  // 首次请求发出前表里本来就是空的，此时不能显示空态文案，要显示骨架。
+  // 用「请求已发出且已结束」反推，而不是只看 loading：loading 在首个请求发出前一直是 false。@author nokecy
+  var _useState7 = useState(!!request),
     _useState8 = _slicedToArray(_useState7, 2),
-    loadError = _useState8[0],
-    setLoadError = _useState8[1];
-  var _useState9 = useState(false),
+    firstLoadPending = _useState8[0],
+    setFirstLoadPending = _useState8[1];
+  var requestStartedRef = useRef(false);
+  // 空态四分需要的两个事实：这次请求是不是失败了、用户有没有施加筛选。@author nokecy
+  var _useState9 = useState(null),
     _useState10 = _slicedToArray(_useState9, 2),
-    filtered = _useState10[0],
-    setFiltered = _useState10[1];
-  var _useState11 = useState(),
+    loadError = _useState10[0],
+    setLoadError = _useState10[1];
+  var _useState11 = useState(false),
     _useState12 = _slicedToArray(_useState11, 2),
-    columnState = _useState12[0],
-    setColumnState = _useState12[1];
-  var _useState13 = useState({}),
+    filtered = _useState12[0],
+    setFiltered = _useState12[1];
+  var _useState13 = useState(),
     _useState14 = _slicedToArray(_useState13, 2),
-    columnCellClass = _useState14[0],
-    setColumnCellClass = _useState14[1];
-  var _useState15 = useState([]),
+    columnState = _useState14[0],
+    setColumnState = _useState14[1];
+  var _useState15 = useState({}),
     _useState16 = _slicedToArray(_useState15, 2),
-    rowData = _useState16[0],
-    setRowData = _useState16[1];
-  var _useState17 = useState({}),
+    columnCellClass = _useState16[0],
+    setColumnCellClass = _useState16[1];
+  var _useState17 = useState([]),
     _useState18 = _slicedToArray(_useState17, 2),
-    queryFilter = _useState18[0],
-    setQueryFilter = _useState18[1];
-  var _useState19 = useState(),
+    rowData = _useState18[0],
+    setRowData = _useState18[1];
+  var _useState19 = useState({}),
     _useState20 = _slicedToArray(_useState19, 2),
-    sortColumn = _useState20[0],
-    setSortColumn = _useState20[1];
+    queryFilter = _useState20[0],
+    setQueryFilter = _useState20[1];
+  var _useState21 = useState(),
+    _useState22 = _slicedToArray(_useState21, 2),
+    sortColumn = _useState22[0],
+    setSortColumn = _useState22[1];
   // 初始化分页参数，支持外部传入的pageSize
-  var _useState21 = useState({
-      pageSize: props.pageSize !== undefined ? props.pageSize : props.hidePagination ? 10000 : 200,
+  var _useState23 = useState({
+      pageSize: resolveInitialPageSize(props.pageSize, props.hidePagination),
       current: 1,
       total: dataSource ? dataSource.length : 0
     }),
-    _useState22 = _slicedToArray(_useState21, 2),
-    pagination = _useState22[0],
-    setPagination = _useState22[1];
+    _useState24 = _slicedToArray(_useState23, 2),
+    pagination = _useState24[0],
+    setPagination = _useState24[1];
+
+  // dataSource 本地数据模式：分页器要真正切片，而不是只显示页码。
+  // 总数与页码按 dataSource 当场推导，数据增删后页码自动收回末页，无需再同步 state。
+  // 树形数据按层级展开，不能按行切片，保持整表。@author nokecy
+  var localPaging = !!dataSource && !request && !props.hidePagination && !props.treeData;
+  var pageTotal = localPaging ? dataSource.length : pagination.total;
+  var pageCurrent = localPaging ? clampPage(pagination.current, pageTotal, pagination.pageSize) : pagination.current;
+  // 命令式入口（GridRef）与异步回调读取最新分页，避免闭包拿到旧页码
+  var paginationRef = useRef({
+    current: pageCurrent,
+    pageSize: pagination.pageSize,
+    total: pageTotal
+  });
+  paginationRef.current = {
+    current: pageCurrent,
+    pageSize: pagination.pageSize,
+    total: pageTotal
+  };
 
   // ============ 方案管理 - 使用集中式 Context ============
   var _useGridSchemes = useGridSchemes(),
@@ -221,16 +303,22 @@ function AgGridPlus(props) {
     getColumnSchemes = _useGridSchemes.getColumnSchemes,
     getQuerySchemes = _useGridSchemes.getQuerySchemes,
     getCurrentScheme = _useGridSchemes.getCurrentScheme;
-  var _useState23 = useState([]),
-    _useState24 = _slicedToArray(_useState23, 2),
-    queryItemsOrder = _useState24[0],
-    setQueryItemsOrder = _useState24[1];
+  var _useState25 = useState([]),
+    _useState26 = _slicedToArray(_useState25, 2),
+    queryItemsOrder = _useState26[0],
+    setQueryItemsOrder = _useState26[1];
+  // 查询区操作句柄：查询方案管理经它读取当前条件值 @author nokecy
+  var queryFormApiRef = useRef(null);
+  var getQueryValues = useCallback(function () {
+    var _queryFormApiRef$curr, _queryFormApiRef$curr2;
+    return (_queryFormApiRef$curr = (_queryFormApiRef$curr2 = queryFormApiRef.current) === null || _queryFormApiRef$curr2 === void 0 ? void 0 : _queryFormApiRef$curr2.getValues()) !== null && _queryFormApiRef$curr !== void 0 ? _queryFormApiRef$curr : {};
+  }, []);
 
   // 高级查询状态
-  var _useState25 = useState(false),
-    _useState26 = _slicedToArray(_useState25, 2),
-    advancedPopoverOpen = _useState26[0],
-    setAdvancedPopoverOpen = _useState26[1];
+  var _useState27 = useState(false),
+    _useState28 = _slicedToArray(_useState27, 2),
+    advancedPopoverOpen = _useState28[0],
+    setAdvancedPopoverOpen = _useState28[1];
   var createEmptyRuleGroup = function createEmptyRuleGroup() {
     return {
       id: uuidv4(),
@@ -238,17 +326,21 @@ function AgGridPlus(props) {
       children: []
     };
   };
-  var _useState27 = useState(createEmptyRuleGroup),
-    _useState28 = _slicedToArray(_useState27, 2),
-    advancedQueryRules = _useState28[0],
-    setAdvancedQueryRules = _useState28[1];
+  var _useState29 = useState(createEmptyRuleGroup),
+    _useState30 = _slicedToArray(_useState29, 2),
+    advancedQueryRules = _useState30[0],
+    setAdvancedQueryRules = _useState30[1];
+  // 查询区回调可能还是旧渲染里的闭包，「重置」要在同一次点击里让它读到已清空的高级条件，所以另放一份 ref。
+  var advancedRulesRef = useRef(advancedQueryRules);
+  advancedRulesRef.current = advancedQueryRules;
   useImperativeHandle(propsGridRef, function () {
     return gridRef.current;
   });
 
   //默认列属性
+  var pageDefaultColDef = useDeepCompareStable(rest.defaultColDef);
   var defaultColDef = useMemo(function () {
-    return {
+    var builtIn = {
       resizable: true,
       sortable: true,
       // suppressHeaderFilterButton: true,
@@ -261,7 +353,11 @@ function AgGridPlus(props) {
         '<span data-ref="eFilterButton" class="ag-header-icon ag-header-cell-filter-button"></span>' + '<div data-ref="eLabel" class="ag-header-cell-label" role="presentation">' + '<span data-ref="eText" class="ag-header-cell-text" role="columnheader"></span>' + '<span data-ref="eFilter" class="ag-header-icon ag-filter-icon"></span>' + '<span data-ref="eSortOrder" class="ag-header-icon ag-sort-order"></span>' + '<span data-ref="eSortDesc" class="ag-header-icon ag-sort-descending-icon"></span>' + '<span data-ref="eSortAsc" class="ag-header-icon ag-sort-ascending-icon"></span>' + '<span data-ref="eSortNone" class="ag-header-icon ag-sort-none-icon"></span>' + '</div>' + '</div>'
       }
     };
-  }, []);
+    // 页面传入的 defaultColDef 与内置合并（页面优先），headerFilter=false 全局收起列头筛选按钮
+    return mergeDefaultColDef(builtIn, pageDefaultColDef, {
+      headerFilter: headerFilter
+    });
+  }, [pageDefaultColDef, headerFilter]);
   var columnTypes = useMemo(function () {
     return {
       bool: {
@@ -304,6 +400,11 @@ function AgGridPlus(props) {
     setRowData(dataSource || propRowData || []);
   }, [dataSource, propRowData]);
 
+  // 首次请求结束（成功或失败）后不再算「首次加载」
+  useEffect(function () {
+    if (!loading && requestStartedRef.current && firstLoadPending) setFirstLoadPending(false);
+  }, [loading, firstLoadPending]);
+
   //外部loading
   useEffect(function () {
     loadingProps !== undefined && setLoading(loadingProps);
@@ -326,7 +427,9 @@ function AgGridPlus(props) {
 
   // 辅助函数: 处理单个列配置
   var processColumnConfig = function processColumnConfig(col, data) {
+    var _col;
     var dataType = getDataType(data, col.field || '', col.valueEnum);
+    if (defaultValueFormat) col = withDefaultValueFormat(col, (dataType === null || dataType === void 0 ? void 0 : dataType.type) === 'number' && dataType.calculateType !== false);
     if (col.valueEnum && Array.isArray(col.valueEnum)) {
       // 枚举列渲染只走一处实现，见 columnProcessors.processEnumColumn
       // （命中上色、未命中交给 col.enumFallbackRenderer，都没配则回原始码）
@@ -336,7 +439,7 @@ function AgGridPlus(props) {
       return mergeInferredColumnType(col, dataType);
     }
     //@ts-ignore
-    if (col !== null && col !== void 0 && col.ellipsis) {
+    if ((_col = col) !== null && _col !== void 0 && _col.ellipsis) {
       return processEllipsisColumn(mergeInferredColumnType(col, dataType));
     }
     if (col.cellRenderer) {
@@ -438,7 +541,7 @@ function AgGridPlus(props) {
       });
     }
     return cols;
-  }, [React.Children.count(children), props.columnDefs, extensibleColumns, gridKey, entityType, hostEntityExtensions, typeInferenceRow, valueEnumContrast ? token.colorBgContainer : undefined]);
+  }, [React.Children.count(children), props.columnDefs, extensibleColumns, gridKey, entityType, hostEntityExtensions, typeInferenceRow, defaultValueFormat, valueEnumContrast ? token.colorBgContainer : undefined]);
 
   // 方案派生依赖本轮源码列，避免读取尚未更新的 ref 快照。@author nokecy
   /**
@@ -464,12 +567,46 @@ function AgGridPlus(props) {
   var currentColumnSchemes = schemeDataFlow.columnSchemes,
     currentColumnScheme = schemeDataFlow.currentColumnScheme,
     currentQuerySchemes = schemeDataFlow.querySchemes,
-    currentQueryScheme = schemeDataFlow.currentQueryScheme,
+    resolvedQueryScheme = schemeDataFlow.currentQueryScheme,
     derivedColumnDefs = schemeDataFlow.derivedColumnDefs,
     derivedColumnState = schemeDataFlow.derivedColumnState,
     isUsingGlobalFallback = schemeDataFlow.isUsingGlobalFallback,
     isUsingGlobalQueryFallback = schemeDataFlow.isUsingGlobalQueryFallback;
 
+  // 「重置」取消当前应用的查询方案：默认/全局方案是按回退规则算出来的，只清存储的 ID 仍会被回退算回来，
+  // 所以本页内另用一个标记压住它；用户重新选方案（ID 变为非空）时解除。
+  var _useState31 = useState(false),
+    _useState32 = _slicedToArray(_useState31, 2),
+    querySchemeDismissed = _useState32[0],
+    setQuerySchemeDismissed = _useState32[1];
+  var currentQueryScheme = querySchemeDismissed ? undefined : resolvedQueryScheme;
+  var storedQuerySchemeId = currentSchemes === null || currentSchemes === void 0 || (_currentSchemes = currentSchemes[gridKey || '']) === null || _currentSchemes === void 0 ? void 0 : _currentSchemes.querySchemeId;
+  useEffect(function () {
+    if (storedQuerySchemeId) setQuerySchemeDismissed(false);
+  }, [storedQuerySchemeId]);
+  var resetQueryScheme = useCallback(function () {
+    var _setCurrentQuerySchem, _setCurrentQuerySchem2;
+    setQuerySchemeDismissed(true);
+    // 重置要恢复全量，高级搜索条件一并清空，否则提交时仍会优先走高级条件。
+    var empty = createEmptyRuleGroup();
+    advancedRulesRef.current = empty;
+    setAdvancedQueryRules(empty);
+    // 存储里清成 null 后，再次选择同一方案才会是一次真实变化；下次进入页面仍按默认方案规则回退。
+    if (gridKey) setCurrentQueryScheme === null || setCurrentQueryScheme === void 0 || (_setCurrentQuerySchem = setCurrentQueryScheme(gridKey, null)) === null || _setCurrentQuerySchem === void 0 || (_setCurrentQuerySchem2 = _setCurrentQuerySchem.catch) === null || _setCurrentQuerySchem2 === void 0 || _setCurrentQuerySchem2.call(_setCurrentQuerySchem, function () {});
+  }, [gridKey, setCurrentQueryScheme]);
+
+  // 表头上拖拽列宽、列序后自动记忆（DESIGN.md §7.5）
+  useAutoColumnMemory({
+    enabled: autoRememberColumns,
+    gridKey: gridKey,
+    ready: ready,
+    api: ready ? apiRef.current : undefined,
+    originalColumnDefs: allColDefs,
+    currentScheme: currentColumnScheme,
+    saveColumnScheme: saveColumnScheme,
+    setCurrentColumnScheme: setCurrentColumnScheme
+  });
+
   /**
    * 【P0 + P1 优化】使用派生状态应用方案（单向数据流）
    *
@@ -514,13 +651,6 @@ function AgGridPlus(props) {
           });
         });
       });
-    }).then(function () {
-      if (cancelled || !apiRef.current) return;
-
-      // 3. 应用过滤器（在列状态稳定后执行）
-      if (currentColumnScheme !== null && currentColumnScheme !== void 0 && currentColumnScheme.filterModel) {
-        apiRef.current.setFilterModel(currentColumnScheme.filterModel);
-      }
     }).catch(function (error) {
       if (!cancelled) {
         console.error('[AgGridPlus] 应用方案失败:', error);
@@ -601,6 +731,7 @@ function AgGridPlus(props) {
   var onRequest = useCallback(function (queryFilter) {
     if (!requestRef.current) return;
     setLoading(true);
+    requestStartedRef.current = true;
     logger.debug('开始请求数据', {
       queryFilter: queryFilter,
       pagination: pagination
@@ -656,7 +787,7 @@ function AgGridPlus(props) {
         // 场景：用户执行操作（如审核）后刷新列表，选中行的数据已变化
         // 需要从新数据中找到对应的行，同步更新业务层的选中状态
         // 支持两种回调方式：onSelectedRowsChange 和 onSelectionChanged
-        if (apiRef.current) {
+        if (apiRef.current && !crossPageRef.current) {
           // 使用 requestAnimationFrame 确保 AG-Grid 数据更新完成
           requestAnimationFrame(function () {
             if (!apiRef.current) return;
@@ -768,6 +899,16 @@ function AgGridPlus(props) {
       stableSortColumn: stableSortColumn
     };
     if (ready && formInitialized && requestRef.current) {
+      // 外部 params 变化意味着换了一批数据，停在原页码会落到别人的第 N 页甚至空页。
+      // 先回第 1 页，由页码变化再触发请求，避免先带着旧页码发一次。
+      if (changedDeps.includes('stableGridParams') && pagination.current !== 1) {
+        setPagination(function (prev) {
+          return _objectSpread(_objectSpread({}, prev), {}, {
+            current: 1
+          });
+        });
+        return;
+      }
       logger.debug('useEffect 触发数据请求', {
         ready: ready,
         formInitialized: formInitialized,
@@ -812,10 +953,54 @@ function AgGridPlus(props) {
     }
   }, [onRequest, stableQueryFilter]);
 
+  // 查询区、高级查询的回调可能是旧渲染里捕获的闭包（实测在第 2 页点「重置」时拿到的是第 1 页），
+  // 所以发请求、判断页码一律走 ref，永远读最新一次渲染。
+  var onRequestRef = useRef(onRequest);
+  onRequestRef.current = onRequest;
+
+  /**
+   * 提交一组查询条件：非第 1 页时只回第 1 页，请求由页码变化触发（此处再发会带着旧页码多发一次）；
+   * 已在第 1 页则直接发。
+   */
+  // 条件变了由「条件变化」effect 请求一次，这里不能再发；只有条件没变（重新取数）才直接发，见 needsDirectRequest。
+  var appliedFilterRef = useRef(stableQueryFilter);
+  appliedFilterRef.current = stableQueryFilter;
+  var submitQuery = useCallback(function (filter) {
+    var previous = appliedFilterRef.current;
+    setQueryFilter(filter);
+    if (paginationRef.current.current !== 1) {
+      setPagination(function (prev) {
+        return _objectSpread(_objectSpread({}, prev), {}, {
+          current: 1
+        });
+      });
+      return;
+    }
+    if (needsDirectRequest(previous, filter, 1)) onRequestRef.current(filter);
+  }, []);
+  var goToPage = useCallback(function (page) {
+    var _paginationRef$curren = paginationRef.current,
+      pageSize = _paginationRef$curren.pageSize,
+      total = _paginationRef$curren.total;
+    var target = clampPage(page, total, pageSize);
+    setPagination(function (prev) {
+      return prev.current === target ? prev : _objectSpread(_objectSpread({}, prev), {}, {
+        current: target
+      });
+    });
+  }, []);
+  var resetPage = useCallback(function () {
+    return goToPage(1);
+  }, [goToPage]);
+  var getPagination = useCallback(function () {
+    return _objectSpread({}, paginationRef.current);
+  }, []);
+
   // 空态四分：加载失败 / 无权限 / 筛选无结果 / 无数据，各说各的，失败那支还给出「重试」。
   // 以前四种情况共用一句「没有找到数据，试试调整筛选条件吧！」，接口挂了也这么说，
   // 用户按提示去调筛选，越调越没有。@author nokecy
   var noRowsOverlayParams = useMemo(function () {
+    var _loadError$getRemoteS;
     return {
       branch: resolveEmptyBranch({
         hasError: !!loadError,
@@ -827,7 +1012,8 @@ function AgGridPlus(props) {
         accessible: accessible,
         filtered: filtered,
         override: overlayNoRowsTemplateText,
-        texts: emptyState
+        texts: emptyState,
+        reason: loadError === null || loadError === void 0 || (_loadError$getRemoteS = loadError.getRemoteServiceError()) === null || _loadError$getRemoteS === void 0 ? void 0 : _loadError$getRemoteS.message
       }),
       onRetry: onRefresh
     };
@@ -836,11 +1022,16 @@ function AgGridPlus(props) {
   var noRowsOverlay = useMemo(function () {
     return resolveNoRowsOverlay(NoRowsOverlay, noRowsOverlayParams, rest.noRowsOverlayComponent, rest.noRowsOverlayComponentParams);
   }, [noRowsOverlayParams, rest.noRowsOverlayComponent, rest.noRowsOverlayComponentParams]);
-  useEffect(function () {
-    gridRef.current = {
-      onRefresh: onRefresh
+
+  // 渲染期就位，保证首次提交时 useImperativeHandle 已能拿到实例（原先放在 effect 里，首个提交拿到 undefined）
+  gridRef.current = useMemo(function () {
+    return {
+      onRefresh: onRefresh,
+      goToPage: goToPage,
+      resetPage: resetPage,
+      getPagination: getPagination
     };
-  }, [onRefresh]);
+  }, [onRefresh, goToPage, resetPage, getPagination]);
   var onRowChanged = useCallback(function (e) {
     if (props.onSelectionChanged) {
       props.onSelectionChanged(e);
@@ -860,7 +1051,37 @@ function AgGridPlus(props) {
     onErrorRef.current = props.onError;
     requestRef.current = request;
   }, [onSelectedRowsChange, props.onRowSelected, props.onError, request]);
+
+  // 跨页模式下对外通知：行集合是所有页的并集，另给「不在当前页的数量」和清除入口
+  var emitCrossPage = useCallback(function () {
+    var _onSelectedRowsChange, _onCrossPageChangeRef, _apiRef$current$getSe, _apiRef$current4;
+    var rows = crossPage.rows();
+    (_onSelectedRowsChange = onSelectedRowsChangeRef.current) === null || _onSelectedRowsChange === void 0 || _onSelectedRowsChange.call(onSelectedRowsChangeRef, rows);
+    (_onCrossPageChangeRef = onCrossPageChangeRef.current) === null || _onCrossPageChangeRef === void 0 || _onCrossPageChangeRef.call(onCrossPageChangeRef, {
+      rows: rows,
+      count: rows.length,
+      outsideCurrentPage: Math.max(0, rows.length - ((_apiRef$current$getSe = (_apiRef$current4 = apiRef.current) === null || _apiRef$current4 === void 0 ? void 0 : _apiRef$current4.getSelectedNodes().length) !== null && _apiRef$current$getSe !== void 0 ? _apiRef$current$getSe : 0)),
+      clear: function clear() {
+        var _apiRef$current5;
+        crossPage.clear();
+        (_apiRef$current5 = apiRef.current) === null || _apiRef$current5 === void 0 || _apiRef$current5.deselectAll();
+        emitCrossPageRef.current();
+      }
+    });
+  }, [crossPage]);
+  var emitCrossPageRef = useRef(emitCrossPage);
+  emitCrossPageRef.current = emitCrossPage;
   var onRowSelected = useCallback(function (e) {
+    if (crossPageRef.current) {
+      var _onRowSelectedCallbac;
+      // 换页时 AG Grid 因数据替换触发的取消勾选不是用户操作，不能改写记录
+      if (!crossPage.isRestoring() && e.source !== 'rowDataChanged') {
+        crossPage.track(e.node);
+        emitCrossPageRef.current();
+      }
+      (_onRowSelectedCallbac = onRowSelectedCallbackRef.current) === null || _onRowSelectedCallbac === void 0 || _onRowSelectedCallbac.call(onRowSelectedCallbackRef, e);
+      return;
+    }
     // 处理选中行数据回调
     if (onSelectedRowsChangeRef.current && apiRef.current) {
       // 获取所有选中的行
@@ -905,18 +1126,18 @@ function AgGridPlus(props) {
       });
     }
     if (!allColDefs || displayedData.length === 0) {
-      var _apiRef$current4;
-      (_apiRef$current4 = apiRef.current) === null || _apiRef$current4 === void 0 || _apiRef$current4.setGridOption('pinnedBottomRowData', undefined);
+      var _apiRef$current6;
+      (_apiRef$current6 = apiRef.current) === null || _apiRef$current6 === void 0 || _apiRef$current6.setGridOption('pinnedBottomRowData', undefined);
       return;
     }
     var calcColFields = getCalculationColumns(allColDefs);
     if (calcColFields.length > 0) {
-      var _apiRef$current5;
+      var _apiRef$current7;
       var calculatedValues = computeAggregationRow(calcColFields, displayedData);
-      (_apiRef$current5 = apiRef.current) === null || _apiRef$current5 === void 0 || _apiRef$current5.setGridOption('pinnedBottomRowData', calculatedValues);
+      (_apiRef$current7 = apiRef.current) === null || _apiRef$current7 === void 0 || _apiRef$current7.setGridOption('pinnedBottomRowData', calculatedValues);
     } else {
-      var _apiRef$current6;
-      (_apiRef$current6 = apiRef.current) === null || _apiRef$current6 === void 0 || _apiRef$current6.setGridOption('pinnedBottomRowData', undefined);
+      var _apiRef$current8;
+      (_apiRef$current8 = apiRef.current) === null || _apiRef$current8 === void 0 || _apiRef$current8.setGridOption('pinnedBottomRowData', undefined);
     }
   }, [allColDefs, props.pinnedBottomRowData]);
   var onFilterChanged = function onFilterChanged(event) {
@@ -1026,13 +1247,31 @@ function AgGridPlus(props) {
     if (props.treeData && !useNativeTreeFilter) {
       return flatten(toTree(rowData, treeKeyName !== null && treeKeyName !== void 0 ? treeKeyName : "id", treeParentName !== null && treeParentName !== void 0 ? treeParentName : "parentId"), treeKeyName !== null && treeKeyName !== void 0 ? treeKeyName : "id");
     }
-    return rowData;
-  }, [rowData, props.treeData, treeKeyName, treeParentName, useNativeTreeFilter]);
+    return localPaging ? sliceRowsByPage(rowData, pageCurrent, pagination.pageSize) : rowData;
+  }, [rowData, props.treeData, treeKeyName, treeParentName, useNativeTreeFilter, localPaging, pageCurrent, pagination.pageSize]);
+
+  // 跨页勾选：新一页数据进入网格后，把记录里命中的行重新勾上。
+  // 子组件（AgGridReact）的 effect 先于本 effect 执行，此时新行已在网格里；再补一帧兜底慢一拍的情况。
+  useEffect(function () {
+    if (!crossPageRef.current || !apiRef.current) return;
+    var restore = function restore() {
+      if (apiRef.current && !apiRef.current.isDestroyed() && crossPage.restore(apiRef.current)) emitCrossPageRef.current();
+    };
+    restore();
+    var raf = requestAnimationFrame(restore);
+    return function () {
+      return cancelAnimationFrame(raf);
+    };
+  }, [rowDataMemo, crossPage]);
+
+  // 加载态：首次请求发出前也算加载中；表里没有行时用骨架，有行时只给顶部加载条、不盖住数据
+  var busy = loading || firstLoadPending;
+  var showSkeleton = busy && rowData.length === 0;
   var actionDom = toolBarRender && toolBarRender(apiRef.current, convertFilterModel(queryFilter, allColDefsRef.current), queryFilter, {
-    current: pagination.current,
-    skipCount: pagination.current == 1 ? 0 : (pagination.current - 1) * pagination.pageSize,
+    current: pageCurrent,
+    skipCount: pageCurrent == 1 ? 0 : (pageCurrent - 1) * pagination.pageSize,
     maxResultCount: pagination.pageSize,
-    page: pagination.current,
+    page: pageCurrent,
     pageSize: pagination.pageSize
   });
   var autoGroupColumnDef = useMemo(function () {
@@ -1071,6 +1310,23 @@ function AgGridPlus(props) {
     _iterator.f();
   }
   Object.assign(gridPassthroughProps, selectionOptions.eventHandlers);
+  // 普通对象的 theme 已叠加进 gridTheme，不能再原样透传把它整体盖掉
+  if (pageThemeParams) delete gridPassthroughProps.theme;
+
+  // 列表键盘模型（§7.9）：Alt+A、Alt+Shift+↑↓、Ctrl/⌘+←→、Esc。捕获阶段处理，命中后不再交给 AG Grid
+  var listKeyHandler = useMemo(function () {
+    return createListKeyHandler({
+      getApi: function getApi() {
+        return apiRef.current;
+      },
+      onPage: props.hidePagination ? undefined : function (delta) {
+        return goToPage(paginationRef.current.current + delta);
+      }
+    });
+  }, [goToPage, props.hidePagination]);
+  var onTableKeyDownCapture = useCallback(function (e) {
+    if (listKeyHandler(e.nativeEvent)) e.stopPropagation();
+  }, [listKeyHandler]);
 
   // 传给 AG-Grid 的列定义：qc-ui 专属列属性收进 colDef.context，内部通过 getQcColDefProp 读取
   var agColumnDefs = useMemo(function () {
@@ -1083,7 +1339,8 @@ function AgGridPlus(props) {
     return {
       queryFormItems: queryFormItems,
       currentQueryOrder: currentQueryScheme ? extractItemsOrder(currentQueryScheme) : queryItemsOrder,
-      updateQueryOrder: setQueryItemsOrder
+      updateQueryOrder: setQueryItemsOrder,
+      getQueryValues: getQueryValues
     };
   }, [queryFormItems, currentQueryScheme, queryItemsOrder]);
 
@@ -1125,7 +1382,10 @@ function AgGridPlus(props) {
       isUsingGlobalFallback: isUsingGlobalFallback,
       isUsingGlobalQueryFallback: isUsingGlobalQueryFallback,
       // ========== 实体扩展字段配置 @author nokecy ==========
-      hostEntityExtensions: hostEntityExtensions
+      hostEntityExtensions: hostEntityExtensions,
+      // ========== 密度：列设置里的密度入口读取 @author nokecy ==========
+      density: density,
+      onDensityChange: onDensityChange
     };
   }, [extensibleColumns, gridPlusColumnState,
   // ref.current 作依赖无效(变更不触发重渲染);依赖数据源 allColDefs,initialColumnDefs 随其首次计算填充 @author nokecy
@@ -1137,13 +1397,13 @@ function AgGridPlus(props) {
   // 全局方案回退状态依赖 @author nokecy
   isUsingGlobalFallback, isUsingGlobalQueryFallback,
   // 实体扩展字段配置依赖 @author nokecy
-  hostEntityExtensions]);
+  hostEntityExtensions, density, onDensityChange]);
   return /*#__PURE__*/_jsx(GridPlusContext.Provider, {
     value: gridPlusContextValue,
     children: /*#__PURE__*/_jsx(QueryFormContext.Provider, {
       value: queryFormContextValue,
       children: /*#__PURE__*/_jsx(Spin, {
-        spinning: loading,
+        spinning: false,
         classNames: {
           root: "grid-spin"
         },
@@ -1163,34 +1423,23 @@ function AgGridPlus(props) {
             defaultExpand: defaultSearchExpand,
             gridApi: apiRef.current,
             onValuesChange: onQueryValuesChange,
+            scheme: currentQueryScheme ? {
+              id: currentQueryScheme.id,
+              name: currentQueryScheme.name,
+              values: (_currentQueryScheme$q = currentQueryScheme.queryConfig) === null || _currentQueryScheme$q === void 0 ? void 0 : _currentQueryScheme$q.defaultValues
+            } : undefined,
+            apiRef: queryFormApiRef,
+            onResetScheme: resetQueryScheme,
             onQuery: function onQuery(formValues) {
               // 优先使用高级搜索：如果存在高级搜索条件，忽略简单查询
-              if (advancedQueryRules.children.length > 0) {
-                var filter = {
+              if (advancedRulesRef.current.children.length > 0) {
+                submitQuery({
                   __advancedMode__: true,
-                  __rules__: advancedQueryRules
-                };
-                setQueryFilter(filter);
-                if (pagination.current !== 1) {
-                  setPagination(function (prev) {
-                    return _objectSpread(_objectSpread({}, prev), {}, {
-                      current: 1
-                    });
-                  });
-                }
-                onRequest && onRequest(filter);
-                return;
-              }
-              setQueryFilter(_objectSpread({}, formValues));
-              // 始终使用传入的 formValues 发起请求
-              if (pagination.current !== 1) {
-                setPagination(function (prev) {
-                  return _objectSpread(_objectSpread({}, prev), {}, {
-                    current: 1
-                  });
+                  __rules__: advancedRulesRef.current
                 });
+                return;
               }
-              onRequest && onRequest(formValues);
+              submitQuery(_objectSpread({}, formValues));
             },
             onInit: function onInit(defaultValues) {
               // 【修复】先设置 queryFilter，再标记表单已初始化
@@ -1218,18 +1467,32 @@ function AgGridPlus(props) {
             },
             children: [/*#__PURE__*/_jsxs("div", {
               className: "qc-table-container",
-              style: _objectSpread({
+              "aria-busy": busy || undefined,
+              onKeyDownCapture: onTableKeyDownCapture,
+              style: _objectSpread(_objectSpread({
                 display: "flex",
                 flexDirection: "column",
                 height: "100%"
-              }, style),
-              children: [hideTool ? null : /*#__PURE__*/_jsx(ToolBar, {
+              }, rowColors ? {
+                '--qc-row-selected-hover-bg': rowColors.selectedHover
+              } : {}), style),
+              children: [busy && !showSkeleton ? /*#__PURE__*/_jsx("div", {
+                className: "qc-grid-busy-bar",
+                role: "progressbar",
+                "aria-label": "\u6B63\u5728\u52A0\u8F7D",
+                children: /*#__PURE__*/_jsx("span", {
+                  style: {
+                    background: token.colorPrimary
+                  }
+                })
+              }) : null, hideTool ? null : /*#__PURE__*/_jsx(ToolBar, {
                 title: headerTitle,
                 actions: actionDom,
                 settings: [/*#__PURE__*/_jsx(SettingItem, {
+                  title: "\u5237\u65B0",
                   onClick: onRefresh,
                   icon: /*#__PURE__*/_jsx(RedoOutlined, {})
-                }), /*#__PURE__*/_jsx(Setting, {
+                }, "refresh"), /*#__PURE__*/_jsx(Setting, {
                   gridKey: gridKey,
                   gridApi: apiRef.current,
                   onSaveColumnState: onColumnStateChanged
@@ -1257,8 +1520,7 @@ function AgGridPlus(props) {
                         size: "small",
                         onClick: function onClick() {
                           setAdvancedQueryRules(createEmptyRuleGroup());
-                          setQueryFilter({});
-                          onRequest && onRequest({});
+                          submitQuery({});
                           setAdvancedPopoverOpen(false);
                         },
                         style: {
@@ -1269,19 +1531,10 @@ function AgGridPlus(props) {
                         size: "small",
                         type: "primary",
                         onClick: function onClick() {
-                          var filter = {
+                          submitQuery({
                             __advancedMode__: true,
                             __rules__: advancedQueryRules
-                          };
-                          setQueryFilter(filter);
-                          if (pagination.current !== 1) {
-                            setPagination(function (prev) {
-                              return _objectSpread(_objectSpread({}, prev), {}, {
-                                current: 1
-                              });
-                            });
-                          }
-                          onRequest && onRequest(filter);
+                          });
                           setAdvancedPopoverOpen(false);
                         },
                         children: "\u67E5\u8BE2"
@@ -1302,20 +1555,20 @@ function AgGridPlus(props) {
                     count: advancedQueryRules.children.length,
                     size: "small",
                     offset: [-2, 2],
-                    children: /*#__PURE__*/_jsx("div", {
-                      style: {
-                        margin: "0 4px",
-                        color: advancedQueryRules.children.length > 0 ? token.colorPrimary : token.colorText,
-                        fontSize: 16,
-                        cursor: "pointer"
-                      },
-                      children: /*#__PURE__*/_jsx(FilterOutlined, {})
+                    children: /*#__PURE__*/_jsx(SettingItem, {
+                      title: "\u9AD8\u7EA7\u641C\u7D22",
+                      icon: /*#__PURE__*/_jsx(FilterOutlined, {}),
+                      active: advancedQueryRules.children.length > 0,
+                      "aria-haspopup": "dialog"
                     })
                   })
                 }, "advanced-search-setting") : null].filter(Boolean)
-              }), /*#__PURE__*/_jsx(AgGridReact, _objectSpread(_objectSpread({
+              }), /*#__PURE__*/_jsx(AgGridReact, _objectSpread(_objectSpread(_objectSpread({
                 theme: gridTheme
-              }, gridPassthroughProps), {}, {
+              }, densitySpec ? {
+                rowHeight: densitySpec.rowHeight,
+                headerHeight: densitySpec.headerHeight
+              } : {}), gridPassthroughProps), {}, {
                 localeText: localeText,
                 gridOptions: {
                   enableCellTextSelection: true,
@@ -1324,10 +1577,14 @@ function AgGridPlus(props) {
                 },
                 noRowsOverlayComponent: noRowsOverlay.component,
                 noRowsOverlayComponentParams: noRowsOverlay.params
-                // 加载中不显示空态：外层 Spin 已经在转，再叠一句「暂无数据」会让用户
-                // 以为真的没数据（冒烟截图里这两者确实同时出现过）。@author nokecy
+                // 加载中不显示空态：再叠一句「暂无数据」会让用户以为真的没数据。
+                // 首次请求发出前（firstLoadPending）同样不显示。@author nokecy
+                ,
+                suppressNoRowsOverlay: busy
+                // 表里没有行时用骨架占住表体，表头保持可见
                 ,
-                suppressNoRowsOverlay: loading,
+                loading: showSkeleton,
+                loadingOverlayComponent: SkeletonOverlay,
                 cellSelection: (_rest$cellSelection = rest.cellSelection) !== null && _rest$cellSelection !== void 0 ? _rest$cellSelection : selectionOptions.cellSelection,
                 autoGroupColumnDef: selectionOptions.autoGroupColumnDef
                 // 【兼容】原生树形数据配置：只有 useNativeTreeFilter=true 时才启用
@@ -1358,8 +1615,8 @@ function AgGridPlus(props) {
                 },
                 onDragStopped: function onDragStopped(e) {
                   if (apiRef.current) {
-                    var _apiRef$current7;
-                    var _columnState = (_apiRef$current7 = apiRef.current) === null || _apiRef$current7 === void 0 ? void 0 : _apiRef$current7.getColumnState();
+                    var _apiRef$current9;
+                    var _columnState = (_apiRef$current9 = apiRef.current) === null || _apiRef$current9 === void 0 ? void 0 : _apiRef$current9.getColumnState();
                     setColumnState(_columnState);
 
                     // onColumnStateChanged && onColumnStateChanged(columnState)
@@ -1382,31 +1639,43 @@ function AgGridPlus(props) {
               style: {
                 marginTop: 12,
                 display: "flex",
-                justifyContent: "flex-end"
+                justifyContent: "space-between",
+                alignItems: "center"
               },
-              children: !props.hidePagination && /*#__PURE__*/_jsx(Pagination, {
-                pageSize: pagination.pageSize,
-                current: pagination.current,
-                total: pagination.total,
-                onChange: function onChange(page, pageSize) {
-                  setPagination(_objectSpread(_objectSpread({}, pagination), {}, {
-                    pageSize: pageSize,
-                    current: page
-                  }));
-                },
-                onShowSizeChange: function onShowSizeChange(current, size) {
-                  setPagination(_objectSpread(_objectSpread({}, pagination), {}, {
-                    pageSize: size,
-                    current: current
-                  }));
-                },
-                size: "small",
-                showTotal: function showTotal(total, range) {
-                  return "\u7B2C ".concat(range[0], "-").concat(range[1], " \u6761/\u603B\u5171 ").concat(total, " \u6761");
-                },
-                pageSizeOptions: props.pageSizeOptions || DEFAULT_PAGE_SIZE_OPTIONS,
-                hideOnSinglePage: false,
-                showQuickJumper: false
+              children: !props.hidePagination && /*#__PURE__*/_jsxs(_Fragment, {
+                children: [/*#__PURE__*/_jsx("span", {
+                  className: "qc-grid-total",
+                  style: {
+                    color: token.colorTextSecondary,
+                    fontSize: token.fontSizeSM
+                  },
+                  children: formatPaginationTotal(pageTotal, pageCurrent, pagination.pageSize)
+                }), /*#__PURE__*/_jsx(Pagination, {
+                  pageSize: pagination.pageSize,
+                  current: pageCurrent,
+                  total: pageTotal,
+                  onChange: function onChange(page, pageSize) {
+                    setPagination(function (prev) {
+                      return _objectSpread(_objectSpread({}, prev), {}, {
+                        pageSize: pageSize,
+                        current: page
+                      });
+                    });
+                  },
+                  onShowSizeChange: function onShowSizeChange(current, size) {
+                    setPagination(function (prev) {
+                      return _objectSpread(_objectSpread({}, prev), {}, {
+                        pageSize: size,
+                        current: current
+                      });
+                    });
+                  },
+                  size: "small",
+                  pageSizeOptions: props.pageSizeOptions || DEFAULT_PAGE_SIZE_OPTIONS,
+                  hideOnSinglePage: false,
+                  showSizeChanger: showSizeChanger,
+                  showQuickJumper: showQuickJumper !== null && showQuickJumper !== void 0 ? showQuickJumper : false
+                })]
               })
             })]
           })]