@skyroc/scripts 2.5.0

package/templates/admin-shell/ui/compose/table/hooks.ts

@@ -0,0 +1,196 @@
+import { useEffect, useRef, useState } from 'react';
+
+import type {
+  HookTableConfig,
+  HookTableResult,
+  PaginationData,
+  TableColumnCheck,
+  TableDataWithIndex
+} from './types';
+
+const DEFAULT_PAGE = 1;
+const DEFAULT_PAGE_SIZE = 10;
+
+/** 核心表格 Hook，负责查询参数、React Query 请求、分页结果和列设置状态。 */
+export function useHookTable<Params, Response, T, Column>(
+  config: HookTableConfig<Params, Response, T, Column>
+): HookTableResult<Params, T, Column> {
+  const {
+    apiParams,
+    columns: columnsFactory,
+    enabled = true,
+    getColumnChecks,
+    getColumns,
+    immediate = true,
+    isChangeURL = false,
+    onSearchParamsChange,
+    queryHook,
+    queryOptions,
+    resetParams,
+    transformer,
+    transformParams
+  } = config;
+
+  const initialSearchParamsRef = useRef(createSearchParams<Params>(apiParams));
+  const resetSearchParamsRef = useRef(createSearchParams<Params>(resetParams ?? apiParams));
+  const onFetchedRef = useRef(config.onFetched);
+
+  onFetchedRef.current = config.onFetched;
+
+  const [searchParams, setSearchParams] = useState<Partial<Params>>(initialSearchParamsRef.current);
+  const [queryEnabled, setQueryEnabled] = useState(immediate);
+  const [columnChecks, setColumnChecks] = useState<TableColumnCheck[]>(() => getColumnChecks(columnsFactory()));
+
+  const allColumns = columnsFactory();
+  const columns = getColumns(allColumns, columnChecks);
+  const requestParams = resolveRequestParams<Params>(searchParams, transformParams);
+
+  const query = queryHook<PaginationData<TableDataWithIndex<T>>>(requestParams, {
+    ...queryOptions,
+    enabled: enabled && queryEnabled,
+    select: response => {
+      return withTableIndex(transformer(response));
+    }
+  });
+
+  const paginationData = query.data ?? createEmptyPaginationData<T>();
+  const empty = !query.isFetching && paginationData.data.length === 0;
+  const loading = query.isFetching;
+
+  useEffect(() => {
+    if (!query.data) return;
+
+    const onFetched = onFetchedRef.current;
+
+    if (!onFetched) return;
+
+    Promise.resolve(onFetched(query.data)).catch(() => undefined);
+  }, [query.data]);
+
+  /** 重新请求当前查询。 */
+  async function getData() {
+    setQueryEnabled(true);
+    await query.refetch();
+  }
+
+  /** 合并更新查询参数。 */
+  function updateSearchParams(params: Partial<Params>) {
+    commitSearchParams({ ...searchParams, ...params });
+  }
+
+  /** 用默认参数重置查询。 */
+  function resetSearchParams() {
+    commitSearchParams(resetSearchParamsRef.current);
+  }
+
+  /** 重新生成列设置，并保留已有显隐、固定和排序偏好。 */
+  function reloadColumns() {
+    const nextChecks = getColumnChecks(columnsFactory());
+    setColumnChecks(mergeColumnChecks(columnChecks, nextChecks));
+  }
+
+  function commitSearchParams(nextParams: Partial<Params>) {
+    const formattedParams = formatSearchParams(nextParams);
+
+    setSearchParams(formattedParams);
+    setQueryEnabled(true);
+
+    if (isChangeURL) {
+      onSearchParamsChange?.(formattedParams);
+    }
+  }
+
+  return {
+    columnChecks,
+    columns,
+    data: paginationData.data,
+    empty,
+    getData,
+    loading,
+    pageNum: paginationData.pageNum,
+    pageSize: paginationData.pageSize,
+    query,
+    reloadColumns,
+    resetSearchParams,
+    searchParams,
+    setColumnChecks,
+    total: paginationData.total,
+    updateSearchParams
+  };
+}
+
+/** 移除查询参数中的空值，保留 false、0 和空字符串。 */
+export function formatSearchParams<T>(params: Partial<T> = {}) {
+  const entries = Object.entries(params as Record<string, unknown>).filter(([, value]) => {
+    return value !== null && value !== undefined;
+  });
+
+  return Object.fromEntries(entries) as Partial<T>;
+}
+
+function createSearchParams<T>(params?: Partial<T>) {
+  return formatSearchParams<T>({
+    current: DEFAULT_PAGE,
+    size: DEFAULT_PAGE_SIZE,
+    ...params
+  } as unknown as Partial<T>);
+}
+
+function resolveRequestParams<Params>(
+  searchParams: Partial<Params>,
+  transformParams?: (params: Params) => Params
+) {
+  const formattedParams = formatSearchParams(searchParams) as Params;
+
+  if (!transformParams) {
+    return formattedParams;
+  }
+
+  return transformParams(formattedParams);
+}
+
+function createEmptyPaginationData<T>(): PaginationData<TableDataWithIndex<T>> {
+  return {
+    data: [],
+    pageNum: DEFAULT_PAGE,
+    pageSize: DEFAULT_PAGE_SIZE,
+    total: 0
+  };
+}
+
+function withTableIndex<T>(data: PaginationData<T>): PaginationData<TableDataWithIndex<T>> {
+  const { data: records, pageNum, pageSize, total } = data;
+
+  return {
+    data: records.map((item, index) => {
+      return {
+        ...item,
+        index: (pageNum - 1) * pageSize + index + 1
+      } as TableDataWithIndex<T>;
+    }),
+    pageNum,
+    pageSize,
+    total
+  };
+}
+
+function mergeColumnChecks(currentChecks: TableColumnCheck[], nextChecks: TableColumnCheck[]) {
+  const currentMap = new Map(currentChecks.map(item => [item.key, item]));
+  const orderMap = new Map(currentChecks.map((item, index) => [item.key, index]));
+  const fallbackOrder = nextChecks.length;
+
+  return nextChecks
+    .map((item, index) => {
+      const current = currentMap.get(item.key);
+
+      return {
+        ...item,
+        checked: current?.checked ?? item.checked,
+        fixed: current?.fixed ?? item.fixed,
+        visible: current?.visible ?? item.visible,
+        __order: orderMap.get(item.key) ?? fallbackOrder + index
+      };
+    })
+    .toSorted((a, b) => a.__order - b.__order)
+    .map(({ __order: _order, ...item }) => item);
+}

