@hsu-react/ui 0.0.1

package/src/components/Table/index.tsx

@@ -0,0 +1,335 @@
+import {
+  ColumnType as AntColumnType,
+  ColumnGroupType as AntColumnGroupType,
+} from "antd/lib/table";
+import {
+  Table as AntdTable,
+  TableProps as AntdTableProps,
+  TooltipProps,
+} from "antd";
+import Drag, { DragProps } from "./_components/Drag";
+import Pagination, { PaginationProps } from "./_components/Pagination";
+import React, { CSSProperties, ReactNode, useMemo, useRef } from "react";
+
+import { AnyObject } from "antd/es/_util/type";
+import { generateRandomStr } from "hsu-utils";
+import classNames from "classnames";
+import styles from "./index.module.less";
+import useHideHeaderScrollbar from "./_hooks/useHideHeaderScrollbar";
+import useSetTableHeight from "./_hooks/useSetTableHeight";
+import { ColumnTitleProps } from "antd/lib/table/interface";
+import useAutoScrolling from "./_hooks/useAutoScrolling";
+import useScrollEnd from "./_hooks/useScrollEnd";
+import useEllipsisTooltip from "./_hooks/useEllipsisTooltip";
+import useTablePagination from "./_hooks/useTablePagination";
+import useTableColumns from "./_hooks/useTableColumns";
+
+export { Drag as TableDrag };
+
+export interface EllipsisTooltipConfig
+  extends Omit<TooltipProps, "title" | "children"> {
+  ellipsisPosition?: "start" | "end";
+  defaultWidth?: number; // 默认 Tooltip 宽度（当列没有设置宽度时使用）
+}
+
+export interface ColumnType<RecordType> extends AntColumnType<RecordType> {
+  title?: string;
+  renderTitle?: (title: string) => ReactNode;
+  titleSort?: (props: ColumnTitleProps<RecordType>) => ReactNode;
+  dataIndex?: string;
+  hidden?: boolean;
+  sort?: number;
+  hasPermi?: string[];
+  children?: ColumnType<RecordType>[];
+  mergeRow?: boolean;
+  help?: string;
+  orderKey?: string;
+  fixedWidth?: boolean;
+  ellipsisPosition?: "start" | "end";
+}
+export interface ColumnsGroupType<RecordType>
+  extends Omit<AntColumnGroupType<RecordType>, "children"> {
+  title?: string;
+  renderTitle?: (title: string) => ReactNode;
+  titleSort?: (props: ColumnTitleProps<RecordType>) => ReactNode;
+  dataIndex?: string;
+  hidden?: boolean;
+  sort?: number;
+  hasPermi?: string[];
+  children?: ColumnsGroupType<RecordType>[];
+  mergeRow?: boolean;
+  help?: string;
+  orderKey?: string;
+  fixedWidth?: boolean;
+  ellipsisPosition?: "start" | "end";
+}
+export type ColumnsType<RecordType = AnyObject> = (
+  | ColumnType<RecordType>
+  | ColumnsGroupType<RecordType>
+)[];
+
+export interface TableProps<RecordType = AnyObject>
+  extends Omit<
+    AntdTableProps<RecordType>,
+    "scroll" | "pagination" | "columns"
+  > {
+  columns?: ColumnsType<RecordType>;
+  scroll?: boolean | { y: boolean };
+  autoWidth?: boolean;
+  scrollAutoHeight?: boolean;
+  hideScrollbar?: boolean;
+  thPadding?: string;
+  tdPadding?: string;
+  expandedCellPadding?: string;
+  pagination?: false | PaginationProps;
+  onDragEnd?: DragProps["onDragEnd"];
+  tableClassName?: string;
+  fillPanel?: boolean;
+  staticDataSource?: boolean;
+  antdTableClassName?: string;
+  autoScrolling?: boolean;
+  autoScrollingInterval?: number;
+  /** smooth 模式自动滚动速度，单位 px/s，默认 25 */
+  autoScrollingSpeed?: number;
+  autoScrollMode?: "smooth" | "row";
+  /** 自动滚动到末尾后是否循环回到顶部，默认 true */
+  autoScrollLoop?: boolean;
+  /** 循环模式："reset" 回到顶部重新滚动（默认），"seamless" 无缝衔接继续滚动 */
+  autoScrollLoopMode?: "reset" | "seamless";
+  /** 自动滚动偏移量阈值（px），可滚动溢出超过该值后才启动自动滚动，默认 0 */
+  autoScrollingOffset?: number;
+  hideEmpty?: boolean;
+  ellipsisTooltipConfig?: EllipsisTooltipConfig;
+  serialNumberColumn?: boolean;
+  onAutoScrollEndAdd?: () => Promise<boolean>;
+  onScrollEnd?: () => void;
+  order?: { k: string; t: "asc" | "desc" };
+  onOrderChange?: (order?: { k: string; t: "asc" | "desc" }) => void;
+  sorter?: boolean;
+  showTotal?: false | ((total: number, range: [number, number]) => ReactNode);
+  isExpandedCellTable?: boolean;
+}
+
+type TableFC = (<T extends AnyObject>(
+  props: TableProps<T>
+) => JSX.Element | null) &
+  React.FC<TableProps<AnyObject>>;
+
+const Table: TableFC = <T extends AnyObject>(props: TableProps<T>) => {
+  const {
+    scroll = false,
+    pagination = {},
+    className,
+    dataSource,
+    columns = [],
+    autoWidth,
+    expandable = {},
+    scrollAutoHeight = true,
+    hideScrollbar = true,
+    thPadding,
+    tdPadding,
+    expandedCellPadding,
+    onDragEnd,
+    tableClassName,
+    fillPanel,
+    staticDataSource = false,
+    id,
+    antdTableClassName,
+    autoScrolling,
+    autoScrollingInterval: interval,
+    autoScrollingSpeed,
+    autoScrollMode,
+    autoScrollLoop = true,
+    autoScrollLoopMode,
+    autoScrollingOffset,
+    hideEmpty = false,
+    ellipsisTooltipConfig,
+    serialNumberColumn = false,
+    onAutoScrollEndAdd,
+    onScrollEnd,
+    bordered,
+    order,
+    onOrderChange,
+    onChange,
+    sorter,
+    virtual,
+    showTotal,
+    rowSelection,
+    isExpandedCellTable = false,
+    ...TableConfig
+  } = props;
+  const {
+    pageSize,
+    current,
+    total,
+    onChange: onChangePage,
+    onShowSizeChange,
+    onStaticPaginationChange,
+    ...paginationConfig
+  } = typeof pagination === "boolean" ? ({} as PaginationProps) : pagination;
+  const ref = useRef<HTMLDivElement>(null);
+  const cls = useMemo(() => generateRandomStr(10), []);
+
+  const { enhanceColumns } = useEllipsisTooltip<T>(ellipsisTooltipConfig);
+
+  const {
+    _pageNum,
+    _pageSize,
+    paginatedDataSource,
+    mergeRowDataSource,
+    handlePageChange,
+    handlePageSizeChange,
+  } = useTablePagination({
+    dataSource,
+    pagination,
+    staticDataSource,
+    current,
+    pageSize,
+    onChangePage,
+    onShowSizeChange,
+    onStaticPaginationChange,
+  });
+
+  const { _columns, renderedColumns, handleTableChange } = useTableColumns({
+    columns,
+    scroll,
+    autoWidth,
+    dataSource,
+    enhanceColumns,
+    serialNumberColumn,
+    pagination,
+    _pageNum,
+    _pageSize,
+    order,
+    mergeRowDataSource,
+    onChange,
+    onOrderChange,
+    sorter,
+    ref,
+    cls,
+    bordered,
+    rowSelection,
+    expandable,
+  });
+
+  useSetTableHeight({
+    pagination,
+    scroll,
+    scrollAutoHeight,
+    ref,
+    dataSource,
+    cls,
+    fillPanel,
+    columns: _columns,
+    bordered,
+    virtual,
+  });
+
+  useHideHeaderScrollbar({
+    hideScrollbar,
+    cls,
+    ref,
+    scroll,
+    bordered,
+  });
+
+  useAutoScrolling({
+    cls,
+    autoScrolling,
+    ref,
+    dataSource,
+    interval,
+    autoScrollingSpeed,
+    onAutoScrollEndAdd,
+    autoScrollMode,
+    autoScrollLoop,
+    autoScrollLoopMode,
+    autoScrollingOffset,
+  });
+
+  useScrollEnd({
+    cls,
+    ref,
+    dataSource,
+    onScrollEnd,
+    autoScrolling,
+  });
+
+  if (!_columns.length) {
+    return null;
+  }
+
+  const isScrollEnabled = Boolean(scroll && !virtual);
+  const isScrollYDisabled =
+    typeof scroll === "object" && scroll.y === false && !virtual;
+
+  return (
+    <Drag rowKey={props.rowKey} dataSource={dataSource} onDragEnd={onDragEnd}>
+      <div
+        className={classNames(styles.Table, className, cls)}
+        ref={ref}
+        id={id}
+        style={
+          {
+            "--th-padding": thPadding,
+            "--td-padding": tdPadding,
+            "--expanded-cell-padding": expandedCellPadding || tdPadding,
+          } as CSSProperties
+        }
+      >
+        <div
+          className={classNames(styles.antdTable, tableClassName, {
+            [styles.scroll]: isScrollEnabled,
+            [styles["y-unScroll"]]: isScrollYDisabled,
+            [styles.hideScrollbar]: hideScrollbar,
+            [styles.hideEmpty]: hideEmpty,
+            [styles.isExpandedCellTable]: isExpandedCellTable,
+          })}
+        >
+          <AntdTable
+            {...TableConfig}
+            bordered={bordered}
+            components={onDragEnd ? { body: { row: Drag.Row } } : undefined}
+            dataSource={paginatedDataSource}
+            columns={renderedColumns}
+            pagination={false}
+            scroll={isScrollEnabled ? { y: "" } : undefined}
+            expandable={
+              expandable ? { ...expandable, columnWidth: 48 } : undefined
+            }
+            className={antdTableClassName}
+            onChange={handleTableChange}
+            virtual={virtual}
+            rowSelection={
+              rowSelection ? { ...rowSelection, columnWidth: 48 } : undefined
+            }
+          />
+        </div>
+        {pagination && (
+          <Pagination
+            pageSize={_pageSize}
+            current={_pageNum}
+            total={total || dataSource?.length}
+            listLength={dataSource?.length}
+            onChange={handlePageChange}
+            size="small"
+            showQuickJumper={true}
+            onShowSizeChange={handlePageSizeChange}
+            showSizeChanger={true}
+            pageSizeOptions={[10, 20, 50, 100, 200]}
+            showTotal={
+              showTotal === false
+                ? undefined
+                : showTotal
+                ? showTotal
+                : (total) => `共 ${total} 条数据`
+            }
+            {...paginationConfig}
+          />
+        )}
+      </div>
+    </Drag>
+  );
+};
+
+export default Table;

