# easy-table LLMs.txt

> 供 LLM 快速理解 `@flatbiz/antd/easy-table` 的使用方式。

## 模块定位

对 查询条件+表格数据 进行深度封装，内置数据交互处理

## 导入方式

```ts
import { EasyTable } from '@flatbiz/antd/easy-table';
// 也可以从主入口导入：import { ... } from '@flatbiz/antd';
```

## 公开导出

- `filterCache`
- `firstQueryCache`
- `columnFoldCache`
- `EasyTableContext`
- `EditableFieldContextContextApi`
- `EasyTable`
- `EasyTableFilter` - 过滤条件
- `EasyTableFilterProps`
- `FoldOperateDropdown`
- `FoldOperate`
- `useColumnsAppendTips`
- `useColumnsAppendInnerColumn`
- `useColumnsToHidden`
- `useColumnByAsyncColumnRequest`
- `useEasyTable` - 在 EasyTable子组件内才可使用
- `EasyTableTable` - 表格渲染
- `EasyTableTableProps`
- `TEasyTableTableColumn`
- `EasyTableServiceConfig`
- `EasyTableProps`
- `EasyTableRefApi`
- `getFormFieldsValue`
- `requestParamsInternalAdapter` - 请求参数内部转换处理

## 依赖的 antd 能力

`Badge`、`Checkbox`、`Drawer`、`Empty`、`Form`、`FormInstance`、`message`、`Popover`、`Space`、`Table`

## Props / 配置要点

### EditableFieldContextContextApi

