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

package/dist/esm/ag-grid-plus/context/gridContext.d.ts

@@ -2,6 +2,7 @@ import React from "react";
 import type { ColumnScheme, QueryScheme, CurrentSchemeDto } from "../shared/storage/schemeStorageAdapter";
 import type { GlobalConfigPermissions } from '../shared/permissions/globalConfigPermissions';
 import type { HostEntityExtensions } from '../types';
+import type { GridDensity, GridDensityOverrides } from '../density';
 /**
  * 方案管理 API 接口
  *
@@ -153,8 +154,9 @@ export interface GridPlusContextValue extends SchemeManagementAPI {
      * 将当前列配置应用为全局默认（管理员操作）
      * @param gridId 表格标识
      * @param schemeId 源方案ID（可选，不传则使用当前激活的方案）
+     * @returns 应用后的全局方案 ID（useSchemeManager 返回；其他实现可不返回）
      */
-    applySchemeToGlobal?: (gridId: string, schemeId?: string) => Promise<void>;
+    applySchemeToGlobal?: (gridId: string, schemeId?: string) => Promise<string | void>;
     /**
      * 重置当前用户配置，回退到全局配置
      * @param gridId 表格标识
@@ -184,5 +186,14 @@ export interface GridPlusContextValue extends SchemeManagementAPI {
      * 来自后端 ABP 配置，用于 AgGridPlus 根据 entityType 自动注入扩展列
      */
     hostEntityExtensions?: HostEntityExtensions;
+    /**
+     * 表格密度档位：行高、表头高、字号、单元格 padding 由它派生。
+     * 不传则保持出厂外观（字号 12、行高 30、表头 25），页面 `rowHeight` / `headerHeight` / `theme` 仍可覆盖。
+     */
+    density?: GridDensity;
+    /** 自定义三档数值，只写要改的字段，其余沿用规范值。 */
+    densityValues?: GridDensityOverrides;
+    /** 列设置里切换密度时回调；不传则列设置不显示密度入口。由宿主/Provider 接管密度状态。 */
+    onDensityChange?: (density: GridDensity) => void;
 }
 export declare const GridPlusContext: React.Context<GridPlusContextValue>;

package/dist/esm/ag-grid-plus/context/queryFormContext.d.ts

@@ -14,6 +14,8 @@ export interface QueryFormContextValue {
     currentQueryOrder?: string[];
     /** 更新查询项顺序 */
     updateQueryOrder?: (order: string[]) => void;
+    /** 读取查询区当前条件值（已去空、可持久化），用于把条件值存进查询方案 */
+    getQueryValues?: () => Record<string, any>;
 }
 export declare const QueryFormContext: React.Context<QueryFormContextValue>;
 /** 读取查询表单上下文。@author nokecy */

package/dist/esm/ag-grid-plus/context/useSchemeDataFlow.js

@@ -81,6 +81,14 @@ export function useSchemeSource(gridKey, schemeData) {
       return s.id === currentQuerySchemeId;
     });
     var isUsingGlobalQueryFallback = false;
