Skip to main content

useList

用于配置化+自定义实现各种列表页面的 hooks。

说明

列表页是开发中遇到最常见的页面，如下图所示，一张典型的列表页会包括“列表主区域”、“操作区”和“筛选区”。

为了提高开发效率，避免大量重复的基础代码(比如请求数据，打开弹框等)，将列表通用的行为都抽取出来，用户只需要通过简单的配置就能实现大多数场景的列表页面，一些特殊的场景可以通过自定义组件和方法来实现。

  • 列表主区域支持表格，卡片风格及其他自定义形式的列表。
  • 操作区和表格区支持常用的 5 种操作方式：
    • 页面跳转
    • 弹框
    • 抽屉
    • Ajax 请求
    • 自定义方法
  • 操作区支持配置及自定义，能与主区域选中的数据进行交互。自定义操作组件可以调用底层的 handleAction 方法迅速实现 5 种常用操作。
  • 筛选区支持配置及自定义，筛选区的数据可从后端接口中获取，随时可改，支持联动。
  • 支持在业务端 自己定义方法，或实现自己的逻辑。
与 useTable 的区别
  • 更灵活的配置项：useTable 比 useList 支持更多基础组件参数的传入
  • 更统一的配置项：useTable 统一了 command 部分不同 actionType 下参数配置结构
  • 更精简的代码：useTable 精简了代码文件结构（useList 由于 createBaseList 的原因，文件引用复杂）

引入​

import {useList, HooksList} from 'baidu-acu-react-common';

使用方法​

import {useList, HooksList} from 'baidu-acu-react-common';

// 配置信息
const options = (props, handleTableCommand, customFunctions) => ({
    // ...
});

export default props => {
    // 自定义方法
    const customOpt = () => {
        // ...
    };

    // 自定义方法集合
    const customFunctions = {customOpt};
    const [bizData, setBizData] = useState({});
    const {listProps} = useList(options, {...props, ...bizData}, customFunctions);

    return <HooksList {...listProps} />;
};

1、 首先定义配置项信息 options，它必须是一个方法，有三个参数 prop、handleTableCommand 和 customFunctions，分别代表组件属性，表格事件处理函数，和业务代码中自定义的方法集合。更多详细的配置项下面详细介绍。

2、 核心：在组件中使用 useList 这个 hooks，它的三个参数是 options、props 和 customFunctions，返回一个对象如下说明：

  • dataSource: 当前列表中展现的数据集合
  • options: 当前所有配置项
  • setOptions: 更新配置项的方法
  • setSelectedRowKeys: 设置选中的方法
  • handleAction: 5 种常见操作方法
  • listProps: 列表渲染的所有属性

3、 最后返回 HooksList 组件

配置项​

基础配置​

配置项说明类型默认值
*fetchListAction请求方法，可以是 actions 方法名或接口string--
*rowKey返回数据的主键字段名string--
title页面标题string〡ReactNode--
className列表 classNamestring--
pageSize每页条数number10
pageSizeOptions指定每页可以显示多少条string[]['10', '20', '50', '100']
select选择类型multi〡single〡nonemulti
interval轮询间隔（ms）number--
emptyText无返回数据时的文案提示string--
bulkPosition操作区位置left〡rightleft
bulkConfig操作区配置，详见“操作区配置”BulkItem[]--
bulkComp自定义操作区组件，优先级优于 bulkConfigReactNode--
bulkConfig筛选区配置，详见“筛选区配置”FilterConfig--
filterComp自定义筛选区组件，优先级优于 filterConfigReactNode--
tableConfig列表主区域配置，详见“列表主区域配置”object--
tableComp自定义列表主区域区组件，优先级优于 tableConfigReactNode--
card卡片组件，当展现形式为卡片列表时配置ReactNode--
commands事件实现配置，详见“事件实现配置”object--
requestAbort是否中断请求发起booleanfalse
$onRequest列表请求发出前钩子函数(payload: any) => any--
$onResponse列表请求返回成功后钩子函数(page: any) => any--
$onError列表请求失败时钩子函数(error: any) => void--