- `cacheKey`（必填）：: string
- `onRequest`（可选）：: (params?: TPlainObject) => void
- `tableDataSource`（可选）：: TPlainObject[]
- `tableTotal`（必填）：: number
- `loading`（可选）：: boolean
- `fieldNames`（必填）：: TPlainObject
- `pageSize`（必填）：: number
- `initialValues`（可选）：: TPlainObject
- `onSetPaginationStatus`（必填）：: (status: boolean) => void
- `getPaginationStatus`（必填）：: () => boolean
- `onFormFinish`（可选）：: (values?: TPlainObject) => void
- `form`（必填）：: FormInstance
- `getEasyTableRef`（必填）：: () => EasyTableRefApi
- `paginationFixed`（必填）：: boolean
- `foldKeys`（必填）：: string[]
- `onSetBaseColumns`（可选）：: ( baseColumns?: TEasyTableTableColumn<TPlainObject>[] ) => void
- `onSetColumns`（可选）：: (columns?: TEasyTableTableColumn<TPlainObject>[]) => void
- `columns`（可选）：: TEasyTableTableColumn<TPlainObject>[]
- `dynamicColumnsConfig`（可选）：: { showFoldKeyList: string[]; onChangeShowFoldKeyList: (keys: string[]) => void; columnFoldOpen: boolean; columnFoldConfig?: EasyTableProps['columnFoldConfig'…
- `filterFormItemKeys`（可选）：: string[]
- `showCancelInitRequestTips`（可选）：: boolean

### EasyTableFilterProps

- `children`（必填）：: | ReactElement | ReactElement[] | ((form: FormInstance) => ReactElement)
- `filterOperate`（可选）：: (form: FormInstance) => FormOperateColProps；isPure = true时无效
- `isPure`（可选）：: boolean；是否为纯净模式（查询条件布局是否自定义），
- `queryButtonProps`（可选）：: Omit<ButtonWrapperProps, 'onClick'> & { text?: string }；查询按钮配置
- `resetButtonProps`（可选）：: Omit<ButtonWrapperProps, 'onClick'> & { text?: string }；重置按钮配置
- `formClassName`（可选）：: string；@deprecated已过期，使用 easyFormProps.className 配置
- `formStyle`（可选）：: CSSProperties；@deprecated已过期，使用 easyFormProps.style 配置
- `filterWrapperStyle`（可选）：: CSSProperties；filter Form 外层 BlockLayout style
- `filterWrapperClassName`（可选）：: string；filter Form 外层 BlockLayout className
- `rightOperateAreaAppendType`（可选）：: 'cover' | 'beforeAppend' | 'afterAppend'；自定义 filterOperate.rightList 后 默认【查询、重置】按钮处理逻辑 1. cover：覆盖内部查询重置按钮（默认值） 2. beforeAppend：添加到【查询重置】按钮前面 3. afterAppend：添加到【查询重置】按钮后面 如果想隐藏【查询、重置】按钮中的某一个，可设置 queryButtonProps.hidden、resetButtonProps.hidden
- `defaultResetButtonTriggerRequest`（可选）：: boolean；默认重启按钮触发请求，默认值：true
- `easyFormProps`（可选）：: Omit< EasyFormProps, 'isPure' | 'column' | 'forceColumn' | 'width' | 'gridGutter' | 'children' >

### FoldOperateProps

- `style`（可选）：: CSSProperties
- `dataList`（必填）：: { dataIndex: string; title: string }[]
- `onChange`（必填）：: (keys: string[]) => void
- `cacheKey`（可选）：: string
- `initSelectedRowKeys`（可选）：: string[]
- `children`（可选）：: ReactElement

### FoldOperateProps

- `style`（可选）：: CSSProperties
- `dataList`（可选）：: { dataIndex?: string; title: string }[]
- `onChange`（必填）：: (keys: string[]) => void
- `open`（可选）：: boolean
- `onClose`（可选）：: () => void
- `cacheKey`（可选）：: string
- `initSelectedRowKeys`（可选）：: string[]

### EasyTableTableProps

- `children`（可选）：: ReactElement | ReactElement[]
- `rowKey`（必填）：: TableProps<TAny>['rowKey']；表格行 key 的取值，
- `tableWrapperStyle`（可选）：: CSSProperties；table Form 外层 SimpleLayout className
- `tableWrapperClassName`（可选）：: string；table Form 外层 SimpleLayout className
- `columns`（必填）：: TEasyTableTableColumn<T>[]
- `isSync`（可选）：: boolean；数据加载与表格初始化渲染 是否同步 @version 4.4.6
- `emptyShowSize`（可选）：: 'small' | 'large'；空效果显示尺寸，默认值：small @version 4.4.6
- `title`（可选）：: ReactNode；标题
- `actions`（可选）：: ReactElement[]；与标题对齐的动作
- `tableButtomExtraContent`（可选）：: ReactElement；表格底部额外内容

### TEasyTableTableColumn

- `dataIndex`（可选）：: keyof T | (string & {})
- `tipsWrapperProps`（可选）：: string | TipsWrapperProps；会在 title 之后展示一个 icon
- `hidden`（可选）：: boolean；是否隐藏
- `isFold`（可选）：: boolean；是否折叠在更多中
- `asyncRender`（可选）：: ( value: TAny, record: T, index: number, respData?: TAny ) => ReactNode；异步数据渲染，与asyncColumnRequest配合使用
- `defaultValue`（可选）：: string；设置默认值，当数据为【undefined、null、''】时显示；自定义render后失效

### EasyTableServiceConfig

- `onRequest`（可选）：: (params?: TPlainObject) => Promise<TPlainObject | TPlainObject[]>；接口配置
- `requestParamsAdapter`（可选）：: ( params: TPlainObject, originalParams: TPlainObject ) => TPlainObject；请求参数处理
- `requestResultAdapter`（可选）：: (params: TAny) => TPlainObject；接口相应数据处理
- `dynamicColumsAdapter`（可选）：: ( respData?: TAny, columns?: TEasyTableTableColumn<TPlainObject>[] ) => TEasyTableTableColumn<TPlainObject>[] | undefined；动态列自定义渲染

### EasyTableProps

- `className`（可选）：: string
- `style`（可选）：: CSSProperties
- `children`（可选）：: | ReactElement | ReactElement[] | ((dataSource?: TAny) => ReactElement)
- `modelKey`（可选）：: string；EasyTable唯一值，可用于缓存查询条件 @deprecated 已过时，如果需要缓存数据请设置 cacheKey 参数
- `cacheKey`（可选）：: string；缓存key
- `serviceConfig`（必填）：: EasyTableServiceConfig；接口数据配置
- `initialValues`（可选）：: TPlainObject；1. 查询条件Form initialValues 2. 接口其他参数，例如常量类型
- `pageSize`（可选）：: number；分页单页条数，默认值：10
- `fieldNames`（可选）：: { list?: string; total?: string; pageNo?: string; pageSize?: string; }；字段映射，默认值：{ list:'list', total:'total', pageNo:'pageNo', pageSize:'pageSize' }
- `initRequest`（可选）：: boolean；初始化是否请求，默认值：true；必须配合 cacheKey 一起使用 @deprecated 已过时，请使用 cancelInitAutoRequest、alwaysCancelInitAutoRequest 参数
- `cancelInitAutoRequest`（可选）：: boolean | (() => boolean)；取消初始化自动请求
- `alwaysCancelInitAutoRequest`（可选）：: boolean | (() => boolean)；永久关闭任何初始请求，任何情况下都不会自动发起初始请求。
- `onDataSourceChange`（可选）：: (dataSource: TAny) => void；表格数据变更回调
- `onFormFinish`（可选）：: (values?: TPlainObject) => void；如果自定义查询按钮，可设置 Form onFinish
- `isFull`（可选）：: boolean；在父节点高度下，上下铺满；默认值：true
- `paginationFixed`（可选）：: boolean；分页区域固定，不随滚动条滚动
- `pagination`（可选）：: PaginationProps；1. 配合paginationFixed=true一起使用有效果 2. 当使用Table内的pagination时，在EasyTable.Table中配置分页属性
- `foldKeys`（可选）：: string[]；查询条件展开、收起，被收起key数组；数组内容为EasyTable.Filter 子节点key值
- `onRequestErrorHandle`（可选）：: (error) => void；自定义处理服务异常
- `isInline`（可选）：: boolean；是否inline模式
- `form`（可选）：: FormInstance；Form 实例
- `columnFoldConfig`（可选）：: { initSelectedKeys?: string[]; hidden?: boolean; icon?: ReactElement; text?: string; hoverTipText?: string; onChange?: (keys: string[]) => void; triggerType?…；字段折叠配置
- `asyncColumnRequest`（可选）：: { dataIndex: string; onRequest: () => Promise<TAny>; }[]；配置表格列中需要异步请求数据
- `breforeRequest`（可选）：: (form: FormInstance) => Promise<void>；调用接口前自定义判断，返回Promise.resolve才能发起查询操作
- `filterFormItemKeys`（可选）：: string[]；指定查询条件验证的formItemKeys，设置后条件回车查询事件失效
- `removeRequestParamsEmptyValue`（可选）：: boolean；移除请求参数中值为空字符串、null、undefined 的key值，默认值：true
- `fixedFooterExtraContent`（可选）：: { top?: ReactElement; bottom?: ReactElement; }；固定底部额外内容，当 paginationFixed=true 时有效，与分页水平对齐

## 使用规则与行为

- 不要添加默认值
- 缓存的优先级高于 initialValues
- isPure = true时无效
- 是否为纯净模式（查询条件布局是否自定义），
- 查询按钮配置
- 重置按钮配置
- 网格布局设置 default = { xs: 24, sm: 12, md: 12, lg: 8, xl: 8, xxl: 6 }; small = { xs: 24, sm: 8, md: 8, lg: 6, xl: 6, xxl: 6 };
- filter Form 外层 BlockLayout style
- filter Form 外层 BlockLayout className
- 默认重启按钮触发请求，默认值：true

## 默认值线索

- `removeRequestParamsEmptyValue => true`

## 基础示例

```tsx
import { EasyTable, type EasyTableFilterProps } from '@flatbiz/antd/easy-table';

const props: EasyTableFilterProps = {
  // 按业务传入必要参数
};

<EasyTable {...props} />;
```

## 源码索引

- `src/easy-table/cache.ts`
- `src/easy-table/context.ts`
- `src/easy-table/easy-table.tsx`
- `src/easy-table/filter.tsx`
- `src/easy-table/fold-operate-dropdown.tsx`
- `src/easy-table/fold-operate.tsx`
- `src/easy-table/hooks/columns.tsx`
- `src/easy-table/hooks.ts`
- `src/easy-table/index.ts`
- `src/easy-table/table.tsx`
- `src/easy-table/type.ts`
- `src/easy-table/utils.test.ts`
- `src/easy-table/utils.ts`

## 给 LLM 的注意事项

- 优先使用 `@flatbiz/antd/easy-table` 或主入口 `@flatbiz/antd` 的公开导出，不要引用内部实现文件。
- 当 Props 与 antd 原组件同名能力冲突时，以本模块导出的 Props 类型为准。
- 若文档未覆盖某个边缘参数，请读取上方源码索引中的类型定义和 JSDoc。