package/src/components/Tags/_components/EllipsisTag/index.module.less

@@ -0,0 +1,18 @@
+.ellipsisTag {
+  flex-shrink: 0;
+  margin: 0;
+  cursor: pointer;
+}
+
+.tooltip {
+  .tooltipContent {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    max-width: 300px;
+  }
+
+  .tooltipTag {
+    margin: 0;
+  }
+}

package/src/components/Tags/_components/EllipsisTag/index.tsx

@@ -0,0 +1,54 @@
+import { Tag, Tooltip } from "antd";
+import React from "react";
+import { getTagColor } from "../../_utils";
+import styles from "./index.module.less";
+
+export interface EllipsisTagProps {
+  ellipsisTags: string[];
+  startIndex: number;
+  colors?: string[];
+}
+
+/**
+ * 省略标签组件，显示被省略的标签数量，悬浮时通过 Tooltip 展示所有被省略的标签
+ */
+const EllipsisTag: React.FC<EllipsisTagProps> = (props) => {
+  const { ellipsisTags, startIndex, colors } = props;
+
+  if (ellipsisTags.length === 0) {
+    return null;
+  }
+
+  return (
+    <Tooltip
+      title={
+        <div className={styles.tooltipContent}>
+          {ellipsisTags?.map((tag, index) => (
+            <Tag
+              key={`ellipsis-${tag}-${index}`}
+              color={getTagColor(startIndex + index, colors)}
+              className={styles.tooltipTag}
+            >
+              {tag}
+            </Tag>
+          ))}
+        </div>
+      }
+      classNames={{
+        root: styles.tooltip,
+      }}
+      color="#fff"
+      styles={{
+        body: {
+          padding: "6px",
+          maxHeight: "300px",
+          overflow: "auto",
+        },
+      }}
+    >
+      <Tag className={styles.ellipsisTag}>+{ellipsisTags.length}</Tag>
+    </Tooltip>
+  );
+};
+
+export default EllipsisTag;