列表主区域配置 (tableConfig)​

如果配置了 tableConfig，则会使用 antd table 展示表格，所以配置项可以使用 Acud table 的配置项，组件会进行透传，下面就几个常用的配置项做说明。

配置项说明类型默认值
*columns表格列的配置描述antdTable columns--
*getCheckboxProps选择框的默认属性配置Function(record)--

columns 操作区指南​

先看一个例子代码

const options = (props, handleTableCommand, customFunctions) => ({
    tableConfig: {
        columns: [
            ...(props.match.params.withName ? [{
                    title: '名称',
                    dataIndex: 'name'
            }] : []),
            {
                title: '操作',
                key: 'action',
                render: item => (
                    <span>
                        <a onClick={() => handleTableCommand('VIEW_DETAIL', item)}>新页查看详情</a>
                        <a onClick={() => handleTableCommand('VIEW_DIALOG_DETAIL', item)}>弹框查看详情</a>
                        <a onClick={() => handleTableCommand('DELETE', item)}>删除</a>
                        <a onClick={() => handleTableCommand('UPDATE', item)}>编辑</a>
                        <a onClick={() => customFunctions.customOpt(item)}>自定义方法</a>
                    </span>
                )
            }
        ]
    },
    commands: {
        VIEW_DETAIL: {
            actionType: 'link',
            link: '/home/detail/basicdetail',
            $payloadFields: ['id']
        },
        VIEW_DIALOG_DETAIL: {
            actionType: 'dialog',
            dialog: {
                title: 'Demo详情',
                width: 700,
                body: {
                    type: 'plain',
                    content: DialogDetail
                }
            }
        },
        DELETE: {
            actionType: 'ajax',
            ajax: {
                apiAction: 'deleteDemo',
                $toastMessage: '删除成功',
                confirmTitle: '确认删除提示',
                confirmText: '确定要删除所选择的数据吗?',
                confirmType: 'error',
                $payloadFields: ['id'],
                $extraPayload: {
                    a: 1
                }
            }
        },
        UPDATE: {
            actionType: 'dialog',
            dialog: {
                title: '编辑Demo',
                width: 700,
                body: {
                    type: 'common',
                    content: DialogForm
                }
            }
        }
    }
});

上面代码块有两个小技巧

  • columns 有些列可以根据 url 参数或者 props 中某个属性而显示隐藏。比如上面 name 列就由 url 中 withName 参数来控制展现与否。
  • 表格中的操作有两种方式：
  1. 通过配置
  2. 自定义方法，自定义方法需要在业务代码中自己实现，并放到 customFunctions 集合中，通过配置 commands 字段就可以快速实现 5 种常见的操作，key 对应 handleTableCommand 方法的第一个参数，value 对象配置项详见下面【事件配置】

事件配置​

配置项说明类型默认值
*actionType操作类型link/ajax/dialog/drawer/custom--
link当 actionType 为 link 时
要跳转的链接		string--
action当 actionType 为 custom 时
自定义方法名		string--
ajax当 actionType 为 ajax 时
Ajax 配置项		AjaxOption--
dialog当 actionType 为 dialog 时
dialog 配置项		DialogOption--
drawer当 actionType 为 drawer 时
drawer 配置项		DrawerOption--

三种配置项 AjaxOption、DialogOption 和 DrawerOption 分别用 TS 类型定义来说明如下：

export type ConfirmType = 'warning' | 'info' | 'error' | 'sucess';

export interface AjaxOption {
    apiAction: string; // actions方法名
    $toastMessage?: string; // 成功之后提示
    confirmTitle?: string; // 确认提示title
    cancelText?: string;
    okText?: string;
    confirmText?: string; // 确认提示文案
    confirmType?: ConfirmType | 'error'; // 确认按钮的类别
    $payloadFields?: string[]; // 需要传给后端的表格字段
    $extraPayload?: any; // 额外的请求参数
    $onRequest?: (requestPayload: any) => any; // 发起ajax请求前的勾子函数
    $onResponse?: (response: any, requestPayload: any) => any; // ajax请求成功后的勾子函数
    $onError?: (error: any, requestPayload: any) => void; // ajax请求失败时的勾子函数
}

