@hsu-react/ui 0.0.1

package/src/components/Search/_hooks/useSearchCommon.ts

@@ -0,0 +1,337 @@
+import { FormInstance } from "antd";
+import { useMemo, useRef, useCallback, RefObject } from "react";
+import { FormItemProps } from "../../FormItem";
+import { generateRandomStr } from "hsu-utils";
+import useLabelWidth from "../../../hooks/useLabelWidth";
+import usePermissions from "../../../hooks/usePermissions";
+import { useSearchItems } from "./useSearchItems";
+import { useSearchForm } from "./useSearchForm";
+import { useAdaptiveColumnNum } from "./useAdaptiveColumnNum";
+import { useSearchExpand } from "./useSearchExpand";
+import {
+  cleanSearchData,
+  calculateVisibleItems,
+  calculateButtonGroupAndColumnWidth,
+} from "../_utils";
+import styles from "../index.module.less";
+import { ChakraButtonProps } from "../../Button";
+
+export interface UseSearchCommonParams {
+  form: FormInstance;
+  searchItems: FormItemProps[];
+  moreSearchItems?: FormItemProps[];
+  searchData?: Record<string, unknown>;
+  hasPermi?: string[];
+  beforeButtonGroup?: ChakraButtonProps[];
+  affterButtonGroup?: ChakraButtonProps[];
+  columnNum: number;
+  autoAdaptWidth: boolean;
+  defaultExpanded: boolean;
+  onExpandChange?: (expand: boolean) => void;
+  showAllSearchItems: boolean;
+  minLabelWidth?: boolean | number;
+  baseWidth?: number;
+  onSearch?: <T = Record<string, unknown>>(data?: Partial<T>) => void;
+  onReset?: () => void;
+  columnOffsetWidth?: number;
+}
+
+export interface UseSearchCommonReturn {
+  // Refs
+  containerRef: RefObject<HTMLDivElement>;
+  buttonGroupRef: RefObject<HTMLDivElement>;
+  cls: string;
+
+  // Form
+  getLabelWidth: ReturnType<typeof useLabelWidth>[1];
+
+  // Search Items
+  processedSearchItems: FormItemProps[];
+  setSearchItems: (items: FormItemProps[]) => void;
+  visibleSearchItems: FormItemProps[];
+  visibleMoreSearchItems: FormItemProps[];
+  visibleSearchItemCount: number;
+  currentSearchItems: FormItemProps[];
+
+  // Column & Layout
+  totalColumnNum: number;
+  adaptiveColumnNum: number;
+
+  // Expand Control
+  expand: boolean;
+  setExpand?: (expand: boolean) => void;
+  toggleExpand: () => void;
+  visibleItemCount: number;
+  hasCustomWidth: boolean;
+  showExpandButton: boolean;
+
+  // Callbacks
+  onSearchClick: () => void;
+  onResetClick: () => void;
+
+  // Render Check
+  shouldRender: boolean;
+  // Permission
+  permitted: boolean;
+}
+
+/**
+ * 提取所有 Search 组件的通用逻辑
+ */
+export const useSearchCommon = (
+  params: UseSearchCommonParams,
+): UseSearchCommonReturn => {
+  const {
+    form,
+    searchItems,
+    moreSearchItems = [],
+    searchData,
+    hasPermi,
+    beforeButtonGroup,
+    affterButtonGroup,
+    columnNum,
+    autoAdaptWidth,
+    defaultExpanded,
+    onExpandChange,
+    showAllSearchItems,
+    baseWidth,
+    onSearch,
+    onReset,
+    columnOffsetWidth = 0,
+  } = params;
+
+  const [, getLabelWidth] = useLabelWidth();
+  const { permitted, checkPermission } = usePermissions(hasPermi);
+  const { searchItems: processedSearchItems, setSearchItems } =
+    useSearchItems(searchItems);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const buttonGroupRef = useRef<HTMLDivElement>(null);
+  const cls = useMemo(() => generateRandomStr(10), []);
+
+  // 提取可见搜索项
+  const visibleSearchItems = useMemo(() => {
+    return processedSearchItems.filter((item) => item.visible !== false);
+  }, [processedSearchItems]);
+
+  // 提取可见的更多搜索项
+  const visibleMoreSearchItems = useMemo(() => {
+    return moreSearchItems.filter((item) => item.visible !== false);
+  }, [moreSearchItems]);
+
+  // 计算可见的搜索项数量
+  const visibleSearchItemCount = useMemo(() => {
+    return visibleSearchItems.length;
+  }, [visibleSearchItems]);
+
+  // 计算总列数（包括按钮组）
+  const baseTotalColumnNum = useMemo(() => columnNum + 1, [columnNum]);
+
+  // 根据容器宽度动态调整列数
+  const totalColumnNum = useAdaptiveColumnNum(
+    containerRef,
+    baseTotalColumnNum,
+    autoAdaptWidth,
+    1, // minColumnNum
+    undefined, // maxColumnNum
+    undefined, // breakpoints
+    baseWidth,
+  );
+
+  // 计算调整后的搜索项列数（不包括按钮组）
+  const adaptiveColumnNum = useMemo(
+    () => Math.max(1, totalColumnNum - 1),
+    [totalColumnNum],
+  );
+
+  // 使用基于宽度的展开/收起控制
+  const { expand, setExpand, toggleExpand, visibleItemCount } = useSearchExpand(
+    containerRef,
+    buttonGroupRef,
+    `.${cls} .${styles.item}`,
+    visibleSearchItemCount,
+    adaptiveColumnNum,
+    autoAdaptWidth,
+    defaultExpanded,
+    onExpandChange,
+    processedSearchItems,
+    showAllSearchItems || !!moreSearchItems?.length,
+    columnOffsetWidth,
+  );
+
+  useSearchForm({ form, searchData });
+
+  // 计算当前应该显示的搜索项
+  const currentSearchItems = useMemo(() => {
+    if (showAllSearchItems || !!moreSearchItems?.length) {
+      if (expand) return [...visibleSearchItems, ...visibleMoreSearchItems];
+      return visibleSearchItems;
+    }
+
+    // 计算按钮组宽度和列宽（用于判断是否需要显示更多项）
+    let buttonGroupWidth: number | undefined;
+    let columnWidth: number | undefined;
+
+    if (!expand) {
+      const result = calculateButtonGroupAndColumnWidth(
+        containerRef,
+        buttonGroupRef,
+        adaptiveColumnNum,
+        columnOffsetWidth,
+      );
+      buttonGroupWidth = result.buttonGroupWidth;
+      columnWidth = result.columnWidth;
+    }
+
+    // 否则使用计算函数
+    return calculateVisibleItems(
+      processedSearchItems,
+      expand,
+      adaptiveColumnNum,
+      visibleItemCount,
+      autoAdaptWidth,
+      buttonGroupWidth,
+      columnWidth,
+    );
+  }, [
+    showAllSearchItems,
+    moreSearchItems?.length,
+    expand,
+    processedSearchItems,
+    adaptiveColumnNum,
+    visibleItemCount,
+    autoAdaptWidth,
+    visibleSearchItems,
+    visibleMoreSearchItems,
+    columnOffsetWidth,
+  ]);
+
+  const onResetClick = useCallback(() => {
+    if (!form) return;
+    form.resetFields();
+    onReset?.();
+  }, [form, onReset]);
+
+  const onSearchClick = useCallback(() => {
+    if (!form) return;
+    form.validateFields().then((value) => {
+      const cleanedData = cleanSearchData(value);
+      onSearch?.(cleanedData);
+    });
+  }, [form, onSearch]);
+
+  // 检查是否有自定义宽度
+  const hasCustomWidth = useMemo(() => {
+    return processedSearchItems.some((item) => item.width !== undefined);
+  }, [processedSearchItems]);
+
+  // 计算实际应该显示的项数（考虑按钮组宽度大于列宽的情况）
+  const actualDisplayCount = useMemo(() => {
+    if (hasCustomWidth) {
+      return visibleItemCount;
+    }
+
+    // 计算按钮组宽度和列宽
+    const { buttonGroupWidth, columnWidth } =
+      calculateButtonGroupAndColumnWidth(
+        containerRef,
+        buttonGroupRef,
+        adaptiveColumnNum,
+        columnOffsetWidth,
+      );
+
+    // 判断按钮组宽度是否大于列宽，如果是，则显示 实际搜索项数量+1
+    if (
+      buttonGroupWidth !== undefined &&
+      columnWidth !== undefined &&
+      (buttonGroupWidth > columnWidth ||
+        (buttonGroupWidth < columnWidth &&
+          adaptiveColumnNum + 1 === visibleSearchItemCount))
+    ) {
+      return adaptiveColumnNum + 1;
+    }
+
+    return adaptiveColumnNum;
+  }, [
+    hasCustomWidth,
+    adaptiveColumnNum,
+    columnOffsetWidth,
+    visibleSearchItemCount,
+    visibleItemCount,
+  ]);
+
+  // 计算是否显示展开按钮
+  const showExpandButton = useMemo(() => {
+    // 如果有更多搜索项，显示展开按钮
+    if (showAllSearchItems || !!moreSearchItems?.length) {
+      if (visibleMoreSearchItems?.length) {
+        return true;
+      }
+      return false;
+    }
+
+    // 如果有自定义宽度，根据可见项数量判断
+    if (hasCustomWidth) {
+      return visibleSearchItemCount > visibleItemCount;
+    }
+    // 否则根据实际显示项数判断（考虑按钮组宽度大于列宽的情况）
+    return visibleSearchItemCount > actualDisplayCount;
+  }, [
+    showAllSearchItems,
+    moreSearchItems,
+    hasCustomWidth,
+    visibleSearchItemCount,
+    actualDisplayCount,
+    visibleMoreSearchItems?.length,
+    visibleItemCount,
+  ]);
+
+  // 检查按钮组是否有权限的按钮
+  const hasPermittedButtons = useCallback(
+    (buttonGroup?: ChakraButtonProps[]) => {
+      if (!buttonGroup?.length) return false;
+
+      return buttonGroup.some((button) => checkPermission(button.hasPermi));
+    },
+    [checkPermission],
+  );
+
+  // 权限和内容检查
+  const shouldRender = useMemo(() => {
+    return Boolean(
+      hasPermittedButtons(beforeButtonGroup) ||
+      hasPermittedButtons(affterButtonGroup) ||
+      (permitted && searchItems.length > 0),
+    );
+  }, [
+    searchItems.length,
+    beforeButtonGroup,
+    affterButtonGroup,
+    permitted,
+    hasPermittedButtons,
+  ]);
+
+  return {
+    containerRef,
+    buttonGroupRef,
+    cls,
+    getLabelWidth,
+    processedSearchItems,
+    setSearchItems,
+    visibleSearchItems,
+    visibleMoreSearchItems,
+    visibleSearchItemCount,
+    currentSearchItems,
+    totalColumnNum,
+    adaptiveColumnNum,
+    expand,
+    setExpand,
+    toggleExpand,
+    visibleItemCount,
+    hasCustomWidth,
+    showExpandButton,
+    onSearchClick,
+    onResetClick,
+    shouldRender,
+    permitted,
+  };
+};