package/templates/admin-shell/ui/compose/table/index.ts

@@ -0,0 +1,16 @@
+// 导出组件
+export { default as DragContent } from './DragContent';
+export * from './hooks';
+export { default as TableHeaderOperation } from './TableHeaderOperation';
+
+/**
+ * Table Features
+ *
+ * 提供完整的表格功能模块
+ */
+
+export * from './types';
+export * from './use-table';
+
+export * from './use-table-operate';
+export * from './use-table-scroll';

package/templates/admin-shell/ui/compose/table/types.ts

@@ -0,0 +1,244 @@
+import type { QueryKey, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import type { FormInstance, TablePaginationConfig, TableProps } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import type { Key, ReactNode } from 'react';
+
+/** 表格接口函数类型。 */
+export type TableApiFn<Params = any, Response = PaginatingQueryRecord<any>> = (params: Params) => Promise<Response>;
+
+/** 后端分页列表的最小结构。 */
+export interface PaginatingQueryRecord<T = any> {
+  /** 当前页码。 */
+  current: number;
+  /** 数据列表。 */
+  records: T[];
+  /** 每页条数。 */
+  size: number;
+  /** 总条数。 */
+  total: number;
+}
+
+/** 从分页接口响应中提取列表项类型。 */
+export type GetTableData<A extends TableApiFn> =
+  Awaited<ReturnType<A>> extends PaginatingQueryRecord<infer T> ? T : never;
+
+/** 从分页接口响应类型中提取列表项类型。 */
+export type GetTableDataFromResponse<Response> = Response extends PaginatingQueryRecord<infer T> ? T : never;
+
+/** 带序号的表格行数据。 */
+export type TableDataWithIndex<T> = T & {
+  /** 当前查询结果中的连续序号。 */
+  index: number;
+};
+
+/** Ant Design 表格列定义。 */
+export type TableColumn<T = any> = ColumnsType<T>[number];
+
+/** 表格列固定位置。 */
+export type TableColumnFixed = 'left' | 'right' | 'unFixed';
+
+/** 列设置面板中展示的列标题。 */
+export type TableColumnCheckTitle = ReactNode | ((...args: any[]) => ReactNode);
+
+/** 表格列设置项。 */
+export interface TableColumnCheck {
+  /** 列是否参与表格渲染。 */
+  checked: boolean;
+  /** 列固定到左侧、右侧，或取消固定。 */
+  fixed: TableColumnFixed;
+  /** 列的稳定唯一标识。 */
+  key: string;
+  /** 列设置面板中展示的标题。 */
+  title: TableColumnCheckTitle;
+  /** 列是否出现在列设置面板中。 */
+  visible: boolean;
+}
+
+/** 标准分页数据。 */
+export interface PaginationData<T = any> {
+  /** 当前页数据。 */
+  data: T[];
+  /** 当前页码。 */
+  pageNum: number;
+  /** 每页条数。 */
+  pageSize: number;
+  /** 总条数。 */
+  total: number;
+}
+
+/** 表格操作类型。 */
+export type TableOperateType = 'add' | 'edit';
+
+/** 表格行基础数据。 */
+export interface TableData {
+  /** 表格行的稳定业务主键。 */
+  id: Key;
+  /** 业务字段。 */
+  [key: string]: any;
+}
+
+/** 表格变化回调参数。 */
+export type TableOnChange<T = any> = Parameters<NonNullable<TableProps<T>['onChange']>>;
+
+/** 根据请求参数生成 React Query key。 */
+export type TableQueryKeyBuilder<A extends TableApiFn> = (params: Parameters<A>[0]) => QueryKey;
+
+/** 表格查询 Hook 可接收的 React Query 配置。 */
+export type TableQueryHookOptions<Response, Data = Response> = Omit<
+  UseQueryOptions<Response, Error, Data, QueryKey>,
+  'queryFn' | 'queryKey'
+>;
+
+/** 表格查询 Hook 类型，消费侧负责声明 queryKey 和 queryFn。 */
+export type TableQueryHook<Params, Response> = <Data = Response>(
+  params: Params,
+  options?: TableQueryHookOptions<Response, Data>
+) => UseQueryResult<Data, Error>;
+
+/** React Query 配置，enabled/select/queryKey/queryFn 由表格 Hook 和查询 Hook 接管。 */
+export type TableQueryOptions<Response, T> = Omit<
+  TableQueryHookOptions<Response, PaginationData<TableDataWithIndex<T>>>,
+  'enabled' | 'queryFn' | 'queryKey' | 'select'
+>;
+
+/** 核心表格 Hook 配置。 */
+export interface HookTableConfig<Params, Response, T, Column> {
+  /** 初始查询参数，通常包含分页和查询表单默认值。 */
+  apiParams?: Partial<Params>;
+  /** 表格列工厂，允许消费侧按权限或国际化重新生成列。 */
+  columns: () => Column[];
+  /** 外部业务是否允许发起查询。 */
+  enabled?: boolean;
+  /** 从列定义生成列设置项。 */
+  getColumnChecks: (columns: Column[]) => TableColumnCheck[];
+  /** 根据列设置项生成最终渲染列。 */
+  getColumns: (columns: Column[], checks: TableColumnCheck[]) => Column[];
+  /** 是否首次挂载后立即请求。 */
+  immediate?: boolean;
+  /** 是否把提交后的查询参数同步给外部路由。 */
+  isChangeURL?: boolean;
+  /** 查询完成后的业务回调。 */
+  onFetched?: (data: PaginationData<TableDataWithIndex<T>>) => Promise<void> | void;
+  /** 查询参数变化时的外部同步回调。 */
+  onSearchParamsChange?: (params: Partial<Params>) => void;
+  /** 根据当前查询参数创建 React Query 查询。 */
+  queryHook: TableQueryHook<Params, Response>;
+  /** 透传给 React Query 的附加配置。 */
+  queryOptions?: TableQueryOptions<Response, T>;
+  /** 重置查询时使用的参数。 */
+  resetParams?: Partial<Params>;
+  /** 把接口响应转换成标准分页数据。 */
+  transformer: (response: Response) => PaginationData<T>;
+  /** 接口请求前的参数转换。 */
+  transformParams?: (params: Params) => Params;
+}
+
+/** 核心表格 Hook 返回值。 */
+export interface HookTableResult<Params, T, Column> {
+  /** 可配置的列设置项。 */
+  columnChecks: TableColumnCheck[];
+  /** 最终传给表格组件的列。 */
+  columns: Column[];
+  /** 当前页数据。 */
+  data: TableDataWithIndex<T>[];
+  /** 当前查询是否为空结果。 */
+  empty: boolean;
+  /** 重新请求当前查询。 */
+  getData: () => Promise<void>;
+  /** 当前查询是否正在请求。 */
+  loading: boolean;
+  /** 当前页码。 */
+  pageNum: number;
+  /** 每页条数。 */
+  pageSize: number;
+  /** 底层 React Query 查询结果。 */
+  query: UseQueryResult<PaginationData<TableDataWithIndex<T>>, Error>;
+  /** 重新从列工厂生成列设置项，并保留用户设置。 */
+  reloadColumns: () => void;
+  /** 用默认参数重置查询。 */
+  resetSearchParams: () => void;
+  /** 当前已提交的查询参数。 */
+  searchParams: Partial<Params>;
+  /** 更新列设置项。 */
+  setColumnChecks: (checks: TableColumnCheck[]) => void;
+  /** 总条数。 */
+  total: number;
+  /** 合并更新查询参数。 */
+  updateSearchParams: (params: Partial<Params>) => void;
+}
+
+/** 表格配置。 */
+export interface TableConfig<Params, Response, T = GetTableDataFromResponse<Response>>
+  extends Omit<
+    TableProps<TableDataWithIndex<T>>,
+    'columns' | 'dataSource' | 'loading' | 'onChange' | 'pagination' | 'rowKey'
+  > {
+  /** 接口默认查询参数。 */
+  apiParams?: Partial<Params>;
+  /** Ant Design 表格列工厂。 */
+  columns: () => TableColumn<TableDataWithIndex<T>>[];
+  /** 外部业务是否允许发起查询。 */
+  enabled?: boolean;
+  /** 判断列是否出现在列设置面板中。 */
+  getColumnVisible?: (column: TableColumn<TableDataWithIndex<T>>) => boolean;
+  /** 是否首次挂载后立即请求。 */
+  immediate?: boolean;
+  /** 是否读取并同步路由查询参数。 */
+  isChangeURL?: boolean;
+  /** 是否使用移动端简洁分页。 */
+  isMobile?: boolean;
+  /** 表格分页、筛选、排序变化回调。 */
+  onChange?: (...args: TableOnChange<TableDataWithIndex<T>>) => Partial<Params> | void;
+  /** 查询完成后的业务回调。 */
+  onFetched?: (data: PaginationData<TableDataWithIndex<T>>) => Promise<void> | void;
+  /** 查询参数变化时的外部路由同步回调。 */
+  onSearchParamsChange?: (params: Partial<Params>) => void;
+  /** 分页配置；传 false 可关闭分页。 */
+  pagination?: false | TablePaginationConfig;
+  /** 根据当前查询参数创建 React Query 查询。 */
+  queryHook: TableQueryHook<Params, Response>;
+  /** 透传给 React Query 的附加配置。 */
+  queryOptions?: TableQueryOptions<Response, T>;
+  /** 当前路由查询字符串，用于初始化查询参数。 */
+  routeSearch?: string;
+  /** Ant Design 表格行 key。 */
+  rowKey?: TableProps<TableDataWithIndex<T>>['rowKey'];
+  /** 是否展示总数。 */
+  showTotal?: boolean;
+  /** 把接口响应转换成标准分页数据。 */
+  transformer?: (response: Response) => PaginationData<T>;
+  /** 接口请求前的参数转换。 */
+  transformParams?: (params: Params) => Params;
+}
+
+/** 自定义表格 Props。 */
+export type CustomTableProps<T> = Omit<TableProps<TableDataWithIndex<T>>, 'loading'> & {
+  /** 当前表格是否展示加载状态。 */
+  loading: boolean;
+};
+
+/** 表格搜索 Props。 */
+export interface TableSearchProps<T = any> {
+  /** Ant Design 表单实例。 */
+  form: FormInstance<T>;
+  /** 重置查询表单。 */
+  reset: () => void;
+  /** 提交查询表单。 */
+  search: (isResetCurrent?: boolean) => Promise<void>;
+  /** 当前已提交的查询参数。 */
+  searchParams: T;
+}
+
+/** 通用弹窗操作 Props。 */
+export interface GeneralPopupOperationProps<T extends TableData = TableData> {
+  /** Ant Design 表单实例。 */
+  form: FormInstance<T>;
+  /** 提交弹窗表单。 */
+  handleSubmit: () => Promise<void>;
+  /** 关闭弹窗。 */
+  onClose: () => void;
+  /** 弹窗是否打开。 */
+  open: boolean;
+  /** 当前操作类型。 */
+  operateType: TableOperateType;
+}

package/templates/admin-shell/ui/compose/table/use-table-operate.ts

@@ -0,0 +1,136 @@
+import { useBoolean } from 'ahooks';
+import { Form, message } from 'antd';
+import type { TableProps } from 'antd';
+import { useState } from 'react';
+import type { Key } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { TableData, TableOperateType } from './types';
+
+/**
+ * 表格操作Hook
+ *
+ * 提供表格常用操作功能： - 添加/编辑抽屉管理 - 表格行选择 - 删除操作
+ */
+export function useTableOperate<T extends TableData = TableData>(
+  data: T[],
+  getData: (isResetCurrent?: boolean) => Promise<void>,
+  executeResActions?: (res: T, operateType: TableOperateType) => void | Promise<void>
+) {
+  const { t } = useTranslation();
+
+  // 抽屉可见性状态
+  const [drawerVisible, { setFalse: closeDrawer, setTrue: openDrawer }] = useBoolean();
+
+  // 操作类型：添加或编辑
+  const [operateType, setOperateType] = useState<TableOperateType>('add');
+
+  // 表单实例
+  const [form] = Form.useForm<T>();
+
+  /** 正在编辑的数据 */
+  const [editingData, setEditingData] = useState<T>();
+
+  /** 处理添加操作 */
+  function handleAdd() {
+    setOperateType('add');
+    setEditingData(undefined);
+    form.resetFields();
+    openDrawer();
+  }
+
+  /**
+   * 处理编辑操作
+   *
+   * @param idOrData - 数据ID或完整数据对象
+   */
+  function handleEdit(idOrData: T['id'] | T) {
+    if (typeof idOrData === 'object') {
+      form.setFieldsValue(idOrData);
+      setEditingData(idOrData);
+    } else {
+      const findItem = data.find(item => item.id === idOrData);
+      if (findItem) {
+        form.setFieldsValue(findItem);
+        setEditingData(findItem);
+      }
+    }
+
+    setOperateType('edit');
+    openDrawer();
+  }
+
+  /** 选中的行keys */
+  const [checkedRowKeys, setCheckedRowKeys] = useState<Key[]>([]);
+
+  /** 行选择变化处理 */
+  function onSelectChange(keys: Key[]) {
+    setCheckedRowKeys(keys);
+  }
+
+  /** 行选择配置 */
+  const rowSelection: TableProps<T>['rowSelection'] = {
+    columnWidth: 48,
+    fixed: true,
+    onChange: onSelectChange,
+    selectedRowKeys: checkedRowKeys,
+    type: 'checkbox'
+  };
+
+  /** 关闭抽屉 */
+  function onClose() {
+    closeDrawer();
+    form.resetFields();
+    setEditingData(undefined);
+  }
+
+  /** 批量删除完成后的回调 */
+  async function onBatchDeleted() {
+    message.success(t('common.deleteSuccess'));
+    setCheckedRowKeys([]);
+    await getData(false);
+  }
+
+  /** 单个删除完成后的回调 */
+  async function onDeleted() {
+    message.success(t('common.deleteSuccess'));
+    await getData(false);
+  }
+
+  /** 提交表单 */
+  async function handleSubmit() {
+    const res = await form.validateFields();
+
+    if (executeResActions) {
+      // 执行业务逻辑
+      await executeResActions(res, operateType);
+    }
+
+    message.success(t('common.updateSuccess'));
+
+    onClose();
+    await getData();
+  }
+
+  return {
+    checkedRowKeys,
+    closeDrawer,
+    drawerVisible,
+    editingData,
+    generalPopupOperation: {
+      form,
+      handleSubmit,
+      onClose,
+      open: drawerVisible,
+      operateType
+    },
+    handleAdd,
+    handleEdit,
+    onBatchDeleted,
+    onDeleted,
+    onSelectChange,
+    openDrawer,
+    operateType,
+    rowSelection
+  };
+}

package/templates/admin-shell/ui/compose/table/use-table-scroll.ts

@@ -0,0 +1,49 @@
+import { useSize } from 'ahooks';
+import { useRef } from 'react';
+
+/**
+ * 表格滚动配置Hook
+ *
+ * 自动计算表格滚动区域的宽度和高度
+ *
+ * @param scrollX - 表格最小宽度，默认702
+ * @returns 滚动配置和容器ref
+ */
+export function useTableScroll(scrollX: number = 702) {
+  const tableWrapperRef = useRef<HTMLDivElement>(null);
+
+  const size = useSize(tableWrapperRef);
+
+  /** 获取表格滚动的Y轴高度 */
+  function getTableScrollY() {
+    const height = size?.height;
+
+    if (!height) return undefined;
+
+    // 减去表格头部、分页等组件的高度
+    return height - 160;
+  }
+
+  const scrollConfig = {
+    x: scrollX,
+    y: getTableScrollY()
+  };
+
+  return {
+    scrollConfig,
+    tableWrapperRef
+  };
+}
+
+/**
+ * 计算表格列的总宽度
+ *
+ * @param columns - 表格列配置
+ * @param minWidth - 列的最小宽度，默认120
+ * @returns 总宽度
+ */
+export function getTableScrollX(columns: any[], minWidth: number = 120): number {
+  return columns.reduce((acc, column) => {
+    return acc + Number(column.width ?? column.minWidth ?? minWidth);
+  }, 0);
+}