@ant-design/pro-components 3.1.12-0 → 3.1.13-0

package/es/utils/useEditableMap/index.js

@@ -1,82 +1,140 @@
 import { get, useControlledState } from '@rc-component/util';
 import { message } from 'antd';
-import { useCallback, useMemo, useRef } from 'react';
+import set from 'lodash-es/set';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { useRefFunction } from '..';
 import { useIntl } from "../../provider";
 import { defaultActionRender, recordKeyToString } from "../useEditableArray";
 
 /**
- * 显示警告信息
- * @param messageStr
+ * 把 RecordKey 规范成统一的 string 形式 key（用于 Map 索引 / Set 成员判断）。
+ * RecordKey = React.Key | React.Key[]，统一转 string 避免 number/string 不一致。
+ */
+const normalizeKeyToString = recordKey => String(recordKeyToString(recordKey));
+
+/**
+ * 把 RecordKey 转成 lodash set/get 用的路径数组，统一为 string 段。
+ * 例如：'name' → ['name']，['address','city'] → ['address','city']，123 → ['123']
+ */
+const recordKeyToPath = recordKey => {
+  return Array.isArray(recordKey) ? recordKey.map(segment => String(segment)) : [String(recordKey)];
+};
+
+/**
+ * 显示警告信息（仅在 single 模式拦截重复编辑时调用）。
+ * NOTE: 使用 antd `message` 静态方法在 antd 5 下无法消费 ConfigProvider 的主题，
+ *       但替换为 `App.useApp()` 需要业务方在外层包裹 `<App />`，会有破坏性。
+ *       这里保留静态方法兼容历史调用，建议消费方自行包裹 `<App />` 以获得正确主题。
  */
 const warning = messageStr => {
-  return message.warning(messageStr);
+  message.warning(messageStr);
 };
