表格与表单

import {
  TableHeaderOperation,
  useTable,
  useTableOperate,
  useTableScroll
} from '@skyroc/web-ui-compose';
import type { TableColumn, TableDataWithIndex, TableSearchProps } from '@skyroc/web-ui-compose';

搜索表单 / 分页变化
  -> searchProps.search() / tableProps.onChange
  -> updateSearchParams({ current, size, ...fields })
  -> transformParams(params)          // 可选：参数规范化
  -> queryHook(params, { enabled, select })   // 你的 React Query hook
  -> transformer(response)            // 响应 -> { data, pageNum, pageSize, total }
  -> withTableIndex()                 // 自动补 index 序号
  -> tableProps.dataSource / pagination

index: (pageNum - 1) * pageSize + rowIndex + 1

import { useQuery } from '@tanstack/react-query';

import { fetchGetUserList } from './api';
import { SYSTEM_MANAGE_QUERY_KEYS } from './keys';

export function useUserListQuery<Data = Api.SystemManage.UserList>(
  params: Api.SystemManage.UserSearchParams,
  options?: ServiceQueryOptions<Api.SystemManage.UserList, Data>
) {
  return useQuery({
    ...options,
    queryFn: () => fetchGetUserList(params),
    queryKey: SYSTEM_MANAGE_QUERY_KEYS.USER_LIST(params)
  });
}

import { useAdminState } from '@skyroc/web-admin-layouts';
import { TableHeaderOperation, useTable, useTableOperate, useTableScroll } from '@skyroc/web-ui-compose';
import type { TableColumn, TableDataWithIndex } from '@skyroc/web-ui-compose';
import { useLocation, useNavigate } from '@tanstack/react-router';
import { Button, Card, Collapse, Popconfirm, Table, Tag } from 'antd';
import { Suspense, lazy } from 'react';
import { useTranslation } from 'react-i18next';

import { useUserListQuery } from '@/service/api/system-manage/hooks';

import UserSearch from './modules/UserSearch';
import { getUserSearchInitialParams, normalizeUserSearchParams } from './modules/shared';

const UserOperateDrawer = lazy(() => import('./modules/UserOperateDrawer'));

type UserTableRecord = TableDataWithIndex<Api.SystemManage.User>;

const UserManage = () => {
  const { t } = useTranslation();
  const navigate = useNavigate({ from: '/manage/user/' });
  const location = useLocation();
  const { isMobile } = useAdminState();
  const { scrollConfig, tableWrapperRef } = useTableScroll(1132);

  const { columnChecks, data, getData, searchProps, setColumnChecks, tableProps } = useTable({
    apiParams: getUserSearchInitialParams(),
    columns: createColumns,
    isMobile,
    onSearchParamsChange: syncSearchParams,
    pagination: { showQuickJumper: true },
    queryHook: useUserListQuery,
    routeSearch: location.searchStr,
    transformParams: normalizeUserSearchParams
  });

  const { checkedRowKeys, generalPopupOperation, handleAdd, handleEdit, onBatchDeleted, onDeleted, rowSelection } =
    useTableOperate<UserTableRecord>(data, getData);

  function syncSearchParams(params: Partial<Api.SystemManage.UserSearchParams>) {
    navigate({ search: () => params });
  }

  function createColumns(): TableColumn<UserTableRecord>[] {
    return [
      { align: 'center', dataIndex: 'index', fixed: 'left', key: 'index', title: t('common.index'), width: 64 },
      { align: 'center', dataIndex: 'userName', key: 'userName', minWidth: 120, title: t('page.manage.user.userName') },
      { align: 'center', dataIndex: 'nickName', key: 'nickName', minWidth: 120, title: t('page.manage.user.nickName') },
      {
        align: 'center',
        fixed: 'right',
        key: 'operate',
        render: (_, record) => (
          <div className="flex-center gap-8px">
            <Button ghost size="small" type="primary" onClick={() => handleEdit(record.id)}>
              {t('common.edit')}
            </Button>
            <Popconfirm title={t('common.confirmDelete')} onConfirm={onDeleted}>
              <Button danger size="small">
                {t('common.delete')}
              </Button>
            </Popconfirm>
          </div>
        ),
        title: t('common.operate'),
        width: 200
      }
    ];
  }

  return (
    <div className="h-full min-h-500px flex flex-col gap-16px overflow-hidden lt-sm:overflow-auto">
      <Collapse
        bordered={false}
        className="card-wrapper"
        defaultActiveKey={isMobile ? undefined : '1'}
        items={[{ children: <UserSearch {...searchProps} />, key: '1', label: t('common.search') }]}
      />

      <div className="min-h-0 flex flex-1 flex-col" ref={tableWrapperRef}>
        <Card
          className="min-h-0 flex flex-1 flex-col card-wrapper"
          extra={
            <TableHeaderOperation
              add={handleAdd}
              columns={columnChecks}
              disabledDelete={checkedRowKeys.length === 0}
              loading={tableProps.loading}
              refresh={getData}
              setColumnChecks={setColumnChecks}
              onDelete={onBatchDeleted}
            />
          }
          title={t('page.manage.user.title')}
          variant="borderless"
        >
          <Table rowSelection={rowSelection} scroll={scrollConfig} size="small" {...tableProps} />
          <Suspense fallback={null}>
            <UserOperateDrawer {...generalPopupOperation} />
          </Suspense>
        </Card>
      </div>
    </div>
  );
};