package/src/components/Tags/_components/MeasureContainer/index.module.less

@@ -0,0 +1,15 @@
+.measureContainer {
+  position: absolute;
+  visibility: hidden;
+  top: -9999px;
+  left: -9999px;
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: 8px;
+}
+
+.tag {
+  flex-shrink: 0;
+  margin: 0;
+}

package/src/components/Tags/_components/MeasureContainer/index.tsx

@@ -0,0 +1,37 @@
+import { Tag } from "antd";
+import React from "react";
+import { getTagColor } from "../../_utils";
+import styles from "./index.module.less";
+
+export interface MeasureContainerProps {
+  tags: string[];
+  colors?: string[];
+}
+
+/**
+ * 用于测量标签宽度的隐藏容器
+ */
+const MeasureContainer = React.forwardRef<
+  HTMLDivElement,
+  MeasureContainerProps
+>((props, ref) => {
+  const { tags, colors } = props;
+
+  return (
+    <div ref={ref} className={styles.measureContainer}>
+      {tags?.map((tag, index) => (
+        <Tag
+          key={`measure-${tag}-${index}`}
+          color={getTagColor(index, colors)}
+          className={styles.tag}
+        >
+          {tag}
+        </Tag>
+      ))}
+    </div>
+  );
+});
+
+MeasureContainer.displayName = "MeasureContainer";
+
+export default MeasureContainer;