package/src/components/Search/_hooks/useSearchExpand.ts

@@ -0,0 +1,198 @@
+import { useState, useEffect, useCallback } from "react";
+import { FormItemProps } from "../../FormItem";
+
+/**
+ * 基于宽度自适应控制展开/收起的Hook
+ * @param containerRef 容器引用
+ * @param buttonGroupRef 按钮组引用
+ * @param itemClassName 搜索项的className
+ * @param itemCount 搜索项总数
+ * @param columnNum 列数
+ * @param autoAdaptWidth 是否启用自适应宽度
+ * @param defaultExpanded 默认是否展开
+ * @param onExpandChange 展开状态变化回调
+ * @param searchItems 搜索项配置数组（可选）
+ * @param showAllSearchItems 是否显示所有搜索项
+ * @returns 展开状态及控制方法
+ */
+export function useSearchExpand(
+  containerRef: React.RefObject<HTMLDivElement>,
+  buttonGroupRef: React.RefObject<HTMLDivElement>,
+  itemClassName: string,
+  itemCount: number,
+  columnNum: number,
+  autoAdaptWidth: boolean,
+  defaultExpanded: boolean,
+  onExpandChange?: (expand: boolean) => void,
+  searchItems?: FormItemProps[],
+  showAllSearchItems?: boolean,
+  columnOffsetWidth: number = 0
+) {
+  const [expand, setExpand] = useState<boolean>(defaultExpanded);
+  const [visibleItemCount, setVisibleItemCount] = useState<number>(columnNum);
+
+  useEffect(() => {
+    if (!autoAdaptWidth || !containerRef.current || !!showAllSearchItems) {
+      return;
+    }
+
+    const container = containerRef.current;
+
+    const calculateVisibleItems = () => {
+      if (!containerRef.current || !buttonGroupRef.current) return;
+
+      const containerWidth = container.offsetWidth;
+      // 减去padding
+      const availableWidth = containerWidth - 30; // 15px padding on each side
+
+      // 获取按钮组的实际宽度（计算所有子元素宽度总和）
+      let buttonGroupWidth = 0;
+      const buttonChildren = Array.from(buttonGroupRef.current.children);
+      if (buttonChildren.length > 0) {
+        // 计算所有子元素的宽度总和
+        let totalWidth = 0;
+        buttonChildren?.forEach((child) => {
+          totalWidth += (child as HTMLElement).offsetWidth;
+        });
+        // 加上子元素之间的间距（column-gap: 10px）
+        const childGap = 5;
+        totalWidth += (buttonChildren.length - 1) * childGap;
+        buttonGroupWidth = totalWidth;
+      }
+
+      // 获取所有搜索项元素
+      const items = container.querySelectorAll(`${itemClassName}`);
+
+      // 计算第一行能放下的搜索项数量
+      let count = 0;
+      let usedWidth = 0;
+      const gap = 10; // 项之间的间距
+
+      // 计算默认单个项的宽度（容器宽度除以列数）
+      const defaultItemWidth =
+        (availableWidth - (columnNum - 1) * gap) / columnNum -
+        columnOffsetWidth;
+
+      // 遍历所有搜索项（包括未渲染的）
+      for (let i = 0; i < itemCount; i++) {
+        let itemWidth = 0;
+
+        // 如果DOM中有这个item，使用实际宽度
+        if (i < items.length) {
+          const item = items[i] as HTMLElement;
+          itemWidth = item.offsetWidth;
+        } else if (searchItems && searchItems[i]?.width !== undefined) {
+          // 如果DOM中没有，但有设置宽度，使用设置的宽度
+          const configWidth = searchItems[i].width;
+          if (typeof configWidth === "number") {
+            itemWidth = configWidth;
+          } else if (typeof configWidth === "string") {
+            // 处理百分比或像素值
+            if (configWidth.endsWith("%")) {
+              const percent = parseFloat(configWidth) / 100;
+              itemWidth = availableWidth * percent;
+            } else {
+              itemWidth = parseFloat(configWidth);
+            }
+          }
+        } else {
+          // 如果DOM中没有且没有设置宽度，使用默认计算宽度
+          itemWidth = defaultItemWidth;
+        }
+
+        // 计算加上当前项后的总宽度（包括gap）
+        const nextWidth = usedWidth + itemWidth + (i > 0 ? gap : 0);
+
+        // 检查是否还能放下按钮组（需要预留gap和按钮组宽度）
+        if (nextWidth + gap + buttonGroupWidth <= availableWidth) {
+          count++;
+          usedWidth = nextWidth;
+        } else {
+          break;
+        }
+      }
+
+      // 至少显示1个搜索项
+      count = Math.max(1, count);
+      setVisibleItemCount(count);
+
+      // 如果所有项都能显示，则不需要展开
+      if (count >= itemCount) {
+        setExpand(false);
+      }
+    };
+
+    const resizeObserver = new ResizeObserver(() => {
+      // 使用 requestAnimationFrame 延迟到下一帧，确保DOM已更新
+      requestAnimationFrame(() => {
+        calculateVisibleItems();
+      });
+    });
+
+    // MutationObserver 监听DOM变化
+    const mutationObserver = new MutationObserver(() => {
+      // 使用 requestAnimationFrame 延迟到下一帧
+      requestAnimationFrame(() => {
+        calculateVisibleItems();
+      });
+    });
+
+    resizeObserver.observe(container);
+    mutationObserver.observe(container, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["class", "style"],
+    });
+
+    // 监听窗口大小变化
+    const handleWindowResize = () => {
+      requestAnimationFrame(() => {
+        calculateVisibleItems();
+      });
+    };
+    window.addEventListener("resize", handleWindowResize);
+
+    // 初始计算（延迟执行以确保DOM已渲染）
+    requestAnimationFrame(() => {
+      calculateVisibleItems();
+    });
+
+    return () => {
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+      window.removeEventListener("resize", handleWindowResize);
+    };
+  }, [
+    containerRef,
+    buttonGroupRef,
+    itemClassName,
+    itemCount,
+    columnNum,
+    autoAdaptWidth,
+    searchItems,
+    showAllSearchItems,
+    columnOffsetWidth,
+  ]);
+
+  const toggleExpand = useCallback(() => {
+    const newExpand = !expand;
+    setExpand(newExpand);
+    onExpandChange?.(newExpand);
+  }, [expand, onExpandChange]);
+
+  const handleSetExpand = useCallback(
+    (newExpand: boolean) => {
+      setExpand(newExpand);
+      onExpandChange?.(newExpand);
+    },
+    [onExpandChange]
+  );
+
+  return {
+    expand,
+    setExpand: handleSetExpand,
+    toggleExpand,
+    visibleItemCount: autoAdaptWidth ? visibleItemCount : columnNum,
+  };
+}