+
 /**
- * 使用map 来删除数据，性能一般 但是准确率比较高
- *
- * @param params
- * @param action
+ * 按 recordKey 路径深度合并到 data 上：
+ * - 顶层 key（如 'name'）：等价于 `{ ...data, ...{ name: row.name } }`，但只取该路径
+ * - 嵌套数组 key（如 ['address','city']）：仅更新 data.address.city，不会把 data.address 整个替换掉
+ *   这避免了之前 `{ ...data, ...row }` 顶层合并导致兄弟字段（如 data.address.zipcode）被丢失的问题。
  */
 function editableRowByKey({
   data,
-  row
+  row,
+  key
 }) {
-  return {
-    ...data,
-    ...row
-  };
+  const path = recordKeyToPath(key);
+  const value = get(row, path);
+  // 当 row 路径上没有目标值时（典型场景：受控外部 form 直接 setFieldsValue），
+  // 退回到顶层合并语义，保持向后兼容。
+  if (value === undefined) {
+    return {
+      ...data,
+      ...row
+    };
+  }
+  // lodash set 会原地修改对象，先做浅拷贝避免污染调用方的引用。
+  return set({
+    ...data
+  }, path, value);
 }
 /**
- * 一个方便的hooks 用于维护编辑的状态
+ * 单条记录场景下的"行内编辑"状态管理 hook（与 useEditableArray 平行设计，
+ * useEditableArray 服务于数组场景如 ProTable，本 hook 服务于 ProDescriptions 等单记录场景）。
+ *
+ * 设计要点：
+ * 1. `type='single'`（默认）下，已有任意字段处于编辑态时，再次发起 startEditable 会被拒绝并弹 toast，
+ *    用户必须先 cancel/save 当前编辑行才能编辑别的字段。这是产品刻意设计（受测试 `📝 单行模式下应该阻止同时编辑多个字段` 锁定），
+ *    与某些同类组件"切换式"行为不同；如需切换，需显式传 `type='multiple'` 并自行约束最多一行。
+ * 2. 多行模式（`type='multiple'`）支持任意多个字段同时编辑，每个字段进入编辑态前的快照按 key 存到 `preEditRowRefs` Map 中。
  *
  * @param props
  */
 export function useEditableMap(props) {
   /**
-   * 点击开始编辑之前的保存数据用的
+   * 多行编辑场景下，按 recordKey 缓存每一行进入编辑前的快照（允许 null 表示新建行）。
+   * NOTE: 旧版同时维护了 `preEditRowRef`（单引用），但在 multiple 模式下会被新行覆盖，
+   *       导致取消时还原成别人的数据，已删除。actionRender 透传 `preEditRowRef` 时按当前 key
+   *       从 Map 取最新快照临时构造一个 ref，保证 defaultActionRender 拿到的是正确的快照。
    */
-  const preEditRowRef = useRef(null);
   const preEditRowRefs = useRef(new Map());
-  const editableType = props.type || 'single';
+
+  // 用 ?? 而非 ||，更准确表达"undefined 时取默认"的语义（type 不会传 falsy 但合法的值）
+  const editableType = props.type ?? 'single';
 
   // Internationalization
   const intl = useIntl();
   const [editableKeys, setEditableRowKeysInner] = useControlledState([], props.editableKeys);
+
+  /**
+   * 影子 ref，存放当前最新的 editableKeys。
+   * NOTE: 配合 useRefFunction 使用——后者保证函数引用稳定但闭包永远是渲染时最新的，
+   *       但我们需要"调用时最新"（例如 onSave 内连续调用 cancelEditable 时 React 还没 commit），
+   *       所以用 ref 保留同步影子。
+   */
+  const editableKeysRef = useRef(editableKeys);
+  useEffect(() => {
+    editableKeysRef.current = editableKeys;
+  }, [editableKeys]);
+
+  /**
+   * 把 onChange/dataSource 锁进 ref，避免每次 prop 变化都让 setEditableRowKeys 重建引用。
+   * 同时修正 onChange 第二参数语义：旧版直接传 props.dataSource（整条记录），
+   * 现在按 next keys 取出真正在编辑的字段值数组（与 useEditableArray 行为对齐）。
+   */
+  const triggerOnChange = useRefFunction(nextKeys => {
+    if (!props.onChange) return;
+    const editingRows = nextKeys.map(key => get(props.dataSource, [String(key)]));
+    props.onChange(nextKeys, editingRows);
+  });
   const setEditableRowKeys = useCallback(updater => {
     setEditableRowKeysInner(prev => {
-      const next = typeof updater === 'function' ? updater(prev) : updater;
-      props?.onChange?.(next, props.dataSource);
+      let next = typeof updater === 'function' ? updater(prev) : updater;
+      // single 模式下统一在入口截断，保证 state 与 editableKeysSet 一致。
+      // 旧版只在 editableKeysSet 里 slice(0,1)，导致 state 里残留多余 key 但 isEditable 看不到。
+      if (editableType === 'single' && next.length > 1) {
+        next = next.slice(0, 1);
+      }
+      triggerOnChange(next);
       return next;
     });
-  }, [props.onChange, props.dataSource]);
+  }, [setEditableRowKeysInner, triggerOnChange, editableType]);
 
   /** 一个用来标志的set 提供了方便的 api 来去重什么的 */
   const editableKeysSet = useMemo(() => {
-    const keys = editableType === 'single' ? editableKeys?.slice(0, 1) || [] : editableKeys || [];
-    return new Set(keys.map(key => String(key)));
-  }, [editableKeys, editableType]);
+    return new Set((editableKeys || []).map(key => String(key)));
+  }, [editableKeys]);
 