package/src/components/Tags/_hooks/index.ts

@@ -0,0 +1 @@
+export { useVisibleTags } from "./useVisibleTags";

package/src/components/Tags/_hooks/useVisibleTags.ts

@@ -0,0 +1,101 @@
+import { useEffect, useState } from "react";
+import { calculateVisibleCount } from "../_utils/calculateVisibleCount";
+
+export interface UseVisibleTagsOptions {
+  tags: string[];
+  gap?: number;
+  ellipsisTagWidth?: number;
+  ellipsis?: boolean;
+}
+
+/**
+ * 计算可见标签数量的 Hook
+ * @param containerRef 容器引用
+ * @param measureRef 测量容器引用
+ * @param options 配置选项
+ * @returns 可见的标签数量
+ */
+export function useVisibleTags(
+  containerRef: React.RefObject<HTMLDivElement>,
+  measureRef: React.RefObject<HTMLDivElement>,
+  options: UseVisibleTagsOptions,
+): number {
+  const { tags, gap = 8, ellipsisTagWidth = 60, ellipsis = true } = options;
+  const [visibleCount, setVisibleCount] = useState<number>(tags.length);
+
+  // 当 tags 变化时，重置 visibleCount
+  useEffect(() => {
+    setVisibleCount(tags.length);
+  }, [tags.length]);
+
+  // 如果禁用省略，直接返回所有标签数量
+  useEffect(() => {
+    if (!ellipsis) {
+      setVisibleCount(tags.length);
+    }
+  }, [ellipsis, tags.length]);
+
+  // 计算可见的 tag 数量
+  useEffect(() => {
+    // 如果禁用省略，不进行计算
+    if (!ellipsis) {
+      return;
+    }
+
+    if (!containerRef.current || !measureRef.current || tags.length === 0) {
+      setVisibleCount(tags.length);
+      return;
+    }
+
+    const calculate = () => {
+      const container = containerRef.current;
+      const measureContainer = measureRef.current;
+      if (!container || !measureContainer) return;
+
+      const containerWidth = container.offsetWidth;
+      if (containerWidth === 0) {
+        // 容器宽度为 0，可能是隐藏状态，不进行计算
+        return;
+      }
+
+      // 获取所有 tag 元素的实际宽度
+      const tagElements = measureContainer.children;
+      const tagWidths: number[] = [];
+      for (let i = 0; i < tagElements.length; i++) {
+        const element = tagElements[i] as HTMLElement;
+        tagWidths.push(element.offsetWidth);
+      }
+
+      const count = calculateVisibleCount(
+        containerWidth,
+        tagWidths,
+        gap,
+        ellipsisTagWidth,
+      );
+      setVisibleCount(count);
+    };
+
+    // 使用 requestAnimationFrame 确保 DOM 已更新
+    const timer = requestAnimationFrame(() => {
+      calculate();
+    });
+
+    // 监听容器大小变化
+    const resizeObserver = new ResizeObserver(() => {
+      requestAnimationFrame(() => {
+        calculate();
+      });
+    });
+
+    if (containerRef.current) {
+      resizeObserver.observe(containerRef.current);
+    }
+
+    return () => {
+      cancelAnimationFrame(timer);
+      resizeObserver.disconnect();
+    };
+  }, [tags, gap, ellipsisTagWidth, ellipsis, containerRef, measureRef]);
+
+  return visibleCount;
+}