package/src/components/Search/_hooks/useSearchForm.ts

@@ -0,0 +1,21 @@
+import { useEffect } from "react";
+import { FormInstance } from "antd";
+import { Equal } from "hsu-utils";
+
+interface UseSearchFormProps {
+  form: FormInstance;
+  searchData?: Record<string, unknown>;
+}
+
+/**
+ * 管理搜索表单数据
+ */
+export function useSearchForm({ form, searchData }: UseSearchFormProps) {
+  useEffect(() => {
+    if (searchData && !Equal.ObjEqual(searchData, form.getFieldsValue())) {
+      form.resetFields();
+      form.setFieldsValue(searchData);
+    }
+  }, [form, searchData]);
+}
+

package/src/components/Search/_hooks/useSearchItems.ts

@@ -0,0 +1,53 @@
+import { useCallback, useMemo, useState } from "react";
+import { FormItemProps } from "../../FormItem";
+
+/**
+ * 管理搜索项状态
+ *
+ * 通过 useMemo 直接从入参派生，仅把用户在 FilterDropdown 里手动切换的
+ * visible 覆盖保存为 state；避免 useEffect 镜像 prop 时因为父组件传入
+ * 新数组引用而反复 setState，从而触发 Maximum update depth 循环。
+ */
+export function useSearchItems(searchItems: FormItemProps[]) {
+  const [visibilityOverrides, setVisibilityOverrides] = useState<
+    Record<string, boolean>
+  >({});
+
+  const processedSearchItems = useMemo<FormItemProps[]>(() => {
+    return (
+      searchItems?.map((i) => {
+        const key =
+          i.name !== undefined && i.name !== null ? String(i.name) : "";
+        const override = key ? visibilityOverrides[key] : undefined;
+        return {
+          ...i,
+          visible:
+            override !== undefined
+              ? override
+              : typeof i.visible === "boolean"
+                ? i.visible
+                : true,
+        };
+      }) ?? []
+    );
+  }, [searchItems, visibilityOverrides]);
+
+  const setSearchItems = useCallback((items: FormItemProps[]) => {
+    const overrides: Record<string, boolean> = {};
+    items?.forEach((item) => {
+      if (
+        item.name !== undefined &&
+        item.name !== null &&
+        typeof item.visible === "boolean"
+      ) {
+        overrides[String(item.name)] = item.visible;
+      }
+    });
+    setVisibilityOverrides(overrides);
+  }, []);
+
+  return {
+    searchItems: processedSearchItems,
+    setSearchItems,
+  };
+}

