Skip to main content

useTable

基于 Table 进行扩展的渲染业务列表 hooks，包括以下功能：

  • 列表数据请求相关：
    • 首次请求
    • 定时/手动刷新请求
    • 翻页请求
    • 搜索请求
    • 排序请求
    • 过滤请求
  • 列表操作相关：
    • 新建按钮
    • 批量操作按钮
    • 表格单项操作

功能说明​

  • 列表数据请求相关：这些部分一般只是改变列表请求的参数然后进行再请求一次。
  • 列表操作相关：这些部分一般是触发新的交互页面（表单、跳转、对话框等），后续再触发跟列表请求无关的新的请求。
与 useList 的区别
  • 更灵活的配置项：useTable 比 useList 支持更多基础组件参数的传入
  • 更统一的配置项：useTable 统一了 command 部分不同 actionType 下参数配置结构
  • 更精简的代码：useTable 精简了代码文件结构（useList 由于 createBaseList 的原因，文件引用复杂）

引入​

import {request, useTable, HooksTable} from '@baidu/acud-pro-components';

基本用法​

  1. options：可以接收三个参数的方法，用于动态配置组件所需配置项；
  2. props：options 方法中需要用到的一些参数；
  3. customFunctions：options 方法中需要用到的一些方法。
function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = () => {
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    }
                ]
            }
        };
    };

    const List = props => {
        const listProps = useTable(options, props);
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

不可选择​

配置 options > select 为 none 可以关闭表格的默认可选状态。

function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = () => {
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            select: 'none',
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    }
                ]
            }
        };
    };

    const List = props => {
        const listProps = useTable(options, props);
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

表格操作​

配置 options > tableConfig > columns > render 自定义表格操作。

function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = (props, handleTableCommand) => {
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            select: 'none',
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    },
                    {
                        title: '操作',
                        key: 'action',
                        width: 210,
                        render: payload => (
                            <>
                                <a className="table-action" onClick={() => handleTableCommand('LINK', payload)}>详情</a>
                                <a className="table-action" onClick={() => handleTableCommand('DIALOG', payload)}>编辑</a>
                                <a className="table-action" onClick={() => handleTableCommand('DIALOG', payload)}>对话框</a>
                                <a className="table-action" onClick={() => handleTableCommand('DRAWER', payload)}>抽屉</a>
                                <a className="table-action" disabled>删除</a>
                            </>
                        )
                    }
                ]
            }
        };
    };

    const List = props => {
        const listProps = useTable(options, props);
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

排序和筛选​

  • 配置 options > tableConfig > columns > sorter 可以对表格进行排序；
  • 配置 options > tableConfig > columns > filters 可以对表格进行筛选，filters 是一个数组，包含要筛选的信息。
function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = () => {
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    },
                    {
                        key: 'createTime',
                        title: '创建时间',
                        dataIndex: 'createTime',
                        sorter: true,
                        render: createTime => {
                            return timeUtil.toTime(createTime, '-');
                        }
                    },
                    {
                        key: 'departmentIDs',
                        title: '部门',
                        dataIndex: 'departmentName',
                        filters: [
                            {text: '部门1', value: 'department1'},
                            {text: '部门2', value: 'department2'}
                        ]
                    },
                ]
            }
        };
    };

    const List = props => {
        const listProps = useTable(options, props);
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

配置操作区​

配置 options > bulkConfig 属性来开启操作区，具体可配置项见 API - IBulkItemConfig

function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = () => {
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            bulkConfig: [
                {
                    id: 'createProject',
                    skin: 'primary',
                    icon: <OutlinedPlus />,
                    text: '创建项目',
                    actionType: 'link',
                    link: '/project/create'
                }
            ],
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    }
                ]
            }
        };
    };

    const List = props => {
        const listProps = useTable(options, props);
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

自定义操作区​

配置 options > bulkComp 属性来自定义操作区，优先级高于上面的 bulkConfig。

function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = props => {
        const {bulkComp} = props;
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            bulkComp,
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    }
                ]
            }
        };
    };

    const bulkComp = () => (
        <Button
            type="primary"
            icon={<OutlinedPlus />}
            onClick={() => console.log('create')}
        >
            创建项目
        </Button>
    );

    const List = props => {
        const listProps = useTable(options, {...props, bulkComp});
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

配置筛选区​

配置 options > filterConfig 属性来开启筛选区，具体可配置项见 API - IFilterConfig

function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = (props, handleTableCommand, customFunctions) => {
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            filterConfig: {
                controls: [
                    {
                        name: 'keyword',
                        control: Search,
                        controlProps: {
                            allowClear: true,
                            placeholder: '请输入项目名称搜索',
                            onSearch: keyword => customFunction.handleFilterChange({keyword})
                        }
                    },
                    {
                        id: 'refresh',
                        icon: <OutlinedRefresh />,
                        actionType: 'custom',
                        action: 'loadList',
                        position: 'right'
                    }
                ]
            },
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    }
                ]
            }
        };
    };

    const customFunction = {
        handleFilterChange: key => console.log(key, 'search')
    };

    const List = () => {
        const listProps = useTable(options, {}, customFunction);
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

自定义筛选区​

配置 options > filterComp 属性来自定义筛选区，优先级高于上面的 filterConfig。

function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const options = props => {
        const {filterComp} = props;
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            filterComp,
            tableConfig: {
                columns: [
                    {
                        key: 'name',
                        title: '名称',
                        dataIndex: 'name'
                    },
                    {
                        key: 'creator',
                        title: '创建人',
                        dataIndex: 'creator'
                    }
                ]
            }
        };
    };

    const filterComp = () => (
        <div className="acud-hooks-table-toolbar-filter">
            <Search
                placeholder="请输入项目名称"
                onSearch={nameFilter => console.log(nameFilter, 'search')}
            />
            <Button
                icon={<OutlinedRefresh />}
                onClick={() => console.log('refresh')}
            />
        </div>
    );

    const List = props => {
        const listProps = useTable(options, {...props, filterComp});
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

卡片式列表​

配置 options > card 属性来展示卡片式列表。

function App(props) {
    const listUrl = 'https://yapi.baidu-int.com/mock/23714/api/list';
    const fetchListAction = params => {
        return request.post(listUrl, params);
    };

    const CardContent = props => {
        const {item} = props;
        return (
            <Card
                title={`项目名称：${item.name}`}
                style={{width: 300, margin: '0 20px 20px 0'}}
            >
                创建者：{item.creator}
            </Card>
        );
    };

    const options = () => {
        return {
            rowKey: 'id',
            title: '项目列表',
            fetchListAction,
            card: CardContent
        };
    };

    const List = props => {
        const listProps = useTable(options, props);
        return <HooksTable {...listProps} />;
    };

    return <List />;
}

API​

ITableOptions​

Options 配置项：

配置项说明类型默认值
title页面标题ReactNode--
className列表类名string--
fetchListAction请求的 action 名称或方法string〡Function--
abort是否禁止发这次请求boolean--
interval轮询间隔（ms）number--
$onRequest请求发出前钩子函数(payload: any) => any--
$onResponse请求返回成功后钩子函数(response: any, payload?: any) => any--
$onError请求失败时钩子函数(error: any) => void--
bulkConfig操作区配置IBulkItemConfig[]--
bulkComp自定义操作区组件React.ComponentType<any>--
filterConfig筛选区配置IFilterConfig--
filterComp自定义筛选区组件React.ComponentType<any>--
rowKey表格行 key 的取值string--
select表格行是否可选择及可选类型（多选、单选）multi〡single〡none--
pageSize每页默认展示条数number10
pageSizeOptions每页展示条数的可选值string[]['10', '20', '50', '100']
tableConfig表格区域配置，同 acud TableTable--
tableComp自定义表格区域组件React.ComponentType<any>--
card表格区域以卡片组件的形式展示React.ComponentType<any>--
commands操作相关配置ICommand--
ICommand 类型
export interface ICommand {
    [actionName: string]: {
        actionType?: 'link' | 'ajax' | 'dialog' | 'drawer' | 'custom';
        link?: string; // actionType === 'link' 时的链接
        ajax?: IAjaxOption; // // actionType === 'ajax' 时的额外配置
        dialog?: IDialogOption; // actionType === 'dialog' 时的dialog配置
        drawer?: IDrawerOption; // actionType === 'dialog' 时的drawer配置
        action?: string; // actionType === 'custom' 的用户自定义方法名
        $payloadFields?: any[];
        $extraPayload?: object
    }
}
link 说明
// actionType === 'link'
{
    // id: 'create', // bulkConfig 中配置
    // text: '创建项目' // bulkConfig 中配置
    actionType: 'link',
    link: '/project/create',
    // $payloadFields: ['id'], // commands 中配置
    // handleTableCommand 调用时从传入的 payload 中根据指定的 $payloadFields 提取对应字段的值
    $extraPayload: {
        payload1: '123',
        payload2: '234'
    }
}

// 最终跳转地址：'/project/create[/${id}]/123/234'
// 与直接指定link 为 '/project/create[/${id}]/123/234' 效果一致

IBulkItemConfig​

操作区配置项：

配置项说明类型默认值
id按钮 IDstring--
text按钮文本ReactNode--
skin按钮主题primary〡text〡highlight〡enhance〡default〡danger--
block按钮宽度是否为父级宽度booleanfalse
disabled按钮失效状态booleanfalse
href按钮点击跳转地址string--
htmlType按钮原生类型stringbutton
icon按钮图标组件ReactNode--
loading按钮载入状态boolean〡{ delay: number }false
size按钮大小large〡middle〡smallmiddle
target按钮 target 属性string--
type按钮类型primary〡text〡highlight〡enhance〡defaultdefault
select未选中时是否可操作booleantrue
actionType操作类型link〡ajax〡dialog〡drawer〡custom--
linkactionType 为 link 时的链接配置string--
ajaxactionType 为 ajax 时的 ajax 配置IAjaxOption--
dialogactionType 为 dialog 时的 dialog 配置IDialogOption--
draweractionType 为 dialog 时的 drawer 配置IDrawerOption--
actionactionType 为 custom 的用户自定义方法名string--
$extraPayloadpayload 项，select 为 true 时将被覆盖为 {selectedItems, selectedRowKeys}object--

IAjaxOption​

actionType === ajax
// actionType === 'ajax'
{
    // id: 'delete', // bulkConfig 中配置
    // text: '删除', // bulkConfig 中配置
    // select: true, // bulkConfig 中配置，表格行至少勾选一项后，按钮才可点击，不然为disabled状态
    actionType: 'ajax',
    ajax: {
        apiAction: 'deleteProject',
        confirmTitle: '确认删除提示', // 可以是形如"名称（<%= name %>）"这样的模版字符串
        confirmText: '确定要删除所选的告警渠道吗？删除后不能恢复！',
        $toastMessage: '删除成功',
        // $payloadFields: ['id'] // commands中配置
        $extraPayload: {},
        $onRequest(payload) {
            // bulkConfig 中批量处理时可能需要
            // payload.ids = payload.selectedRowKeys;
            // delete payload.selectedRowKeys;
            // delete payload.selectedItems;
        },
        $onResponse(response, payload) {},
        $onError(error, payload) {}
    },
    $extraPayload: {}
}

IDialogOption​

// actionType === 'dialog' && 弹框类型为'alert'
// 展示形式为 DialogBox，默认为通知形式
{
    // id: 'create', // bulkConfig 中配置
    // text: '创建项目', // bulkConfig 中配置
    // skin: 'primary', // bulkConfig 中配置
    // icon: <OutlinedPlus />, // bulkConfig 中配置
    actionType: 'dialog',
    dialog: {
        title: '创建项目',
        body: {
            type: 'alert',
            content: CreateProject,
            $extraPayload: {},
            $onBeforeOpen(payload) {}
        },
        // foot: true,
        // cancelWithSuccess: false,
        // confirmLoadingText: '提交中…'
    }
}
配置项说明类型
title对话框的标题string
body对话框主体配置IDialogBodyOption
foot对话框是否需要底部boolean
cancelWithSuccess取消时是否执行 onSuccess 方法boolean
confirmLoadingText请求发起中按钮的文案ReactNode
  • type 为 alert 时，其他对话框配置项 同 acud DialogBox API
  • type 为 plain 或者 common 时，其他对话框配置项 同 acud Modal API
export interface IDialogBodyOption {
    type: 'alert' | 'plain' | 'common'; // 弹框的类型
    content?: React.ReactNode; // 弹框的内容
    // $payloadFields?: string[]; // 指定传入参数的字段名
    $extraPayload?: any; // 额外的参数
    // 与 useList 不同，这里废弃 $onBeforeDialogOpen，改为 $onBeforeOpen
    $onBeforeOpen?: (payload: any) => any; // 对话框打开之前的钩子函数
}

IDrawerOption​

// actionType === 'drawer'
// 展示形式为 Drawer，抽屉底部默认有「确定」和「取消」按钮
{
    // id: 'create', // bulkConfig 中配置
    // text: '创建项目', // bulkConfig 中配置
    // skin: 'primary', // bulkConfig 中配置
    // icon: <OutlinedPlus />, // bulkConfig 中配置
    actionType: 'drawer',
    drawer: {
        title: '创建项目',
        body: {
            content: CreateProject,
            // $payloadFields: ['id', ['name', 'projectName']] // commands 中配置。
            $extraPayload: {},
            $onBeforeOpen(payload) {}
        },
        // foot: true,
        // cancelWithSuccess: false,
        // confirmLoadingText: '提交中…'
    }
}
配置项说明类型默认值
title对话框的标题ReactNode--
body对话框主体配置IDrawerBodyOption确认
foot对话框是否需要底部boolean--
cancelWithSuccess取消时是否执行 onSuccess 方法boolean--
confirmLoadingText请求发起中按钮的文案ReactNode提交中…
  • 其他对话框配置项 同 acud Drawer API
export interface IDrawerBodyOption {
    content?: React.ReactNode; // 抽屉的内容
    // $payloadFields?: any[];
    $extraPayload?: object; // 额外的参数
    $onBeforeOpen?: (payload: any) => any; // 抽屉打开之前的钩子函数
}

IFilterConfig​

筛选区配置项：

配置项说明类型默认值
controls筛选项配置IFilterControl[]--

IFilterControl​

export interface IFilterControl extends IBulkItemConfig {
    /**
     * 筛选项名称
     */
    name?: string;
    /**
     * 筛选控件前的标签名
     */
    label?: React.ReactNode;
    /**
     * 筛选控件
     */
    control?: React.ComponentType<any>;
    /**
     * 筛选控件的参数
     * 如控件有默认值（defaultValue、defaultChecked）
     * 则需要通过这种方式传入，不然会影响 filterData 的初始化
     */
    controlProps?: any;
}

HooksTable​

<HooksTable {...useTableProps} />

HooksTable 除了接收 useTable 调用后的参数，还有接收参数：

参数名说明类型默认值
customRender可用于自定义 title 和 toolbar{title: ReactNode, toolbar: ReactNode}--
const customRender = {
    title: <div>业务端 title</div>,
    toolbar: <div>业务端 toolbar</div>
};

return (
    <HooksTable
        {...useTableProps}
        customRender={customRender}
     />
);