interface TableSearchProps<T> {
  form: FormInstance<T>;        // useTable 内部创建的 Form 实例
  reset: () => void;            // 重置表单并恢复到 apiParams
  search: (isResetCurrent?: boolean) => Promise<void>; // 提交查询
  searchParams: T;              // 当前已提交的查询参数（用作表单 initialValues）
}

const UserSearch = (props: TableSearchProps<Api.SystemManage.UserSearchParams>) => {
  const { form, reset, search, searchParams } = props;

  return (
    <Form form={form} initialValues={searchParams}>
      <Form.Item label="用户名" name="userName">
        <Input allowClear />
      </Form.Item>
      <Button onClick={reset}>重置</Button>
      <Button type="primary" onClick={() => search()}>
        查询
      </Button>
    </Form>
  );
};

useTable({
  columns: createColumns,
  queryHook: useUserListQuery,
  onChange(pagination, filters, sorter) {
    return {
      current: pagination.current,
      size: pagination.pageSize,
      sortField: Array.isArray(sorter) ? undefined : sorter.field,
      sortOrder: Array.isArray(sorter) ? undefined : sorter.order
    };
  }
});

// modules/shared.ts
export const UserSearchSchema = z.object({
  current: z.coerce.number().positive().catch(1).default(1),
  size: z.coerce.number().positive().catch(10).default(10),
  userName: z.string().nullish().catch(null).transform(v => v || null)
  // ...其余字段
});

export function normalizeUserSearchParams(params: Partial<Api.SystemManage.UserSearchParams>) {
  return UserSearchSchema.parse(params);
}

// index.tsx
export const Route = createFileRoute('/(admin)/manage/user/')({
  component: UserManage,
  validateSearch: UserSearchSchema
});

const {
  checkedRowKeys,        // 当前选中行 key
  rowSelection,          // 直接传给 Table 的行选择配置
  generalPopupOperation, // 传给新增/编辑抽屉的 props
  handleAdd,             // 打开新增抽屉
  handleEdit,            // 打开编辑抽屉，入参可以是 id 或整行数据
  onDeleted,             // 单条删除后的成功提示 + 刷新
  onBatchDeleted,        // 批量删除后清空选中 + 刷新
  editingData            // 当前编辑的行数据
} = useTableOperate<UserTableRecord>(data, getData);

interface GeneralPopupOperationProps<T> {
  form: FormInstance<T>;          // 与 useTableOperate 共享的表单实例
  handleSubmit: () => Promise<void>; // 校验并提交，成功后关闭抽屉 + 刷新
  onClose: () => void;            // 关闭抽屉并重置表单
  open: boolean;                  // 抽屉是否打开
  operateType: 'add' | 'edit';    // 当前操作类型
}

const { generalPopupOperation, handleAdd, handleEdit } = useTableOperate<UserTableRecord>(
  data,
  getData,
  async (res, operateType) => {
    if (operateType === 'add') {
      await fetchCreateUser(res);
    } else {
      await fetchUpdateUser(res);
    }
  }
);

const { scrollConfig, tableWrapperRef } = useTableScroll(1132);

// 容器 ref 包裹表格
<div ref={tableWrapperRef}>
  <Table scroll={scrollConfig} {...tableProps} />
</div>

useTable({
  apiParams: getBackendRouteSearchInitialParams(),
  columns: createColumns,
  defaultExpandAllRows: true, // 透传给 Table
  pagination: false,
  queryHook: useBackendRouteListQuery,
  routeSearch: location.searchStr,
  transformParams: normalizeMenuSearchParams
});