tntd 1.3.66 → 1.4.0

package/es/QueryListScene/README.md

@@ -0,0 +1,790 @@
+## QueryListScene查询列表
+主要用于查询列表页面场景，主要包括三部分: 表单查询、操作工具栏、表格数据展示。组件特点：
+- 标签结构化、语义化，提高代码可读性
+- 样式统一，方便统一维护升级
+- 数据状态管理 + 通用逻辑涵盖(如Loading、分页、切换页码、查询、重置、自动轮询等)
+
+### 安装
+```
+npm install tntd --save
+```
+
+### 代码演示
+
+### 展开/收起查询条件
+```jsx
+import React, { useState, Fragment } from 'react';
+import ReactDOM from 'react-dom';
+import { Button, Popconfirm, Divider, ButtonGroup, TreeSelect, Cascader } from 'antd';
+import { QueryListScene } from 'tntd';
+import { createGlobalStyle } from 'styled-components';
+import 'antd/dist/antd.css';
+
+const GlobalStyle = createGlobalStyle`
+  .site-body {
+    .ichYgh {
+        overflow: visible;
+    }
+}
+`;
+
+const { QueryForm, Field, Toolbar, QueryList, createActions } = QueryListScene;
+const actions = createActions();
+
+const ColumnActions = ({ record }) => {
+    const onDelete = () => {
+        new Promise(resolve => {
+            resolve(true);
+        }).then(() => {
+            actions.search();
+        });
+    };
+
+    return (
+        <span>
+            <a>编辑</a>
+            <Divider type="vertical" />
+            <Popconfirm
+                title="删除确认"
+                onConfirm={onDelete}
+                okText="确认"
+                cancelText="取消"
+            >
+                <a>删除</a>
+            </Popconfirm>
+            <Divider type="vertical" />
+            <a
+                download
+                target="__blank"
+                href={`/download?id=${record.id}`}
+            >
+                下载
+            </a>
+        </span>
+    );
+};
+
+const columns = [
+    {
+        title: 'ID',
+        dataIndex: 'id',
+        width: 80,
+        sorter: true
+    },
+    {
+        title: '项目名称',
+        dataIndex: 'name',
+        sorter: (a, b) => a.name > b.name
+    },
+    {
+        title: '管理员',
+        dataIndex: 'owner',
+        width: 100
+    },
+    {
+        title: '创建时间',
+        dataIndex: 'createTime',
+        width: 200
+    },
+    {
+        title: '状态',
+        dataIndex: 'status',
+        width: 100
+    },
+    {
+        title: '操作',
+        dataIndex: 'operation',
+        width: 150,
+        render: (val, record) => <ColumnActions record={record} />
+    }
+];
+const query = ({ current = 1, pageSize, ...rest }) => {
+    pageSize = pageSize || 10;
+    console.log('query params...', rest);
+
+    return new Promise(resolve => {
+        setTimeout(() => {
+            resolve({
+                current,
+                pageSize,
+                total: 100,
+                data: new Array(100).fill(1).map(
+                    (item, index) => ({
+                        id: index + 1,
+                        name: `项目${index + 1}`,
+                        owner: `张三${index + 1}`,
+                        createTime: '2019-09-10 16:30:34',
+                        status: ['初始化', '运行中', '成功', '失败'][index % 4]
+                    })
+                ).slice((current - 1) * pageSize, current * pageSize)
+            });
+        }, 500);
+    });
+};
+
+const ExtraActions = (
+    <Button.Group> 
+        <Button icon="cloud-upload" />
+        <Button icon="cloud-download" />
+        <Button icon="setting" />
+    </Button.Group>
+);
+
+ReactDOM.render(
+    <QueryListScene
+        title="项目管理"
+        query={query}
+        actions={actions}
+        interval={5000}
+    >
+        <QueryForm
+            extraActions={ExtraActions}
+            initialValues={{
+                name: 'zhangsan',
+                status: 'initial'
+            }}
+            defaultExpanded={true}
+        >
+            <Field
+                name="tree"
+                component={TreeSelect}
+                props={{
+                    placeholder: "树形选择",
+                    dropdownStyle:{
+                        maxHeight: 400, 
+                        overflow: 'auto'
+                    },
+                    treeData: [
+                        {
+                            title: 'Node1',
+                            value: '0-0',
+                            key: '0-0',
+                            children: [
+                            {
+                                title: 'Child Node1',
+                                value: '0-0-1',
+                                key: '0-0-1',
+                            },
+                            {
+                                title: 'Child Node2',
+                                value: '0-0-2',
+                                key: '0-0-2',
+                            },
+                            ],
+                        },
+                        {
+                            title: 'Node2',
+                            value: '0-1',
+                            key: '0-1',
+                        }
+                    ]
+                }}
+            />
+            <Field
+                type="input"
+                name="name"
+                props={{
+                    placeholder: "名称"
+                }}
+            />
+            <Field
+                type="select"
+                name="status"
+                props={{
+                    placeholder: '状态',
+                    options: [
+                        { label: '初始化', value: 'initial' },
+                        { label: '运行中', value: 'running' },
+                        { label: '成功', value: 'success', disabled: true },
+                        { label: '失败', value: 'fail' }
+                    ]
+                }}
+            />
+            <Field
+                type="select"
+                name="select1"
+                props={{
+                    placeholder: '状态',
+                    loadData: () => new Promise(resolve => resolve(['初始化', '运行中', '成功', '失败']))
+                }}
+            />
+            <Field
+                type="input"
+                name="name2"
+                props={{ placeholder: "名称" }}
+            />
+            <Field 
+                type="search"
+                name="search"
+                props={{
+                    placeholder: '搜索'
+                }}
+            />
+            <Field
+                type="select"
+                name="select2"
+                props={{
+                    placeholder: '状态',
+                    options: ['初始化', '运行中', '成功', '失败']
+                }}
+            />
+            <Field type="date" name="date3" />
+            <Field type="input" name="field1" />
+            <Field type="input" name="field2" />
+            <Field type="dateRange" name="date2" />
+        </QueryForm>
+        <Toolbar>
+            <Button type="primary">新增</Button>
+            <Button type="warning">删除</Button>
+        </Toolbar>
+        <QueryList
+            resizable={true}
+            rowKey="id"
+            paginationSticky
+            bordered={false}
+            columns={columns}
+            scroll={{ y: 540 }}
+        />
+    </QueryListScene>,
+    document.getElementById('root')
+)
+```
+
+
+### 抽屉显示更多条件
+```jsx
+import React, { useState, Fragment } from 'react';
+import ReactDOM from 'react-dom';
+import { Button, Popconfirm, Divider, ButtonGroup, TreeSelect, Cascader, Icon } from 'antd';
+import { QueryListScene } from 'tntd';
+import { createGlobalStyle } from 'styled-components';
+import 'antd/dist/antd.css';
+
+const GlobalStyle = createGlobalStyle`
+  .site-body {
+    .ichYgh {
+        overflow: visible;
+    }
+}
+`;
+
+const { QueryForm, Field, Toolbar, QueryList, createActions } = QueryListScene;
+const actions = createActions();
+
+const ColumnActions = ({ record }) => {
+    const onDelete = () => {
+        new Promise(resolve => {
+            resolve(true);
+        }).then(() => {
+            actions.search();
+        });
+    };
+
+    return (
+        <span>
+            <a>编辑</a>
+            <Divider type="vertical" />
+            <Popconfirm
+                title="删除确认"
+                onConfirm={onDelete}
+                okText="确认"
+                cancelText="取消"
+            >
+                <a>删除</a>
+            </Popconfirm>
+            <Divider type="vertical" />
+            <a
+                download
+                target="__blank"
+                href={`/download?id=${record.id}`}
+            >
+                下载
+            </a>
+        </span>
+    );
+};
+
+const columns = [
+    {
+        title: 'ID',
+        dataIndex: 'id',
+        width: 80,
+        sorter: true
+    },
+    {
+        title: '项目名称',
+        dataIndex: 'name',
+        sorter: (a, b) => a.name > b.name
+    },
+    {
+        title: '管理员',
+        dataIndex: 'owner',
+        width: 100
+    },
+    {
+        title: '创建时间',
+        dataIndex: 'createTime',
+        width: 200
+    },
+    {
+        title: '状态',
+        dataIndex: 'status',
+        width: 100
+    },
+    {
+        title: '操作',
+        dataIndex: 'operation',
+        width: 150,
+        render: (val, record) => <ColumnActions record={record} />
+    }
+];
+const query = ({ current = 1, pageSize, ...rest }) => {
+    pageSize = pageSize || 10;
+    console.log('query params...', rest);
+
+    return new Promise(resolve => {
+        setTimeout(() => {
+            resolve({
+                current,
+                pageSize: 10,
+                total: 100,
+                data: new Array(100).fill(1).map(
+                    (item, index) => ({
+                        id: index + 1,
+                        name: `项目${index + 1}`,
+                        owner: `张三${index + 1}`,
+                        createTime: '2019-09-10 16:30:34',
+                        status: ['初始化', '运行中', '成功', '失败'][index % 4]
+                    })
+                ).slice((current - 1) * pageSize, current * pageSize)
+            });
+        }, 500);
+    });
+};
+
+const ExtraActions = (
+    <Button.Group> 
+        <Button icon="cloud-upload" />
+        <Button icon="cloud-download" />
+        <Button icon="setting" />
+    </Button.Group>
+);
+
+const QueryListPage = () => {
+    return (
+        <Fragment>
+            <QueryListScene
+                title="项目管理"
+                query={query}
+                actions={actions}
+                // interval={5000}
+            >
+                <QueryForm
+                    extraActions={ExtraActions}
+                    // 设置showFieldCount时，则使用抽屉显示更多否则使用展开/收起交互
+                    showFieldCount={2}
+                    initialValues={{
+                        name: 'xxx',
+                        status: 'initial',
+                        obj: {
+                            name: 'zhangsan'
+                        }
+                    }}
+                >
+                    <Field
+                        type="selectInput"
+                        name="obj"
+                        props={{
+                            placeholder: "名称",
+                            options: [
+                                { label: '名称', value: 'name' },
+                                { label: 'ID', value: 'id' }
+                            ],
+                            addonBeforeStyle: { width: '100px' }
+                        }}
+                    />
+                    <Field
+                        name="tree"
+                        component={TreeSelect}
+                        props={{
+                            placeholder: "名称222",
+                            dropdownStyle:{
+                                maxHeight: 400, 
+                                overflow: 'auto'
+                            },
+                            treeData: [
+                                {
+                                    title: 'Node1',
+                                    value: '0-0',
+                                    key: '0-0',
+                                    children: [
+                                    {
+                                        title: 'Child Node1',
+                                        value: '0-0-1',
+                                        key: '0-0-1',
+                                    },
+                                    {
+                                        title: 'Child Node2',
+                                        value: '0-0-2',
+                                        key: '0-0-2',
+                                    },
+                                    ],
+                                },
+                                {
+                                    title: 'Node2',
+                                    value: '0-1',
+                                    key: '0-1',
+                                }
+                            ]
+                        }}
+                    />
+                    <Field
+                        type="input"
+                        name="name"
+                        props={{
+                            placeholder: "名称"
+                        }}
+                    />
+                    <Field
+                        name="cascader"
+                        component={Cascader}
+                        props={{
+                            options: [
+                                {
+                                    value: 'zhejiang',
+                                    label: 'Zhejiang',
+                                    children: [
+                                        {
+                                            value: 'hangzhou',
+                                            label: 'Hangzhou',
+                                            children: [
+                                                {
+                                                    value: 'xihu',
+                                                    label: 'West Lake'
+                                                }
+                                            ]
+                                        }
+                                    ]
+                                }
+                            ]
+                        }}
+                    />
+                    <Field 
+                        type="date"
+                        name="date1"
+                    />
+                    <Field
+                        title="状态"
+                        type="select"
+                        name="status2"
+                        props={{
+                            placeholder: '状态',
+                            options: [
+                                { label: '初始化', value: 'initial' },
+                                { label: '运行中', value: 'running' },
+                                { label: '成功', value: 'success', disabled: true },
+                                { label: '失败', value: 'fail' }
+                            ]
+                        }}
+                    />
+                    <Field title="日期" type="date" name="date" />
+                    <Field
+                        title="日期范围"
+                        type="dateRange"
+                        name="date2"
+                    />
+                    <Field
+                        title="状态"
+                        type="select"
+                        name="select1"
+                        props={{
+                            placeholder: '状态',
+                            fieldNames: {
+                                label: 'displayName',
+                                value: 'name'
+                            },
+                            loadData: () => new Promise(
+                                resolve => resolve([
+                                    { name: 'success', displayName: '成功' },
+                                    { name: 'fail', displayName: '失败' }
+                                ])
+                            )
+                        }}
+                    />
+                    <Field
+                        title="名称"
+                        type="input"
+                        name="name2"
+                        props={{ placeholder: "名称" }}
+                    />
+                    <Field
+                        title="状态2"
+                        type="select"
+                        name="select2"
+                        props={{
+                            placeholder: '状态',
+                            options: ['初始化', '运行中', '成功', '失败']
+                        }}
+                    />
+                </QueryForm>
+                <Toolbar>
+                    <Button type="primary">新增</Button>
+                    <Button type="warning">删除</Button>
+                </Toolbar>
+                <QueryList
+                    rowKey="id"
+                    paginationSticky
+                    bordered={false}
+                    columns={columns}
+                />
+            </QueryListScene>
+        </Fragment>
+    );
+};
+
+ReactDOM.render(
+    <Fragment>
+        <QueryListPage />
+        <GlobalStyle />
+    </Fragment>,
+    document.getElementById('root')
+)
+```
+
+
+### QueryListScene with memory
+- 使用场景: 从列表页跳转到其它页面再回到列表页时会记住查询条件及分页参数。
+- 重置记忆数据：actions.resetMemoryData
+
+```jsx
+import React, { useState, useEffect, Fragment } from 'react';
+import ReactDOM from 'react-dom';
+import { Button } from 'antd';
+import { QueryListScene } from 'tntd';
+
+const { QueryForm, Field, Toolbar, QueryList, createActions, useActions } = QueryListScene;
+// const actions = createActions();
+
+const QueryListPage = () => {
+    const actions = useActions();
+    const [visible, setVisible] = useState(true);
+    const query = params => {
+        params.pageSize = params.pageSize || 10;
+        const { current, pageSize } = params;
+        console.log('memory query params...', params);
+
+        return Promise.resolve({
+            current,
+            pageSize,
+            total: 100,
+            data: new Array(100).fill(1).map(
+                (item, index) => ({
+                    id: index + 1,
+                    name: `项目${index + 1}`,
+                    owner: `张三${index + 1}`,
+                    createTime: '2019-09-10 16:30:34',
+                    status: ['初始化', '运行中', '成功', '失败'][index % 4]
+                })
+            ).slice((current - 1) * pageSize, current * pageSize)
+        });
+    }; 
+
+    // 用法完全和QueryListScene一样
+    return (
+        <Fragment>
+            <Button
+                type={visible ? 'danger' : 'primary'}
+                onClick={() => setVisible(!visible)}
+            >
+                {visible ? '销毁列表' : '显示列表'}
+            </Button>
+            <Button
+                onClick={actions.resetMemoryData}
+            >
+                重置记忆数据
+            </Button>
+            {
+                visible ? (
+                    <QueryListScene
+                        memory
+                        actions={actions}
+                        query={query}
+                    >
+                        <QueryForm initialValues={{ name: '项目' }}>
+                            <Field
+                                name="name"
+                                type="input"
+                                props={{
+                                    placeholder: '名称'
+                                }}
+                            />
+                            <Field
+                                type="select"
+                                name="status"
+                                props={{
+                                    placeholder: '状态',
+                                    options: ['初始化', '运行中', '成功', '失败']
+                                }}
+                            />
+                        </QueryForm>
+                        <QueryList
+                            resizable={true}
+                            rowKey="id"
+                            columns={[
+                                { dataIndex: 'id', title: 'ID', width: 100, },
+                                { dataIndex: 'name', title: '名称', width: 200 },
+                                { dataIndex: 'owner', title: '负责人', width: 100 },
+                                { dataIndex: 'status', title: '状态' }
+                            ]}
+                        />
+                    </QueryListScene>
+                ) : <p style={{ color: 'red' }}>列表已销毁</p>
+            }
+        </Fragment>
+    );
+};
+
+ReactDOM.render(
+    <QueryListPage />,
+    document.getElementById('root')
+)
+```
+
+
+
+### API
+#### QueryListScene
+
+| 属性名称  | 属性说明                                                                          | 类型    | 默认值 | 是否必须 |
+| :-------- | :-------------------------------------------------------------------------------- | :------ | :----- | :------- |
+| query     | 查询数据方法,调用时会把queryform数据作为参数                                      | Promise | 无     | 是       |
+| title     | 标题                                                                              | string  | 无     | 否       |
+| actions   | 组件上聚合的方法，需由createActions方法创建出来                                   | Object  | 无     | 否       |
+| interval  | 轮训时间间隔单位ms，设置该值后列表可自动轮询                                      | number  | 无     | 否       |
+| memory  | 组件销毁时是否需要记住表单和分页数据                                    | boolean  | false    | 否       |
+| className | css类                                                                             | string  | 无     | 否       |
+| size      | 目前主要设置header高度，默认按照新的设计，如果需要保持原有系统不变，则设置为large | string  | 无     | 否       |
+
+#### QueryForm
+| 属性名称       | 属性说明                                                  | 类型      | 默认值 | 是否必须 |
+| :------------- | :-------------------------------------------------------- | :-------- | :----- | :------- |
+| showFieldCount | 显示在外面的表单数量(尽在“更多条件”在Drawer交互时使用)    | number    | 无     | 否       |
+| showExpand | 展开/收起功能配置，默认开启    | boolean    | true     | 否       |
+| showSearch | 搜索按钮显示配置，默认开启    | boolean    | true     | 否       |
+| showReset | 重置按钮显示配置，默认开启    | boolean    | true     | 否       |
+| drawerProps    | Drawer props（参见antd，设置样式宽度时可用）              | Object    | 无     | 否       |
+| extraActions  | 额外操作                                                  | ReactNode | 无     | 否       |
+| renderActions  | 表单操作, 自定义操作按钮，默认是查询、重置                | Function  | 无     | 否       |
+| onChange       | 表单变化事件，onChange(values, { name, value, preValue }) | Function  | 无     | 否       |
+| onReset | 重置按钮点击事件回调，onReset(initialValues) | Function  | 无     | 否       |
+| onSearch | 点击搜索按钮事件回调，onSearch(values) | Function  | 无     | 否       |
+| onToggleExpand | 展开/收起回调事件，onToggleExpand(expanded) | Function  | 无     | 否       |
+
+
+#### Field
+| 属性名称  | 属性说明                                                       | 类型   | 默认值 | 是否必须 |
+| :-------- | :------------------------------------------------------------- | :----- | :----- | :------- |
+| name      | 表单项名，保证唯一                                             | string | 无     | 是       |
+| title     | 表单label                                                      | string | 无     | 否       |
+| type      | 表单类型input、search, number、select、selectInput、 date、 dateRange       | 无     | 否     |
+| component      | 表单组件，如果内置的type表单组件不满足需求的话，可以直接传ReactNode类型的表单组件，其优先级高于type,如 antd TreeSelect、Cascader等，也可以完全自定义表单组件       | 无     | 否     |
+| props     | 表单元素属性，参照antd, Input, InputNumber, Select, DatePicker | Object | 无     | 否       |
+| className | 添加样式class                                                  | string | 无     | 否       |
+
+type="select"， props 扩展了 options, fieldNames, loadData用法如下：
+```js
+<Field
+    type="select"
+    name="status"
+    props={{
+        options: [
+            { name: 'success', displayName: '成功' },
+            { name: 'fail', displayName: '失败' }
+        ],
+        fieldNames: {
+            label: 'displayName',
+            value: 'name'
+        }
+    }}
+/>
+```
+loadData 是一个function 返回一个promise, 用于异步加载options的场景
+```js
+<Field
+    type="select"
+    name="status"
+    props={{
+        loadData: () => new Promise(
+            resolve => resolve([
+                { name: 'success', displayName: '成功' },
+                { name: 'fail', displayName: '失败' }
+            ])
+        ),
+        fieldNames: {
+            label: 'displayName',
+            value: 'name'
+        }
+    }}
+/>
+```
+
+type="selectInput", 扩展了addonBeforeStyle属性，用来设置前面Select的样式
+```js
+<Field
+    type="selectInput"
+    props={{
+        addonBeforeStyle: {
+            width: '160px'
+        }
+    }}
+/>
+```
+
+#### Toolbar
+无
+
+#### QueryList
+同antd Table
+
+| 属性名称        | 属性说明                                       | 类型    | 默认值 | 是否必须 |
+| :-------------- | :--------------------------------------------- | :------ | :----- | :------- |
+| resizable | 可伸缩列，设置width的列可拖拽改变列宽度 | boolean | false  | 否       |
+| localPagination | 前端分页，数据一次性从接口获取，前端分页时使用 | boolean | false  | 否       |
+| paginationSticky | 分页是否吸底（sticky） | boolean | false  | 否       |
+
+#### createActions
+```
+const { createActions } = QueryListScene;
+const actions = createActions();
+
+actions对象接口如下：
+{
+    // 设置查询表单数据（默认自动查询，不需要查询needSearch传false）
+    setFormData: (data: Object, needSearch = true),
+    // 重置表单数据
+    resetFormData: (needSearch = false),
+    // 重置记忆数据，form、pagination
+    resetMemoryData(),
+    // 设置表格数据
+    setTableDataSource: (dataSource: Array),
+    // 设置分页数据
+    setPagination: (
+        pagination: Object = {
+            current,
+            pageSize,
+            total
+        }
+    ),
+    // 查询列表, params 为查询参数，会扩展到formData上, showLoading：是否显示loading
+    search: (params?: Object, showLoading?: boolean = true),
+
+    // 获取表单数据，name不传则是整个表单数据对象，传了name则获取单个表单值
+    getFormData: (name?: string),
+    // 获取当前查询条件的表单数据，与getFormData的区别在于，这里是已执行过查询的数据
+    getSubmittedFormData: (name?: string),
+    // 获取列表数据
+    getTableDataSource: (),
+    // 获取分页数据
+    getPagination: ()
+}
+```