+
+    // 用户自己设为默认的查询方案：没有显式选择时进入页面自动应用，优先于全局方案
+    if (!currentQueryScheme && querySchemeList.length > 0) {
+      var userDefault = querySchemeList.find(function (s) {
+        return s.isDefault && !s.isGlobal;
+      });
+      if (userDefault) currentQueryScheme = userDefault;
+    }
     if (!currentQueryScheme && querySchemeList.length > 0) {
       var globalQuerySchemes = querySchemeList.filter(function (s) {
         return s.isGlobal === true;

package/dist/esm/ag-grid-plus/density.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 表格密度：三档数值由 Provider 注入，页面不自设行高、表头高（DESIGN.md §2）。
+ * @author nokecy
+ */
+export type GridDensity = 'comfort' | 'compact' | 'dense';
+export interface GridDensityValues {
+    /** 表格行高 */
+    rowHeight: number;
+    /** 表头高 */
+    headerHeight: number;
+    /** 正文与表头字号 */
+    fontSize: number;
+    /** 单元格上下内边距 */
+    paddingBlock: number;
+    /** 单元格左右内边距 */
+    paddingInline: number;
+}
+/** 规范三档：行高 40/32/28，表头 40/36/32，字号 14/13/12，padding 9·12 / 5·10 / 4·8。 */
+export declare const GRID_DENSITY_PRESETS: Record<GridDensity, GridDensityValues>;
+/** 自定义三档数值：只需写要改的字段，其余沿用规范值。 */
+export type GridDensityOverrides = Partial<Record<GridDensity, Partial<GridDensityValues>>>;
+/**
+ * 解析密度数值。没有注入 density 时返回 undefined，调用方保持出厂外观不变。
+ */
+export declare function resolveGridDensity(density?: GridDensity, overrides?: GridDensityOverrides): GridDensityValues | undefined;

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

@@ -0,0 +1,45 @@
+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 ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/**
+ * 表格密度：三档数值由 Provider 注入，页面不自设行高、表头高（DESIGN.md §2）。
+ * @author nokecy
+ */
+
+/** 规范三档：行高 40/32/28，表头 40/36/32，字号 14/13/12，padding 9·12 / 5·10 / 4·8。 */
+export var GRID_DENSITY_PRESETS = {
+  comfort: {
+    rowHeight: 40,
+    headerHeight: 40,
+    fontSize: 14,
+    paddingBlock: 9,
+    paddingInline: 12
+  },
+  compact: {
+    rowHeight: 32,
+    headerHeight: 36,
+    fontSize: 13,
+    paddingBlock: 5,
+    paddingInline: 10
+  },
+  dense: {
+    rowHeight: 28,
+    headerHeight: 32,
+    fontSize: 12,
+    paddingBlock: 4,
+    paddingInline: 8
+  }
+};
+
+/** 自定义三档数值：只需写要改的字段，其余沿用规范值。 */
+
+/**
+ * 解析密度数值。没有注入 density 时返回 undefined，调用方保持出厂外观不变。
+ */
+export function resolveGridDensity(density, overrides) {
+  if (!density || !GRID_DENSITY_PRESETS[density]) return undefined;
+  return _objectSpread(_objectSpread({}, GRID_DENSITY_PRESETS[density]), overrides === null || overrides === void 0 ? void 0 : overrides[density]);
+}

package/dist/esm/ag-grid-plus/index.d.ts

@@ -16,3 +16,4 @@ export type { LocalStorageAdapterConfig } from "./shared/storage/localStorageAda
 export type { GlobalConfigPermissions } from "./shared/permissions/globalConfigPermissions";
 export type { EntityExtensionField, EntityExtensionConfig, HostEntityExtensions } from "./types";
 export { fieldToColumnDef, getEntityExtensionColumns } from "./utils/entityExtensionColumns";
+export { setAgGridLicenseKey } from "./utils/agGridLicenseNotice";

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

@@ -20,5 +20,8 @@ export { BackendApiSchemeAdapter } from "./shared/storage/backendApiAdapter";
 // 实体扩展列工具函数 @author nokecy
 export { fieldToColumnDef, getEntityExtensionColumns } from "./utils/entityExtensionColumns";
 
+// 正式 AG Grid Enterprise 授权入口：宿主注入 key 后组件库不再静默试用提示。
+export { setAgGridLicenseKey } from "./utils/agGridLicenseNotice";
+
 // 注意: 旧的查询方案管理功能已废弃
 // 相关导出已移除，请使用集中式方案管理 API (useSchemeManager/useGridSchemes)

package/dist/esm/ag-grid-plus/index.less

@@ -1,3 +1,39 @@
+.qc-table-container {
+  position: relative;
+}
+
+// 刷新时表里已有数据：不盖遮罩，只在表格顶部给一条 2px 的流动加载条
+.qc-grid-busy-bar {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 2px;
+  z-index: 3;
+  pointer-events: none;
+  overflow: hidden;
+
+  > span {
+    display: block;
+    height: 100%;
+    width: 30%;
+    animation: qc-grid-busy-slide 1.2s ease-in-out infinite;
+  }
+}
+
+@keyframes qc-grid-busy-slide {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(340%); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .qc-grid-busy-bar > span {
+    width: 100%;
+    animation: none;
+    opacity: 0.6;
+  }
+}
+
 .grid-spin {
   height: 100%;
 
@@ -49,6 +85,13 @@
   text-align: right !important;
 }
 
+// AG Grid Enterprise 试用水印：组件库不内置 license key（授权由宿主通过 setAgGridLicenseKey 注入），
+// 未注入时 AG Grid 会在表格右下角叠一层 .ag-watermark。这里统一关闭，宿主不必各自处理。
+// 限定在组件库表格容器内，不影响页面上其他独立接入的 AG Grid 实例。
+.qc-table-container .ag-watermark {
+  display: none !important;
+}
+
 // 空态浮层里的「重试」「新建」「清空筛选」要能点：AG-Grid 给 .ag-overlay 设了 pointer-events: none，
 // 只给加载浮层放开，空态浮层里的按钮因此点不到。只放开可交互元素，空白处仍穿透到表格。@author nokecy
 .ag-overlay-no-rows-wrapper :is(button, a, input, [role='button']) {

package/dist/esm/ag-grid-plus/interface.d.ts

@@ -4,8 +4,24 @@ import React, { CSSProperties, ReactNode } from "react";
 import type { GridPlusError } from "./errors/index";
 import type { EmptyStateTexts } from "./utils/emptyState";
 import type { DateQueryPrecisionResolver } from "./queryForm/datePrecision";
+/** 当前分页状态；页码 1-based。 */
+interface GridPagination {
+    current: number;
+    pageSize: number;
+    /** 总条数；request 模式下首次请求返回前为 0 */
+    total: number;
+}
 interface GridRef {
     onRefresh: () => void;
+    /**
+     * 跳到第 n 页（1-based），按总页数收口；页码变化时自动重新请求。
+     * 已在该页时不重复请求，需要重取请用 onRefresh。
+     */
+    goToPage: (page: number) => void;
+    /** 回到第 1 页，等价 goToPage(1)。 */
+    resetPage: () => void;
+    /** 读取最新分页状态（快照，不随后续翻页变化）。 */
+    getPagination: () => GridPagination;
 }
 interface GridProps extends AgGridReactProps {
     /**
@@ -86,6 +102,23 @@ interface GridProps extends AgGridReactProps {
      */
     pageSize?: number;
     hidePagination?: boolean;
+    /**
+     * 分页器的页码跳转，默认 false（保持原行为）。DESIGN.md §7.3 要求列表带页码跳转，需要的页面显式开启。
+     * @author nokecy
+     */
+    showQuickJumper?: boolean;
+    /**
+     * 分页器的每页条数切换。不传走 antd 缺省（总数 > 50 才出现）；传 true 强制显示。
+     * @author nokecy
+     */
+    showSizeChanger?: boolean;
+    /**
+     * 列头筛选按钮是否显示，默认 true（保持原行为）。传 false 全局收起漏斗，列的 `filter` 不变，
+     * 查询区仍可按这些列查询；需要个别列保留时在该列写 `suppressHeaderFilterButton: false`。
+     * 页面传入的 `defaultColDef` 与内置默认合并（页面优先），不再被覆盖。
+     * @author nokecy
+     */
+    headerFilter?: boolean;
     gridRef?: React.Ref<GridRef | undefined>;
     /**
      * 选中行变化回调函数
@@ -97,6 +130,11 @@ interface GridProps extends AgGridReactProps {
      * @author nokecy
      */
     onQueryValuesChange?: (values: Record<string, any>) => void;
+    /**
+     * 在表头上拖拽列宽、列序后自动记忆到列方案（需要 gridKey），不必进「列方案管理」保存；默认开启。
+     * 全局方案不会被改写，会在个人方案上叠加。设为 false 回到必须手动保存。
+     */
+    autoRememberColumns?: boolean;
     /**
      * 错误处理回调函数
      * 当组件发生错误时调用，可用于自定义错误处理逻辑
@@ -147,6 +185,25 @@ interface GridProps extends AgGridReactProps {
      * @author nokecy
      */
     entityType?: string;
+    /**
+     * 跨页勾选（DESIGN.md §7.4）：翻页保留已勾选的行，回到该页时自动重新勾上。
+     * 开启后 `onSelectedRowsChange` 收到的是所有页的并集。默认 false。
+     * @author nokecy
+     */
+    crossPageSelection?: boolean;
+    /** 跨页勾选变化回调：已选总数、不在当前页的数量，以及清除入口（底部批量选择条用）。 */
+    onCrossPageSelectionChange?: (info: {
+        rows: any[];
+        count: number;
+        outsideCurrentPage: number;
+        clear: () => void;
+    }) => void;
+    /**
+     * 数字千分位、空值显示「—」的出厂格式。列上自己写了 `valueFormatter` 的不受影响；
+     * 传 false 整体关闭。默认 true。
+     * @author nokecy
+     */
+    defaultValueFormat?: boolean;
 }
 interface AgGridColumnPropsClone extends ColDef {
     /**
@@ -205,4 +262,4 @@ interface AgGridColumnPropsClone extends ColDef {
     calculateType?: "sum" | "avg" | "standardDeviation" | false;
 }
 declare function AgGridColumn(props: AgGridColumnPropsClone | ColGroupDef): React.JSX.Element;
-export { GridProps, AgGridColumn, GridRef, AgGridColumnPropsClone };
+export { GridProps, AgGridColumn, GridRef, GridPagination, AgGridColumnPropsClone };

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

@@ -8,6 +8,8 @@ import React from "react";
 // 注意: QueryStorageAdapter 和 ColumnStorageAdapter 已废弃
 // 请使用集中式方案管理 API
 
+/** 当前分页状态；页码 1-based。 */
+
 //column的行内传参
 import { jsx as _jsx } from "react/jsx-runtime";
 function AgGridColumn(props) {

package/dist/esm/ag-grid-plus/queryForm/index.d.ts

@@ -1,5 +1,6 @@
 import { ColDef, ColumnState, GridApi } from 'ag-grid-community';
 import React from 'react';
+import { type QueryFormApi } from './queryValues';
 import './index.less';
 /** 查询区初始化兜底：requestAnimationFrame 迟迟不触发时，最迟这么久后通知首查（毫秒）。@author nokecy */
 export declare const INIT_FALLBACK_DELAY = 300;
@@ -16,5 +17,15 @@ declare const FormRender: (props: {
     onInit?: ((defaultValues: any) => void) | undefined;
     /** 查询条件值变化（输入、默认值落位、重置）时回调，参数为当前条件快照；不触发查询。@author nokecy */
     onValuesChange?: ((values: Record<string, any>) => void) | undefined;
+    /** 当前应用的查询方案：名称显示在查询区；方案带条件值时，方案变化会把值落到查询区并查询。 */
+    scheme?: {
+        id: string;
+        name: string;
+        values?: Record<string, any> | undefined;
+    } | undefined;
+    /** 点「重置」时通知宿主取消当前应用的查询方案（只取消应用状态，不动已保存方案）。 */
+    onResetScheme?: (() => void) | undefined;
+    /** 暴露查询区操作句柄（读取当前条件值），供查询方案管理保存条件值。 */
+    apiRef?: React.MutableRefObject<QueryFormApi | null> | undefined;
 }) => React.JSX.Element;
 export default FormRender;

package/dist/esm/ag-grid-plus/queryForm/index.js

@@ -16,7 +16,8 @@ import { createSchemaField } from '@nokecy/formily-react';
 import { Button, theme } from 'antd';
 import classNames from 'classnames';
 import React, { useEffect, useMemo, useRef, useState } from 'react';
-import QueryForm from "./queryForm";
+import QueryForm, { QueryFormMetaContext } from "./queryForm";
+import { reviveQueryValues, serializeQueryValues } from "./queryValues";
 import { queryFormSchemaKey } from "./schemaKey";
 import { resolveQueryColumns } from "./queryColumns";
 import BoolSelect from "../_utils/boolSelect";
@@ -65,6 +66,26 @@ var FormRender = function FormRender(props) {
       return form.unsubscribe(id);
     };
   }, [form]);
+
+  // 日期类查询项在方案里以字符串存放，应用时要还原成 dayjs。@author nokecy
+  var dateFieldsRef = useRef(new Set());
+  var initNotifiedRef = useRef(false);
+  var onQueryRef = useRef(props.onQuery);
+  onQueryRef.current = props.onQuery;
+  // onReset 被 schema 的组件属性捕获，只在 schema 变化时更新，回调必须走 ref 才不会拿到旧闭包。
+  var onResetSchemeRef = useRef(props.onResetScheme);
+  onResetSchemeRef.current = props.onResetScheme;
+  useEffect(function () {
+    if (!props.apiRef) return;
+    props.apiRef.current = {
+      getValues: function getValues() {
+        return serializeQueryValues(form.values);
+      }
+    };
+    return function () {
+      props.apiRef.current = null;
+    };
+  }, [form, props.apiRef]);
   var SchemaField = useMemo(function () {
     return createSchemaField({
       components: {
@@ -85,11 +106,14 @@ var FormRender = function FormRender(props) {
     onQuery && onQuery(form.values);
   };
   var onReset = function onReset() {
+    var _onResetSchemeRef$cur, _onQueryRef$current;
     // 使用 forceClear: true 强制清空所有字段，包括有默认值的字段
     form.reset('*', {
       forceClear: true
     });
-    onQuery({});
+    // 清空即恢复全量（§8）：先取消方案，再按空条件只查一次；方案取消不会触发查询。
+    (_onResetSchemeRef$cur = onResetSchemeRef.current) === null || _onResetSchemeRef$cur === void 0 || _onResetSchemeRef$cur.call(onResetSchemeRef);
+    (_onQueryRef$current = onQueryRef.current) === null || _onQueryRef$current === void 0 || _onQueryRef$current.call(onQueryRef, {});
   };
   var getComponent = function getComponent(colDef) {
     var component = colDef.searchComponent ? colDef.searchComponent : undefined;
@@ -144,6 +168,7 @@ var FormRender = function FormRender(props) {
       var headerName = (_colDef$searchTitle = colDef.searchTitle) !== null && _colDef$searchTitle !== void 0 ? _colDef$searchTitle : colDef.headerName;
       //表单自定义组件
       var component = getComponent(colDef);
+      if (typeof component === 'string' && component.includes('DatePicker')) dateFieldsRef.current.add(name);
       if (colDef.filter != false) {
         var _colDef$searchCompone, _colDef$searchCompone2, _colDef$searchCompone3, _colDef$searchCompone4;
         // 为多选下拉框添加maxTagCount配置
@@ -239,6 +264,7 @@ var FormRender = function FormRender(props) {
       var notifyInit = function notifyInit() {
         if (initialized) return;
         initialized = true;
+        initNotifiedRef.current = true;
         props.onInit && props.onInit(form.values);
       };
       requestAnimationFrame(function () {
@@ -247,19 +273,45 @@ var FormRender = function FormRender(props) {
       setTimeout(notifyInit, INIT_FALLBACK_DELAY);
     }
   }, [schemaKey, defaultRows, props.defaultExpand]);
+
+  // 方案切换（含进入页面时自动带入默认方案）：须在查询项 schema 生成之后，才知道哪些是日期字段；把方案里的条件值落到查询区，已初始化则立即查询。
+  var appliedSchemeIdRef = useRef(undefined);
+  var scheme = props.scheme;
+  useEffect(function () {
+    var _onQueryRef$current2;
+    // 方案被取消后清掉记录，用户再选同一个方案时才会重新应用。
+    if (!(scheme !== null && scheme !== void 0 && scheme.id)) {
+      appliedSchemeIdRef.current = undefined;
+      return;
+    }
+    if (appliedSchemeIdRef.current === scheme.id) return;
+    appliedSchemeIdRef.current = scheme.id;
+    var saved = scheme.values;
+    if (!saved || Object.keys(saved).length === 0) return;
+    form.reset('*', {
+      forceClear: true
+    });
+    form.setValues(reviveQueryValues(saved, dateFieldsRef.current));
+    if (initNotifiedRef.current) (_onQueryRef$current2 = onQueryRef.current) === null || _onQueryRef$current2 === void 0 || _onQueryRef$current2.call(onQueryRef, _objectSpread({}, form.values));
+  }, [scheme === null || scheme === void 0 ? void 0 : scheme.id, form]);
   return /*#__PURE__*/_jsx("div", {
     className: classNames(className, "ag-grid-table-search ag-grid-table-search-query-filter"),
     style: {
       backgroundColor: token.colorBgContainer
     },
-    children: /*#__PURE__*/_jsx(Form, {
-      form: form,
-      labelWidth: 120,
-      labelWrap: false,
-      feedbackLayout: "none",
-      onAutoSubmit: onSubmit,
-      children: /*#__PURE__*/_jsx(SchemaField, {
-        schema: schema
+    children: /*#__PURE__*/_jsx(QueryFormMetaContext.Provider, {
+      value: {
+        schemeName: scheme === null || scheme === void 0 ? void 0 : scheme.name
+      },
+      children: /*#__PURE__*/_jsx(Form, {
+        form: form,
+        labelWidth: 120,
+        labelWrap: false,
+        feedbackLayout: "none",
+        onAutoSubmit: onSubmit,
+        children: /*#__PURE__*/_jsx(SchemaField, {
+          schema: schema
+        })
       })
     })
   });

package/dist/esm/ag-grid-plus/queryForm/queryForm.d.ts

@@ -1,3 +1,13 @@
 import React from 'react';
+/** 查询区外显条件数的上限（DESIGN.md §8）。 */
+export declare const QUERY_MAX_COLUMNS = 8;
+/** 单个查询项占的最小宽度（px），外显条数 = floor(可用宽度 / 它)，封顶 QUERY_MAX_COLUMNS。 */
+export declare const QUERY_ITEM_WIDTH = 240;
+/** 折叠时外显的条件数：按钮区在表格之外，不再占一格。 */
+export declare const getQueryCapacity: (maxRows: number, columns: number) => number;
+/** 查询区当前应用的方案名等元信息，经 context 传给查询区，不走 schema。 */
+export declare const QueryFormMetaContext: React.Context<{
+    schemeName?: string | undefined;
+}>;
 declare const QueryForm: React.MemoExoticComponent<import("@nokecy/formily-react").ReactFC<any>>;
 export default QueryForm;

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

@@ -2,40 +2,44 @@ import { ClearOutlined, DownOutlined, SearchOutlined } from "@ant-design/icons";
 import { FormButtonGroup, FormGrid, Submit } from "@nokecy/formily-antd";
 import { observer } from "@nokecy/formily-react";
 import { Button } from "antd";
-import React, { useMemo, Fragment } from 'react';
+import React, { useContext, useMemo, Fragment } from 'react';
+
+/** 查询区外显条件数的上限（DESIGN.md §8）。 */
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment as _Fragment } from "react/jsx-runtime";
+export var QUERY_MAX_COLUMNS = 8;
+/** 单个查询项占的最小宽度（px），外显条数 = floor(可用宽度 / 它)，封顶 QUERY_MAX_COLUMNS。 */
+export var QUERY_ITEM_WIDTH = 240;
+
+/** 折叠时外显的条件数：按钮区在表格之外，不再占一格。 */
+export var getQueryCapacity = function getQueryCapacity(maxRows, columns) {
+  return Math.max(1, maxRows * Math.max(1, columns));
+};
+
+/** 查询区当前应用的方案名等元信息，经 context 传给查询区，不走 schema。 */
+export var QueryFormMetaContext = /*#__PURE__*/React.createContext({});
 var useCollapseGrid = function useCollapseGrid(maxRows, defaultExpand) {
   var grid = useMemo(function () {
     return FormGrid.createFormGrid({
-      maxColumns: 5,
-      // 查询项含固定标签和输入框，操作区含查询、重置、折叠入口。@author nokecy
-      minWidth: 240,
-      maxWidth: 240,
+      // 外显条数随宽度增长，宽屏不再卡在 4 个。@author nokecy
+      maxColumns: QUERY_MAX_COLUMNS,
+      minWidth: QUERY_ITEM_WIDTH,
+      maxWidth: QUERY_ITEM_WIDTH,
       maxRows: defaultExpand ? Infinity : maxRows,
       shouldVisible: function shouldVisible(node, grid) {
         // 展开状态时，显示所有元素
         if (grid.maxRows === Infinity) return true;
-
-        // 对于按钮列（最后一个元素），总是显示
-        if (node.index === grid.childSize - 1) {
-          return true;
-        }
-
-        // 所有查询项均占一格；按当前响应式列数为末行按钮预留一格。
-        // 单列窄屏至少保留一个查询项，按钮自然换到下一行。@author nokecy
-        var capacity = Math.max(1, maxRows * Math.max(1, grid.columns) - 1);
-        return node.index !== undefined && node.index < capacity;
+        // 查询、重置按钮在表格之外，表格里只有查询项，按当前响应式列数计算首行外显。
+        return node.index !== undefined && node.index < getQueryCapacity(maxRows, grid.columns);
       }
     });
   }, [maxRows, defaultExpand] // 添加依赖项
   );
   var expanded = grid.maxRows === Infinity;
-  // 操作区展开时会填满余列，不能把它上一次的跨度用来判断是否还有隐藏条件。
   // 根据完整查询项数量判断，折叠、外部重渲染和容器变宽都不会丢失入口。@author nokecy
-  var capacity = Math.max(1, maxRows * Math.max(1, grid.columns) - 1);
-  var collapsible = Math.max(0, grid.childSize - 1) > capacity;
+  var capacity = getQueryCapacity(maxRows, grid.columns);
+  var collapsible = grid.childSize > capacity;
   var toggle = function toggle() {
     if (grid.maxRows === Infinity) {
       grid.maxRows = maxRows;
@@ -93,23 +97,57 @@ var QueryForm = observer(function (props) {
       })
     });
   };
+  var _useContext = useContext(QueryFormMetaContext),
+    schemeName = _useContext.schemeName;
   var renderButtonGroup = function renderButtonGroup() {
     return /*#__PURE__*/_jsx(Fragment, {
       children: /*#__PURE__*/_jsxs(FormButtonGroup, {
         align: "right",
-        children: [renderActions(), collapsible ? renderExpanded() : null]
+        children: [schemeName ? /*#__PURE__*/_jsxs("span", {
+          "data-query-scheme-name": true,
+          title: schemeName,
+          style: {
+            maxWidth: 160,
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap"
+          },
+          children: ["\u65B9\u6848\uFF1A", schemeName]
+        }) : null, renderActions(), collapsible ? renderExpanded() : null]
       })
     });
   };
-  return /*#__PURE__*/_jsxs(FormGrid, {
-    grid: grid,
-    colWrap: true,
-    strictAutoFit: true,
-    children: [props.children, /*#__PURE__*/_jsx(FormGrid.GridColumn, {
-      gridSpan: expanded || !collapsible ? -1 : 1,
+
+  // 按钮区放在表格之外、固定在首行右侧：展开/收起只改变条件行数，不改变按钮位置（§8）。窄屏时换到条件下方。
+  return /*#__PURE__*/_jsxs("div", {
+    "data-query-form": true,
+    style: {
+      display: "flex",
+      flexWrap: "wrap",
+      alignItems: "flex-start",
+      gap: 8,
+      width: "100%"
+    },
+    children: [/*#__PURE__*/_jsx("div", {
+      style: {
+        flex: "1 1 480px",
+        minWidth: 0
+      },
+      children: /*#__PURE__*/_jsx(FormGrid, {
+        grid: grid,
+        colWrap: true,
+        strictAutoFit: true,
+        children: props.children
+      })
+    }), /*#__PURE__*/_jsx("div", {
+      "data-query-actions": true,
       style: {
+        flex: "0 0 auto",
         display: "flex",
-        justifyContent: "right"
+        alignItems: "center",
+        justifyContent: "flex-end",
+        minHeight: 32,
+        marginInlineStart: "auto"
       },
       children: renderButtonGroup()
     })]

package/dist/esm/ag-grid-plus/queryForm/queryValues.d.ts

@@ -0,0 +1,9 @@
+/** 去掉空值并转成可持久化的普通对象（dayjs 经 toJSON 变为 ISO 字符串）。 */
+export declare function serializeQueryValues(values: Record<string, any> | undefined): Record<string, any>;
+/** 应用方案时还原值：日期字段（含区间）从字符串转回 dayjs，其余原样。 */
+export declare function reviveQueryValues(values: Record<string, any> | undefined, dateFields: ReadonlySet<string>): Record<string, any>;
+/** 查询区向外暴露的操作句柄，供查询方案管理读写条件值。 */
+export interface QueryFormApi {
+    /** 当前条件值（已去空、可持久化） */
+    getValues: () => Record<string, any>;
+}

package/dist/esm/ag-grid-plus/queryForm/queryValues.js

@@ -0,0 +1,54 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+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; }
+import dayjs from 'dayjs';
+
+/**
+ * 查询区条件值与查询方案之间的序列化：
+ * 保存时只留有意义的值并转成可 JSON 化的形态，应用时把日期字段还原回 dayjs。
+ * 存的是查询区表单值，不是列头筛选。@author nokecy
+ */
+
+var isEmptyValue = function isEmptyValue(value) {
+  return value === undefined || value === null || value === '' || Array.isArray(value) && value.every(isEmptyValue);
+};
+
+/** 去掉空值并转成可持久化的普通对象（dayjs 经 toJSON 变为 ISO 字符串）。 */
+export function serializeQueryValues(values) {
+  var result = {};
+  Object.entries(values !== null && values !== void 0 ? values : {}).forEach(function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 2),
+      name = _ref2[0],
+      value = _ref2[1];
+    if (isEmptyValue(value)) return;
+    var plain = JSON.parse(JSON.stringify(value));
+    if (!isEmptyValue(plain)) result[name] = plain;
+  });
+  return result;
+}
+var reviveDate = function reviveDate(value) {
+  if (typeof value !== 'string' && typeof value !== 'number') return value;
+  var parsed = dayjs(value);
+  return parsed.isValid() ? parsed : value;
+};
+
+/** 应用方案时还原值：日期字段（含区间）从字符串转回 dayjs，其余原样。 */
+export function reviveQueryValues(values, dateFields) {
+  var result = {};
+  Object.entries(values !== null && values !== void 0 ? values : {}).forEach(function (_ref3) {
+    var _ref4 = _slicedToArray(_ref3, 2),
+      name = _ref4[0],
+      value = _ref4[1];
+    if (!dateFields.has(name)) {
+      result[name] = value;
+    } else {
+      result[name] = Array.isArray(value) ? value.map(reviveDate) : reviveDate(value);
+    }
+  });
+  return result;
+}
+
+/** 查询区向外暴露的操作句柄，供查询方案管理读写条件值。 */