package/src/components/Tags/_utils/calculateVisibleCount.ts

@@ -0,0 +1,47 @@
+/**
+ * 计算可见的标签数量
+ * @param containerWidth 容器宽度
+ * @param tagWidths 所有标签的宽度数组
+ * @param gap 标签之间的间距
+ * @param ellipsisTagWidth 省略标签的预估宽度
+ * @returns 可见的标签数量
+ */
+export function calculateVisibleCount(
+  containerWidth: number,
+  tagWidths: number[],
+  gap: number = 8,
+  ellipsisTagWidth: number = 60
+): number {
+  if (containerWidth === 0 || tagWidths.length === 0) {
+    return tagWidths.length;
+  }
+
+  let usedWidth = 0;
+  let count = 0;
+
+  // 遍历所有 tag，计算能显示多少个
+  for (let i = 0; i < tagWidths.length; i++) {
+    const tagWidth = tagWidths[i] || 0;
+    // 计算加上当前 tag 后的总宽度
+    const nextWidth = usedWidth + tagWidth + (i > 0 ? gap : 0);
+
+    // 检查是否需要显示省略标签
+    if (i < tagWidths.length - 1) {
+      // 不是最后一个 tag，需要预留省略标签的空间
+      if (nextWidth + gap + ellipsisTagWidth > containerWidth) {
+        break;
+      }
+    } else {
+      // 是最后一个 tag，只需要检查当前宽度
+      if (nextWidth > containerWidth) {
+        break;
+      }
+    }
+
+    count++;
+    usedWidth = nextWidth;
+  }
+
+  // 至少显示 0 个（如果连一个都放不下，就只显示省略标签）
+  return Math.max(0, count);
+}

package/src/components/Tags/_utils/getTagColor.ts

@@ -0,0 +1,15 @@
+/**
+ * 根据索引获取标签颜色
+ * @param index 标签索引
+ * @param colors 颜色数组
+ * @returns 颜色值或 undefined
+ */
+export function getTagColor(
+  index: number,
+  colors?: string[]
+): string | undefined {
+  if (colors && colors.length > 0) {
+    return colors[index % colors.length];
+  }
+  return undefined;
+}

package/src/components/Tags/_utils/index.ts

@@ -0,0 +1,2 @@
+export { getTagColor } from "./getTagColor";
+export { calculateVisibleCount } from "./calculateVisibleCount";

package/src/components/Tags/index.md

@@ -0,0 +1,17 @@
+---
+nav: 组件
+group:
+  title: 数据展示
+  order: 4
+title: Tags 标签
+---
+
+# Tags 标签
+
+> `Tags` 组件。完整 API 见源码类型定义，下方为基础用法。
+
+## 引入
+
+```ts
+import { Tags } from "@hsu-react/ui";
+```

package/src/components/Tags/index.module.less

@@ -0,0 +1,33 @@
+.tagsContainer {
+  --gap: 8;
+
+  display: inline-flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: calc(var(--gap) * 1px);
+  overflow: hidden;
+  width: 100%;
+
+  &.wrap {
+    flex-wrap: wrap;
+  }
+
+  &.alignLeft {
+    justify-content: flex-start;
+  }
+
+  &.alignCenter {
+    justify-content: center;
+  }
+
+  &.alignRight {
+    justify-content: flex-end;
+  }
+}
+
+.tag {
+  flex-shrink: 0;
+  margin: 0;
+
+  cursor: default;
+}