-  /**
-   * 检查 key 是否在编辑列表中
-   * 使用 editableKeysSet 进行快速查找，性能更好
-   */
-  const checkKeyInEditableList = useRefFunction(recordKey => {
-    const keyStr = String(recordKeyToString(recordKey));
-    return editableKeysSet.has(keyStr);
+  /** 这行是不是编辑状态。useRefFunction 保证引用稳定且闭包永远最新。 */
+  const isEditable = useRefFunction(recordKey => {
+    return editableKeysSet.has(normalizeKeyToString(recordKey));
   });
 
-  /** 这行是不是编辑状态 */
-  const isEditable = useCallback(recordKey => {
-    return checkKeyInEditableList(recordKey);
-  }, [checkKeyInEditableList]);
-
   /**
-   * 验证是否可以开始编辑
+   * 验证是否可以开始编辑（仅 single 模式下生效）。
+   * 用 editableKeysRef 读最新值，避免连续调用时拿到陈旧快照。
    */
   const validateCanStartEdit = useRefFunction(() => {
-    // 如果是单行模式，检查是否已有编辑中的行
-    if (editableType === 'single' && editableKeys && editableKeys.length > 0) {
+    const currentKeys = editableKeysRef.current;
+    if (editableType === 'single' && currentKeys && currentKeys.length > 0) {
       warning(props.onlyOneLineEditorAlertMessage || intl.getMessage('editableTable.onlyOneLineEditor', '只能同时编辑一行'));
       return false;
     }
@@ -87,26 +145,24 @@ export function useEditableMap(props) {
    * 进入编辑状态
    *
    * @param recordKey
-   * @param recordValue
+   * @param recordValue 显式传入的"编辑前快照"，未传则从 dataSource 按 key 路径取
    */
   const startEditable = useRefFunction((recordKey, recordValue) => {
-    // 验证是否可以开始编辑
     if (!validateCanStartEdit()) {
       return false;
     }
-    const keyStr = String(recordKeyToString(recordKey));
+    const keyStr = normalizeKeyToString(recordKey);
 
-    // 检查是否已经在编辑列表中，避免重复添加
-    if (checkKeyInEditableList(recordKey)) {
+    // 已经在编辑列表中，幂等返回成功
+    if (isEditable(recordKey)) {
       return true;
     }
 
-    // 保存编辑前的数据
-    preEditRowRef.current = recordValue ?? get(props.dataSource, Array.isArray(recordKey) ? recordKey : [recordKey]) ?? null;
-    preEditRowRefs.current.set(String(recordKeyToString(recordKey)), preEditRowRef.current);
-
-    // 更新编辑 keys（不直接修改 editableKeysSet）
-    const newKeys = editableType === 'single' ? [keyStr] : [...(editableKeys || []), keyStr];
+    // 保存编辑前的数据到 Map（按 recordKey 索引，多行场景互不干扰）
+    const snapshot = recordValue ?? get(props.dataSource, recordKeyToPath(recordKey)) ?? null;
+    preEditRowRefs.current.set(keyStr, snapshot);
+    const currentKeys = editableKeysRef.current;
+    const newKeys = editableType === 'single' ? [keyStr] : [...(currentKeys || []), keyStr];
     setEditableRowKeys(newKeys);
     return true;
   });
@@ -117,32 +173,30 @@ export function useEditableMap(props) {
    * @param recordKey
    */
   const cancelEditable = useRefFunction(recordKey => {
-    const keyStr = String(recordKeyToString(recordKey));
-
-    // 检查是否在编辑列表中
-    if (!checkKeyInEditableList(recordKey)) {
+    const keyStr = normalizeKeyToString(recordKey);
+    if (!isEditable(recordKey)) {
       return true;
     }
 
-    // 更新编辑 keys（不直接修改 editableKeysSet）
-    const newKeys = (editableKeys || []).filter(key => String(key) !== keyStr);
+    // 用 editableKeysRef 读最新值，避免快速连续调用时基于陈旧 editableKeys 计算
+    const newKeys = (editableKeysRef.current || []).filter(key => String(key) !== keyStr);
     setEditableRowKeys(newKeys);
     return true;
   });
 
   /**
-   * 取消编辑的回调
+   * 取消编辑的回调（透传给 props.onCancel，后者返回 false 视为失败、其他视为成功）。
+   * NOTE: "false 即失败" 是与 RowEditableConfig 共用的隐式协议，类型上是 `Promise<any | void>`，
+   *       这里在文档里显式说明便于消费方理解。
    */
   const onCancel = useRefFunction(async (recordKey, editRow, originRow, newLine) => {
     const success = await props?.onCancel?.(recordKey, editRow, originRow, newLine);
-    if (success === false) {
-      return false;
-    }
-    return true;
+    return success !== false;
   });
 
   /**
-   * 保存编辑的回调
+   * 保存编辑的回调（透传给 props.onSave，后者返回 false 视为失败、其他视为成功）。
+   * 成功后：1) 退出编辑态 2) 清掉 preEditRowRefs Map 缓存 3) 按 recordKey 路径更新 dataSource。
    */
   const onSave = useRefFunction(async (recordKey, editRow, originRow) => {
     const success = await props?.onSave?.(recordKey, editRow, originRow);
@@ -152,26 +206,33 @@ export function useEditableMap(props) {
 
     // 先退出编辑状态
     await cancelEditable(recordKey);
-    preEditRowRefs.current.delete(String(recordKeyToString(recordKey)));
+    preEditRowRefs.current.delete(normalizeKeyToString(recordKey));
 
-    // 更新数据源
-    const actionProps = {
+    // 按 key 路径深度合并到 dataSource，避免顶层合并把兄弟字段冲掉
+    props.setDataSource(editableRowByKey({
       data: props.dataSource,
       row: editRow,
-      key: recordKey,
-      childrenColumnName: props.childrenColumnName || 'children'
-    };
-    props.setDataSource(editableRowByKey(actionProps));
+      key: recordKey
+    }));
     return true;
   });
   const saveText = intl.getMessage('editableTable.action.save', '保存');
   const deleteText = intl.getMessage('editableTable.action.delete', '删除');
   const cancelText = intl.getMessage('editableTable.action.cancel', '取消');
+  // 提到外部，避免每次 actionRender 都重新拼模板字符串
+  const deletePopconfirmMessage = `${intl.getMessage('deleteThisLine', '删除此项')}?`;
 
   /**
-   * 渲染操作按钮
+   * 渲染操作按钮。
+   * useCallback 依赖只列真正会变的：editableKeys / dataSource / props.actionRender / 文案 token。
+   * cancelEditable / onCancel / onSave 都是 useRefFunction 引用永远稳定，不必列。
    */
   const actionRender = useCallback((key, config) => {
+    // 按当前 recordKey 从 Map 取真正的快照，构造一个临时 ref 透传给 defaultActionRender。
+    // 这避免了旧版用全局单引用 preEditRowRef 在多行场景被覆盖的 bug。
+    const snapshotRef = {
+      current: preEditRowRefs.current.get(normalizeKeyToString(key)) ?? null
+    };
     const renderConfig = {
       recordKey: key,
       cancelEditable,
@@ -181,10 +242,10 @@ export function useEditableMap(props) {
       setEditableRowKeys,
       saveText,
       cancelText,
-      preEditRowRef,
+      preEditRowRef: snapshotRef,
       preEditRowRefs,
       deleteText,
-      deletePopconfirmMessage: `${intl.getMessage('deleteThisLine', '删除此项')}?`,
+      deletePopconfirmMessage,
       editorType: 'Map',
       ...config
     };
@@ -197,7 +258,7 @@ export function useEditableMap(props) {
       });
     }
     return [renderResult.save, renderResult.delete, renderResult.cancel];
-  }, [editableKeys, props.dataSource, cancelEditable, onCancel, onSave]);
+  }, [editableKeys, props.dataSource, props.actionRender, setEditableRowKeys, saveText, cancelText, deleteText, deletePopconfirmMessage, cancelEditable, onCancel, onSave]);
   return {
     editableKeys,
     setEditableRowKeys,

package/es/utils/useMediaQuery/index.d.ts

@@ -1,40 +1,33 @@
-export declare const MediaQueryEnum: {
-    xs: {
-        maxWidth: number;
-        matchMedia: string;
-    };
-    sm: {
-        minWidth: number;
-        maxWidth: number;
-        matchMedia: string;
-    };
-    md: {
-        minWidth: number;
-        maxWidth: number;
-        matchMedia: string;
-    };
-    lg: {
-        minWidth: number;
-        maxWidth: number;
-        matchMedia: string;
-    };
-    xl: {
-        minWidth: number;
-        maxWidth: number;
-        matchMedia: string;
-    };
-    xxl: {
-        minWidth: number;
-        matchMedia: string;
-    };
+/**
+ * 单个断点描述：可选的 minWidth/maxWidth + 必须的 matchMedia 字符串。
+ */
+type MediaQueryItem = {
+    minWidth?: number;
+    maxWidth?: number;
+    matchMedia: string;
 };
-export type MediaQueryKey = keyof typeof MediaQueryEnum;
+type MediaQueryEnumShape = {
+    xs: MediaQueryItem;
+    sm: MediaQueryItem;
+    md: MediaQueryItem;
+    lg: MediaQueryItem;
+    xl: MediaQueryItem;
+    xxl: MediaQueryItem;
+};
+export type MediaQueryKey = keyof MediaQueryEnumShape;
+/**
+ * 历史导出：保留 `MediaQueryEnum.xx.matchMedia` 直接访问的形状，但底层走懒初始化。
+ * 用 Proxy 把每次属性访问都转发到 `getMediaQueryEnum()`，外部代码无需感知。
+ */
+export declare const MediaQueryEnum: MediaQueryEnumShape;
+/**
+ * 同步读取当前屏幕命中的最大断点。SSR 下返回 undefined（无 window）。
+ * 仅用于类组件 / 非 React 环境的一次性查询；React 函数组件请使用 `useBreakpoint`。
+ */
+export declare const getScreenClassName: () => MediaQueryKey | undefined;
 /**
- * loop query screen className
- * Array.find will throw a error
- * `Rendered more hooks than during the previous render.`
- * So should use Array.forEach
+ * 订阅当前屏幕的断点。返回 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'，
+ * 在所有断点都未命中（理论上不会发生）的兜底场景下返回 'md'。
  */
-export declare const getScreenClassName: () => "xxl" | "xl" | "lg" | "md" | "sm" | "xs" | undefined;
-declare const useBreakpoint: () => "xxl" | "xl" | "lg" | "md" | "sm" | "xs" | undefined;
+declare const useBreakpoint: () => MediaQueryKey;
 export { useBreakpoint };

package/es/utils/useMediaQuery/index.js

@@ -1,103 +1,118 @@
 import { theme } from 'antd';
-import { useEffect, useState } from 'react';
+import { useMemo } from 'react';
 import useMediaQuery from "./query";
-const {
-  getDesignToken
-} = theme;
-const token = getDesignToken();
-export const MediaQueryEnum = {
-  xs: {
-    maxWidth: token.screenXSMax,
-    matchMedia: `(max-width: ${token.screenXSMax}px)`
-  },
-  sm: {
-    minWidth: token.screenSMMin,
-    maxWidth: token.screenSMMax,
-    matchMedia: `(min-width: ${token.screenSMMin}px) and (max-width: ${token.screenSMMax}px)`
-  },
-  md: {
-    minWidth: token.screenMDMin,
-    maxWidth: token.screenMDMax,
-    matchMedia: `(min-width: ${token.screenMDMin}px) and (max-width: ${token.screenMDMax}px)`
-  },
-  lg: {
-    minWidth: token.screenLGMin,
-    maxWidth: token.screenLGMax,
-    matchMedia: `(min-width: ${token.screenLGMin}px) and (max-width: ${token.screenLGMax}px)`
+
+/**
+ * 单个断点描述：可选的 minWidth/maxWidth + 必须的 matchMedia 字符串。
+ */
+
+/**
+ * 按断点优先级从大到小排列，方便 useBreakpoint / getScreenClassName 用同一份顺序匹配。
+ */
+const BREAKPOINT_PRIORITY = ['xxl', 'xl', 'lg', 'md', 'sm', 'xs'];
+let cachedMediaQueryEnum;
+
+/**
+ * 懒求值的 MediaQueryEnum 工厂。
+ *
+ * 不能再像旧实现那样 `const token = theme.getDesignToken()` 写在模块顶层 ——
+ *  1. SSR 环境下模块 import 即触发 antd cssinjs 计算，可能产生 SSR warning；
+ *  2. 用户用 ConfigProvider 自定义 token 时，外层 token 修改后 MediaQueryEnum
+ *     仍是模块加载时的旧值，断点完全失效；
+ *  3. 测试环境下若 antd 还未初始化（mock 时序问题）会直接抛错。
+ *
+ * 改成首次访问时才求值并缓存：浏览器一次会话一般不会改 ConfigProvider token，
+ * 缓存命中即等价于模块顶层常量；SSR 也只会在真正用到时才触发求值。
+ */
+const getMediaQueryEnum = () => {
+  if (cachedMediaQueryEnum) return cachedMediaQueryEnum;
+  const token = theme.getDesignToken();
+  cachedMediaQueryEnum = {
+    xs: {
+      maxWidth: token.screenXSMax,
+      matchMedia: `(max-width: ${token.screenXSMax}px)`
+    },
+    sm: {
+      minWidth: token.screenSMMin,
+      maxWidth: token.screenSMMax,
+      matchMedia: `(min-width: ${token.screenSMMin}px) and (max-width: ${token.screenSMMax}px)`
+    },
+    md: {
+      minWidth: token.screenMDMin,
+      maxWidth: token.screenMDMax,
+      matchMedia: `(min-width: ${token.screenMDMin}px) and (max-width: ${token.screenMDMax}px)`
+    },
+    lg: {
+      minWidth: token.screenLGMin,
+      maxWidth: token.screenLGMax,
+      matchMedia: `(min-width: ${token.screenLGMin}px) and (max-width: ${token.screenLGMax}px)`
+    },
+    xl: {
+      minWidth: token.screenXLMin,
+      maxWidth: token.screenXLMax,
+      matchMedia: `(min-width: ${token.screenXLMin}px) and (max-width: ${token.screenXLMax}px)`
+    },
+    xxl: {
+      minWidth: token.screenXXLMin,
+      matchMedia: `(min-width: ${token.screenXXLMin}px)`
+    }
+  };
+  return cachedMediaQueryEnum;
+};
+
+/**
+ * 历史导出：保留 `MediaQueryEnum.xx.matchMedia` 直接访问的形状，但底层走懒初始化。
+ * 用 Proxy 把每次属性访问都转发到 `getMediaQueryEnum()`，外部代码无需感知。
+ */
+export const MediaQueryEnum = new Proxy({}, {
+  get(_target, prop) {
+    return getMediaQueryEnum()[prop];
   },
-  xl: {
-    minWidth: token.screenXLMin,
-    maxWidth: token.screenXLMax,
-    matchMedia: `(min-width: ${token.screenXLMin}px) and (max-width: ${token.screenXLMax}px)`
+  ownKeys() {
+    return Object.keys(getMediaQueryEnum());
   },
-  xxl: {
-    minWidth: token.screenXXLMin,
-    matchMedia: `(min-width: ${token.screenXXLMin}px)`
+  getOwnPropertyDescriptor(_target, prop) {
+    const value = getMediaQueryEnum()[prop];
+    return value ? {
+      configurable: true,
+      enumerable: true,
+      value,
+      writable: false
+    } : undefined;
   }
-};
+});
+
 /**
- * loop query screen className
- * Array.find will throw a error
- * `Rendered more hooks than during the previous render.`
- * So should use Array.forEach
+ * 同步读取当前屏幕命中的最大断点。SSR 下返回 undefined（无 window）。
+ * 仅用于类组件 / 非 React 环境的一次性查询；React 函数组件请使用 `useBreakpoint`。
  */
 export const getScreenClassName = () => {
-  let queryKey = undefined;
-  // support ssr
-  if (typeof window === 'undefined') {
-    return queryKey;
-  }
-  const mediaQueryKey = Object.keys(MediaQueryEnum).find(key => {
-    const {
-      matchMedia
-    } = MediaQueryEnum[key];
-    if (window.matchMedia(matchMedia).matches) {
-      return true;
-    }
-    return false;
-  });
-  queryKey = mediaQueryKey;
-  return queryKey;
+  if (typeof window === 'undefined') return undefined;
+  const enumValue = getMediaQueryEnum();
+  return BREAKPOINT_PRIORITY.find(key => window.matchMedia(enumValue[key].matchMedia).matches);
 };
+
+/**
+ * 订阅当前屏幕的断点。返回 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'，
+ * 在所有断点都未命中（理论上不会发生）的兜底场景下返回 'md'。
+ */
 const useBreakpoint = () => {
-  const isMd = useMediaQuery(MediaQueryEnum.md.matchMedia);
-  const isLg = useMediaQuery(MediaQueryEnum.lg.matchMedia);
-  const isXxl = useMediaQuery(MediaQueryEnum.xxl.matchMedia);
-  const isXl = useMediaQuery(MediaQueryEnum.xl.matchMedia);
-  const isSm = useMediaQuery(MediaQueryEnum.sm.matchMedia);
-  const isXs = useMediaQuery(MediaQueryEnum.xs.matchMedia);
-  const [colSpan, setColSpan] = useState(getScreenClassName());
-  useEffect(() => {
-    if (process.env.NODE_ENV === 'TEST') {
-      setColSpan(process.env.USE_MEDIA || 'md');
-      return;
-    }
-    if (isXxl) {
-      setColSpan('xxl');
-      return;
-    }
-    if (isXl) {
-      setColSpan('xl');
-      return;
-    }
-    if (isLg) {
-      setColSpan('lg');
-      return;
-    }
-    if (isMd) {
-      setColSpan('md');
-      return;
-    }
-    if (isSm) {
-      setColSpan('sm');
-      return;
-    }
-    if (isXs) {
-      setColSpan('xs');
-      return;
-    }
-    setColSpan('md');
-  }, [isMd, isLg, isXxl, isXl, isSm, isXs]);
-  return colSpan;
+  const enumValue = getMediaQueryEnum();
+  // 6 个 useMediaQuery 调用顺序必须稳定，不能放到循环/条件里
+  const isXs = useMediaQuery(enumValue.xs.matchMedia);
+  const isSm = useMediaQuery(enumValue.sm.matchMedia);
+  const isMd = useMediaQuery(enumValue.md.matchMedia);
+  const isLg = useMediaQuery(enumValue.lg.matchMedia);
+  const isXl = useMediaQuery(enumValue.xl.matchMedia);
+  const isXxl = useMediaQuery(enumValue.xxl.matchMedia);
+  return useMemo(() => {
+    if (isXxl) return 'xxl';
+    if (isXl) return 'xl';
+    if (isLg) return 'lg';
+    if (isMd) return 'md';
+    if (isSm) return 'sm';
+    if (isXs) return 'xs';
+    return 'md';
+  }, [isXxl, isXl, isLg, isMd, isSm, isXs]);
 };
 export { useBreakpoint };

package/es/utils/useMediaQuery/query.d.ts

@@ -1 +1,8 @@
+/**
+ * 订阅一个 CSS media query，返回当前是否匹配。
+ *
+ * SSR 行为：
+ *  - 服务端首次渲染恒定返回 false（避免 hydration mismatch，但首屏可能闪一下）。
+ *  - 客户端 mount 后立即拿到真实值并触发一次 setState 更新。
+ */
 export default function useMediaQuery(mediaQuery: string): boolean;

package/es/utils/useMediaQuery/query.js

@@ -1,21 +1,39 @@
 import { useEffect, useLayoutEffect, useState } from 'react';
+
+/**
+ * SSR 友好的 layoutEffect：模块加载时一次性决定走 useLayoutEffect 还是 useEffect。
+ * 不能写成 `isSsr ? useEffect : useLayoutEffect` 放在组件函数里 —— 虽然
+ * `typeof window` 在同一进程中恒定不变实际不会触发 hooks 顺序问题，但会被
+ * `react-hooks/rules-of-hooks` lint 误报，且阅读时令人困惑。
+ */
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+/**
+ * 订阅一个 CSS media query，返回当前是否匹配。
+ *
+ * SSR 行为：
+ *  - 服务端首次渲染恒定返回 false（避免 hydration mismatch，但首屏可能闪一下）。
+ *  - 客户端 mount 后立即拿到真实值并触发一次 setState 更新。
+ */
 export default function useMediaQuery(mediaQuery) {
-  const isSsr = typeof window === 'undefined';
-  const [matches, setMatches] = useState(() => isSsr ? false : window.matchMedia(mediaQuery).matches);
+  // SSR 期间 window 不存在，恒定 false；放弃在 useState 初始值里读
+  // window.matchMedia，否则客户端 hydration 时会与服务端 false 渲染冲突。
+  const [matches, setMatches] = useState(false);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof window === 'undefined') return;
+    const mediaQueryList = window.matchMedia(mediaQuery);
 
-  // 在 SSR 环境中使用 useEffect，在客户端使用 useLayoutEffect
-  // 这样可以避免 SSR 警告，同时在客户端保持同步更新
-  // 使用条件表达式确保 hooks 调用顺序一致
-  const EffectHook = isSsr ? useEffect : useLayoutEffect;
-  EffectHook(() => {
-    if (isSsr) {
-      return;
+    // mount 后立刻同步一次真实值，弥补 SSR 期间初值恒为 false 的偏差
+    setMatches(mediaQueryList.matches);
+    const listener = event => setMatches(event.matches);
+
+    // 优先用现代 addEventListener；老 Safari (<14) / Edge Legacy 仅有 addListener
+    if (typeof mediaQueryList.addEventListener === 'function') {
+      mediaQueryList.addEventListener('change', listener);
+      return () => mediaQueryList.removeEventListener('change', listener);
     }
-    const mediaQueryList = window.matchMedia(mediaQuery);
-    const listener = e => setMatches(e.matches);
-    // 使用最新的 addEventListener API
-    mediaQueryList.addEventListener('change', listener);
-    return () => mediaQueryList.removeEventListener('change', listener);
-  }, [mediaQuery, isSsr]);
+    mediaQueryList.addListener(listener);
+    return () => mediaQueryList.removeListener(listener);
+  }, [mediaQuery]);
   return matches;
 }