package/src/components/Search/_types/index.ts

@@ -0,0 +1,53 @@
+import { FormInstance } from "antd";
+import { ReactNode } from "react";
+import { FormItemProps } from "../../FormItem";
+import { ChakraButtonProps } from "../../Button";
+
+/**
+ * Search 组件的基础属性接口
+ */
+export interface BaseSearchProps {
+  searchItems?: FormItemProps[];
+  moreSearchItems?: FormItemProps[];
+  onSearch?: <T = Record<string, unknown>>(data?: Partial<T>) => void;
+  onReset?: () => void;
+  className?: string;
+  externalForm?: FormInstance;
+  hasPermi?: string[];
+  /** 搜索项列数（不包括按钮组，总列数为 columnNum + 1） */
+  columnNum?: number;
+  beforeButtonGroup?: ChakraButtonProps[];
+  affterButtonGroup?: ChakraButtonProps[];
+  searchData?: Record<string, unknown>;
+  minLabelWidth?: boolean | number;
+  /** 默认是否展开 */
+  defaultExpanded?: boolean;
+  /** 展开状态变化时的回调 */
+  onExpandChange?: (expand: boolean) => void;
+  /** 是否启用基于宽度的自适应布局（默认显示一行包括按钮） */
+  autoAdaptWidth?: boolean;
+  /** 自适应布局的基准宽度（默认1200px） */
+  baseWidth?: number;
+  onValuesChange?: (
+    value: Record<string, unknown>,
+    values: Record<string, unknown>
+  ) => void;
+  searchDisabled?: boolean;
+  showAllSearchItems?: boolean;
+  /** 查询按钮文本 */
+  searchText?: ReactNode;
+  /** 重置按钮文本 */
+  resetText?: ReactNode;
+  /** 列偏移宽度，用于调整列宽计算（默认 0） */
+  columnOffsetWidth?: number;
+}
+
+/**
+ * 带筛选器的 Search 组件属性接口
+ */
+export interface SearchPropsWithFilter extends BaseSearchProps {
+  /** 是否显示筛选器 */
+  setFilter?: boolean;
+  /** FilterDropdown 勾选项变化时的回调 */
+  onFilterChange?: (items: FormItemProps[]) => void;
+}