操作区配置 (bulkConfig)​

bulkConfig: BulkItem[]; BulkItem 配置项如下表所示：

配置项说明类型默认值
*id按钮 IDstring--
*text按钮文案string--
position按钮位置left〡rightleft
type类型button〡checkboxbutton
icon按钮 iconstring--
skin按钮皮肤，不填为默认样式primary〡dashed〡danger--
select是否和选择关联，如果关联，当没有选择数据的时候，按钮不可点booleanfalse
disabled是否禁用booleanfalse
*actionType操作类型link〡ajax〡dialog〡drawer〡custom--
link当 actionType 为 link 时，要跳转的链接string--
action当 actionType 为 custom 时，自定义方法名string--
ajax当 actionType 为 ajax 时，Ajax 配置项AjaxOption--
dialog当 actionType 为 dialog 时，dialog 配置项DialogOption--
drawer当 actionType 为 drawer 时，drawer 配置项DrawerOption--

上表中 AjaxOption、DialogOption 和 DrawerOption 见上面【事件配置】章节。

筛选区配置 (filterConfig)​

配置项说明类型默认值
*controls筛选配置项FilterControl[]--
position筛选区位置，left 与操作区一行居左 right 与操作区一行居右，不设置则在操作区下面string--
submitText查询按钮文案，如果不设置则实时改变就发起查询string--

FilterControl:

配置项说明类型默认值
*type筛选类型textbox〡search〡select〡rangecalendar〡tagselect〡radio--
*name筛选项名称string--
width筛选项宽度number--
defaultValue默认值any--
value数值any--
label标签string--
multi是否多选，应用 type 为 'select' 情况booleanfalse
options选项，select、tagselect 和 radio 类型时需要配置any[]--
timetype === 'rangecalendar' 时是否是时间booleantrue
rangetype === 'rangecalendar' 时日期选择框的范围any--
antdProps其他 antd 支持的属性any--

其他使用技巧​

1、页面中渲染切换

我们业务中有很多这种场景，比如某个按钮置灰与否、列展示、请求地址都会根据 props 中某个值变化而切换。

实现方式：通过修改 options 方法第一个参数 props 来实现所有类似这些变化。

export default props => {
    const customFunctions = {};

    // 业务端维护用来修改渲染的数据，通过setBizData来用数据出发渲染的改变
    const [bizData, setBizData] = useState({});
    const {listProps} = useList(options, {...props, ...bizData}, customFunctions);

    // 更新原始配置的方法
    const updateFilterControl = () => {
        setBizData({
            ...bizData,
            type2Options: [
                {value: 'cat1', text: '类目1'},
                {value: 'cat2', text: '类目2'}
            ]
        });
    };

    useEffect(() => {
        // 更新一个筛选项方法
        updateFilterControl();
    }, []);

    return (
        <HooksList
            {...listProps}
        />
    );
};

2、卡片形式列表的全选功能

功能示例: demo。

实现方式：只需要在 bulkConfig 中新增一个 checkbox 配置项，如下面代码所示

bulkConfig: [
    {
        id: 'checkAll',
        type: 'checkbox',
        text: '全选',
        actionType: 'custom',
        action: 'checkAll' // 底层useList中已实现，业务代码中不需要写
    },
    ...
]

3、业务中自定义的渲染

需求场景：有些列表页 title 上面需要放一些提示，或者表格上面放一些统计信息等，这种情况就需要业务代码进行一些渲染。HooksList 有一个 customRender 属性，当前有 title 和 toolbar 两个位置的渲染输入，具体可见下面代码。

export default props => {
 
    // 业务端支持自定义做一些页面渲染
    const customRender = {
        title: <div>业务端title</div>,
        toolbar: <div>业务端toolbar</div>
    };
    return (
        <HooksList
            {...listProps}
            customRender={customRender}
        />
    );
};

参考文档​

https://react-app-common.now.baidu-int.com/#/hooks/UseList