m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/018-EPUI/347/273/204/344/273/266/031-datagrid/345/210/227/350/241/250.md

@@ -0,0 +1,664 @@
+# datagrid 列表
+
+数据展示。
+
+## 基本使用
+
+配合 `useTableDataSource` 实现数据源的获取和分页。
+
+通过 `data` 绑定数据源，`columns` 绑定列配置。
+
+通过配置 `key` 值为 `action` 的列来实现操作列的功能。
+
+列表刷新时会触发`change`事件，可在事件中刷新数据源。
+
+可通过列的 `isTitle` 字段设置该列为每项的标题行，不设置则默认`columns`第一项为标题行。
+
+通过列的 `isStatus` 设置该列为每项的状态。
+
+注意：该组件需要手动设置高度，否则可能会出现滚动不正常或其他样式问题。
+
+```html
+<template>
+    <e-data-grid-m
+        id-field="userGuid"
+        :data="tableSource.dataSource"
+        :total="tableSource.total"
+        :loading="tableSource.loading"
+        :current="tableSource.current"
+        :page-size="tableSource.pageSize"
+        :columns="columnList"
+        height="100%"
+        @change="tableSource.onTableChange"
+    ></e-data-grid-m>
+</template>
+
+<script lang="ts" setup>
+    import { reactive } from 'vue';
+    import { useTableDataSource } from '@epoint-fe/eui-hooks';
+
+    const params = reactive({
+        userName: '',
+        loginId: '',
+        ouName: ''
+    });
+    // 列配置
+    const columnList: Record<string, any>[] = [
+        { dataIndex: 'itemName', title: '事项名称' },
+        { dataIndex: 'ouName', title: '所在部门' },
+        { dataIndex: 'date', title: '办理时间' },
+        { dataIndex: 'status', title: '状态', isStatus: true },
+        {
+            title: '操作',
+            key: 'action', // 操作列
+            action: {
+                items: [
+                    {
+                        icon: 'Edit',
+                        label: '修改',
+                        onClick: (row) => {
+                            ejs.ui.toast('修改' + row.itemName);
+                        },
+                        visible: (row) => row.itemName === '我是事项1'
+                    },
+                    {
+                        icon: 'Setting',
+                        label: '配置',
+                        onClick: (row) => {
+                            ejs.ui.toast('配置' + row.itemName);
+                        },
+                        disabled: (row) => row.itemName === '我是事项2'
+                    }
+                ]
+            }
+        }
+    ];
+    // tableSource 具备以下属性： { dataSource, pageSize, current, total, loading, refresh, onTableChange }
+    const tableSource = useTableDataSource('/frameaction/getDataGridData', {
+        idField: 'userGuid',
+        columns: columnList,
+        params
+    });
+</script>
+```
+
+## 自定义列表样式
+
+组件仅提供最基础的列表样式，若基础样式不满足需求，可通过 `bodyCell` 或 `list` 插槽自定义列表样式。
+
+注意，使用 `list` 插槽时，不再有批处理、拖拽排序、左滑等功能。
+
+```html
+<template>
+    <e-data-grid-m
+        id-field="userGuid"
+        :data="tableSource2.dataSource"
+        :total="tableSource2.total"
+        :loading="tableSource2.loading"
+        :current="tableSource2.current"
+        :page-size="tableSource2.pageSize"
+        :columns="columnList2"
+        height="100%"
+        @change="tableSource2.onTableChange"
+    >
+        <template #bodyCell="{ record, column }">
+            <div v-if="column.key !== 'action'">{{ column.title }}: {{ record[column.dataIndex] }}</div>
+        </template>
+    </e-data-grid-m>
+</template>
+
+<script lang="ts" setup>
+    import { reactive } from 'vue';
+    import { useTableDataSource } from '@epoint-fe/eui-hooks';
+
+    const params = reactive({
+        userName: '',
+        loginId: '',
+        ouName: ''
+    });
+    // 列配置
+    const columnList2: Record<string, any>[] = [
+        { dataIndex: 'itemName', title: '事项名称' },
+        { dataIndex: 'ouName', title: '所在部门' },
+        { dataIndex: 'date', title: '办理时间' },
+        {
+            dataIndex: 'age',
+            title: '年龄'
+        },
+        {
+            title: '操作',
+            key: 'action', // 操作列
+            action: {
+                items: [
+                    {
+                        icon: 'Edit',
+                        label: '修改',
+                        onClick: (row) => {
+                            ejs.ui.toast('修改' + row.itemName);
+                        },
+                        visible: (row) => row.itemName === '我是事项1'
+                    },
+                    {
+                        icon: 'Setting',
+                        label: '配置',
+                        onClick: (row) => {
+                            ejs.ui.toast('配置' + row.itemName);
+                        },
+                        disabled: (row) => row.itemName === '我是事项2'
+                    }
+                ]
+            }
+        }
+    ];
+    // tableSource2 具备以下属性： { dataSource, pageSize, current, total, loading, refresh, onTableChange }
+    const tableSource2 = useTableDataSource('/frameaction/getDataGridData', {
+        idField: 'userGuid',
+        columns: columnList2,
+        params
+    });
+</script>
+```
+
+## 结合搜索工具栏使用
+
+`datagrid` 组件提供了 `toolbar` 插槽供外部向列表顶部插入工具栏。
+
+当然你也可以直接将工具栏组件放在 `datagrid` 组件上面，此时 `datagrid` 列表高度需要你自行计算。
+
+通过 `keyWord` 向列表传入关键字，列表中相应关键字会高亮展示（自定义列表样式时无此功能）;
+
+在搜索工具栏的 `advance-search` 事件中获取查询参数并调用 `datagrid` 的 `refresh` 方法刷新列表。
+
+```html
+<template>
+    <e-data-grid-m
+        id-field="userGuid"
+        ref="dataGridRef"
+        :data="tableSource3.dataSource"
+        :total="tableSource3.total"
+        :loading="tableSource3.loading"
+        :current="tableSource3.current"
+        :page-size="tableSource3.pageSize"
+        :columns="columnList3"
+        :keyWord="keyWord"
+        height="100%"
+        @change="tableSource3.onTableChange"
+    >
+        <template #toolbar>
+            <e-toolbar-m>
+                <template #filter>
+                    <e-toolbar-search-m :search-list="searchList" @advance-search="onAdvanceSearch" />
+                </template>
+            </e-toolbar-m>
+        </template>
+    </e-data-grid-m>
+</template>
+
+<script lang="ts" setup>
+    import { reactive } from 'vue';
+    import { useTableDataSource } from '@epoint-fe/eui-hooks';
+
+    const params = reactive({
+        userName: '',
+        loginId: '',
+        ouName: ''
+    });
+    // 列配置
+    const columnList3: Record<string, any>[] = [
+        {
+            dataIndex: 'itemName',
+            title: '事项名称'
+        },
+        {
+            dataIndex: 'ouName',
+            title: '所在部门'
+        },
+        {
+            dataIndex: 'date',
+            title: '办理时间'
+        },
+        {
+            dataIndex: 'schedule',
+            title: '预约时间'
+        },
+        {
+            dataIndex: 'age',
+            title: '年龄',
+            width: 100
+        },
+        {
+            title: '操作',
+            key: 'action', // 操作列
+            action: {
+                items: [
+                    {
+                        icon: 'Edit',
+                        label: '修改',
+                        onClick: (row) => {
+                            ejs.ui.toast('修改' + row.itemName);
+                        },
+                        visible: (row) => row.itemName === '我是事项1'
+                    },
+                    {
+                        icon: 'Setting',
+                        label: '配置',
+                        onClick: (row) => {
+                            ejs.ui.toast('配置' + row.itemName);
+                        },
+                        disabled: (row) => row.itemName === '我是事项2'
+                    }
+                ]
+            }
+        }
+    ];
+    // tableSource3 具备以下属性： { dataSource, pageSize, current, total, loading, refresh, onTableChange }
+    const tableSource3 = useTableDataSource('/frameaction/getDataGridData', {
+        idField: 'userGuid',
+        columns: columnList3,
+        params
+    });
+    const keyWord = ref('');
+    const dataGridRef = ref();
+    const onAdvanceSearch = (filterRes, searchValue) => {
+        // 修改列表请求的查询参数
+        params.searchParams = filterRes.conditions;
+        params.logicOperator = filterRes.logicOperator;
+        // 更新列表的关键字，使关键字高亮
+        keyWord.value = searchValue;
+        // 触发列表刷新
+        dataGridRef.value.refresh();
+    };
+    const searchList = ref([
+        {
+            label: '复合搜索',
+            field: 'searchField',
+            type: 'mixSearch', // 复合搜索
+            default: true,
+            operation: 'EQ',
+            operations: [
+                {
+                    label: '等于',
+                    value: 'EQ'
+                },
+                {
+                    label: '不等于',
+                    value: 'NQ'
+                },
+                {
+                    label: '包含',
+                    value: 'IN'
+                },
+                {
+                    label: '不包含',
+                    value: 'NOTIN'
+                }
+            ],
+            data: [
+                { label: '事项名称', value: 'itemName' },
+                { label: '所在部门', value: 'ouName' },
+                { label: '年龄', value: 'age' }
+            ]
+        },
+        {
+            label: '事项名称',
+            field: 'itemName',
+            type: 'input',
+            default: true,
+            operation: 'EQ',
+            operations: [
+                {
+                    label: '等于',
+                    value: 'EQ'
+                },
+                {
+                    label: '不等于',
+                    value: 'NQ'
+                },
+                {
+                    label: '包含',
+                    value: 'IN'
+                },
+                {
+                    label: '不包含',
+                    value: 'NOTIN'
+                }
+            ]
+        },
+        {
+            label: '办理时间',
+            field: 'date',
+            type: 'datePicker',
+            default: true,
+            operation: 'EQ',
+            operations: [
+                {
+                    label: '等于',
+                    value: 'EQ'
+                },
+                {
+                    label: '不等于',
+                    value: 'NQ'
+                },
+                {
+                    label: '介于',
+                    value: 'BTW',
+                    type: 'rangeDatePicker'
+                }
+            ]
+        },
+        {
+            label: '预约时间',
+            field: 'schedule',
+            type: 'rangeDatePicker',
+            default: true,
+            operation: 'BTW',
+            operations: [
+                {
+                    label: '介于',
+                    value: 'BTW'
+                },
+                {
+                    label: '不介于',
+                    value: 'NOTBTW'
+                }
+            ]
+        },
+        {
+            label: '所在部门',
+            field: 'ouName',
+            type: 'select',
+            default: true,
+            operation: 'EQ',
+            operations: [
+                {
+                    label: '等于',
+                    value: 'EQ'
+                },
+                {
+                    label: '不等于',
+                    value: 'NQ',
+                    type: 'select',
+                    url: '/frametoolbar/getCodeList'
+                },
+                {
+                    label: '包含',
+                    value: 'IN'
+                },
+                {
+                    label: '不包含',
+                    value: 'NOTIN'
+                }
+            ],
+            data: [
+                {
+                    label: '启用',
+                    value: '1'
+                },
+                {
+                    label: '禁用',
+                    value: '0'
+                }
+            ]
+        },
+        {
+            label: '多选状态',
+            field: 'statusMulti',
+            prop: 'enabled',
+            type: 'multiSelect',
+            default: true,
+            operation: 'EQ',
+            operations: [
+                {
+                    label: '等于',
+                    value: 'EQ'
+                },
+                {
+                    label: '不等于',
+                    value: 'NQ'
+                },
+                {
+                    label: '包含',
+                    value: 'IN'
+                },
+                {
+                    label: '不包含',
+                    value: 'NOTIN'
+                }
+            ],
+            data: [
+                {
+                    label: '启用',
+                    value: '1'
+                },
+                {
+                    label: '禁用',
+                    value: '0'
+                }
+            ]
+        },
+        {
+            label: '数值范围',
+            field: 'numberRange',
+            prop: 'enabled',
+            type: 'rangeNumber',
+            default: true,
+            operation: 'BTW',
+            operations: [
+                {
+                    label: '介于',
+                    value: 'BTW'
+                },
+                {
+                    label: '不介于',
+                    value: 'NOTBTW'
+                }
+            ]
+        }
+    ]);
+</script>
+```
+
+## 批处理
+
+组件默认开启长按进入批处理，可通过 `longPressBatch` 配置关闭。
+
+关闭长按进入批处理的情况下，仍可通过 `showSelectionColumn` 开启批处理。
+
+通过`rowSelection`设置单选多选、自定义底部按钮组、选中行变化回调等。
+
+组件通过 `confirm` 事件返回最终选中行数据。
+
+```html
+<template>
+    <e-data-grid-m
+        id-field="userGuid"
+        :data="tableSource5.dataSource"
+        :total="tableSource5.total"
+        :loading="tableSource5.loading"
+        :current="tableSource5.current"
+        :page-size="tableSource5.pageSize"
+        :columns="columnList5"
+        showSelectionColumn
+        :rowSelection="rowSelection"
+        height="100%"
+        dragSort
+        @change="tableSource5.onTableChange"
+        @confirm="onConfirm"
+    ></e-data-grid-m>
+</template>
+
+<script lang="ts" setup>
+    import { reactive } from "vue";
+    import { useTableDataSource } from "@epoint-fe/eui-hooks";
+
+    const params = reactive({
+      userName: "",
+      loginId: "",
+      ouName: "",
+    });
+    const rowSelection = ref({
+      type: "checkbox", // 选择框类型，'checkbox' 多选，'radio' 单选
+      selections: true, // 为true时使用默认按钮组, 为false时不展示底部按钮，也可传一个数组自定义按钮组
+      selectedRowKeys: ["2", "3"], // 选中的行的 key 数组, 需要和 onChange 进行配合
+      onChange: (selectedRowKeys: string[], selectedRows: object[]) => {
+        // 选中的行的 key 数组改变时的回调
+        console.log("onChange", selectedRowKeys, selectedRows);
+        rowSelection.value.selectedRowKeys = selectedRowKeys;
+      },
+      onSelect: (record: object, selected: boolean, selectedRows: object[]) => {
+        // 手动选择/取消某一行时的回调
+        console.log("onSelect", record, selected, selectedRows);
+      },
+    });
+    const columnList5: Record<string, any>[] = [
+      {
+        dataIndex: "itemName",
+        title: "事项名称",
+      },
+      {
+        dataIndex: "ouName",
+        title: "所在部门",
+      },
+      {
+        dataIndex: "age",
+        title: "年龄",
+      },
+      ...
+    ];
+    // tableSource 具备以下属性： { dataSource, pageSize, current, total, loading, refresh, onTableChange }
+    const tableSource5 = useTableDataSource("/frameaction/getDataGridData", {
+      idField: "userGuid",
+      columns: columnList5,
+      params,
+    });
+    const onConfirm = (selectedRows: object[]) => {
+      console.log('onConfirm', selectedRows);
+      ejs.ui.toast('选中' + selectedRows.length + '行');
+    };
+</script>
+```
+
+## API
+
+### Attributes
+
+| 属性名              | 描述                           | 类型                | 默认值                                   |
+| ------------------- | ------------------------------ | ------------------- | ---------------------------------------- |
+| idField             | 主键字段名，必填               | `string`            | `-`                                      |
+| data                | 表格数据源                     | `array`             | []                                       |
+| total               | 总记录数                       | `number`            | `-`                                      |
+| loading             | 是否在加载中                   | `boolean`           | `-`                                      |
+| pageSize            | 每页大小                       | `number`            | `-`                                      |
+| current             | 当前页码                       | `number`            | `-`                                      |
+| initPageIndex       | 初始页码                       | `number`            | `1`                                      |
+| columns             | 列配置，详见下                 | `array`             | `[]`                                     |
+| showSelectionColumn | 是否开启批处理                 | `boolean`           | `false`                                  |
+| longPressBatch      | 是否长按开启批处理             | `boolean`           | `true`                                   |
+| rowSelection        | 批处理相关配置，详见下         | `object`            | `{ type: 'checkbox', selections: true }` |
+| height              | 组件整体高度，单位默认是 `px`  | `number` / `string` | `100vh`                                  |
+| dragSort            | 批处理状态下是否开启拖拽排序   | `boolean`           | `false`                                  |
+| highlight           | 搜索关键字高亮样式             | `string`            | `color: #2e6be5`                         |
+| keyWord             | 关键字，用于匹配需要高亮的文字 | `string`            | -                                        |
+
+### Columns 配置项
+
+| 属性名    | 描述                                                       | 类型               | 默认值 |
+| --------- | ---------------------------------------------------------- | ------------------ | ------ |
+| dataIndex | 列对应数据字段名                                           | `string`           | `-`    |
+| title     | 列标题                                                     | `string`           | `-`    |
+| isTitle   | 列数据内容是否作为行标题，不配置时行标题默认使用第一列数据 | `boolean`          | `-`    |
+| isStatus  | 列数据内容是否作为状态展示                                 | `boolean`          | `-`    |
+| key       | 该项的 key，key === 'action’ 时该项是操作列                | `string`           | `-`    |
+| action    | 操作列配置，详见下                                         | `{ items: array }` | `-`    |
+
+#### action.items 数组配置项
+
+| 属性名            | 描述                                      | 类型                                      | 默认值    |
+| ----------------- | ----------------------------------------- | ----------------------------------------- | --------- |
+| label             | 操作项名称                                | `string`                                  | `-`       |
+| swipeAction       | 是否在侧滑中展示，侧滑展示的按钮数量 <= 3 | `boolean`                                 | `false`   |
+| swipeActionType   | 侧滑展示的按钮颜色类型                    | `primary`、`danger`、`warning`、`success` | `primary` |
+| showInActionSheet | 是否在点击列表项的 ... 后展示             | `boolean`                                 | `true`    |
+| onClick           | 点击该操作项回调                          | `(row: object（行数据）) => void`         | `-`       |
+| visible           | 操作项显隐判断方法                        | `(row: object（行数据）) => boolean`      | `-`       |
+| disabled          | 操作项禁用判断方法                        | `(row: object（行数据）) => boolean`      | `-`       |
+
+#### rowSelection 配置项
+
+批处理相关配置项
+
+| 属性名                | 描述                                                                     | 类型                                                                        | 默认值     |
+| --------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ---------- |
+| type                  | 选择框类型，`checkbox` 多选，`radio` 单选                                | `string`                                                                    | `checkbox` |
+| selections            | 自定义选择项，为`true`时使用默认选择项，详见下                           | `INTERNAL_SELECTION_ITEM[]` / `boolean`                                     | `true`     |
+| hideDefaultSelections | 隐藏全选与反选按钮                                                       | `boolean`                                                                   | `false`    |
+| hideSelectAll         | 隐藏全选与自定义选择项                                                   | `boolean`                                                                   | `false`    |
+| selectedRowKeys       | 选中行的 key 数组, 需要和 `onChange` 进行配合                            | `Key[]`                                                                     | `[]`       |
+| onChange              | 选中行的 key 数组改变时的回调                                            | `(selectedRowKeys: string[], selectedRows: object[]) => void`               | `-`        |
+| getCheckboxProps      | 可通过该方法设置返回 `ep-checkbox` 组件的 props，详见 `ep-checkbox` 文档 | `(rows: RecordType) => any`                                                 | `-`        |
+| onSelect              | 手动选择/取消某一行时的回调                                              | `(currRow: object, selected: boolean, selectedRows: object[]) => void`      | `-`        |
+| onSelectAll           | 手动全选时的回调                                                         | `(selected: boolean, selectedRows: object[], changeRows: object[]) => void` | `-`        |
+| onSelectInvert        | 手动反选时的回调                                                         | `(selectedRowKeys: object[]) => void`                                       | `-`        |
+| onSelectNone          | 清空选择时的回调                                                         | `() => void`                                                                | `-`        |
+
+`INTERNAL_SELECTION_ITEM` 说明：
+
+```ts
+type INTERNAL_SELECTION_ITEM = SelectionItem | 'SELECT_ALL' | 'SELECT_INVERT' | 'SELECT_NONE';
+```
+
+`SelectionItem` 配置项说明：
+
+| 属性名   | 描述                       | 类型                              | 默认值 |
+| -------- | -------------------------- | --------------------------------- | ------ |
+| key      | 自定义按钮的 key，必填     | `string`                          | `-`    |
+| text     | 自定义按钮显示的文本，必填 | `string`                          | `-`    |
+| onSelect | 点击自定义按钮的回调       | `(currentRowKeys: Key[]) => void` | `-`    |
+
+### Events
+
+| 事件    | 说明                         | 参数                                                   |
+| ------- | ---------------------------- | ------------------------------------------------------ |
+| change  | 分页变化时触发               | `pagination: { current: number, pageSize: number }`    |
+| confirm | 批处理点击顶部完成按钮时触发 | `selectedRows: RecordType[]`, `listData: RecordType[]` |
+
+### slots
+
+| 名称     | 说明                                                                           | SlotProps                                                   |
+| -------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| bodyCell | 对应列表里 PC 端单元格内容                                                     | text: string, record: object, index: number, column: object |
+| list     | 整体列表内容, 使用该插槽时，批处理、左滑、拖拽排序等功能不再支持，需要自行实现 | listData: object[]                                          |
+| toolbar  | 列表顶部内容，可在此插入 toolbar 工具                                          | -                                                           |
+
+### Methods
+
+| 方法名           | 说明                   | 参数 |
+| ---------------- | ---------------------- | ---- |
+| refresh          | 刷新列表               | `-`  |
+| clearSelection   | 清空已选               | `-`  |
+| getSelectionRows | 获取已选行数据         | `-`  |
+| resize           | 重新计算移动端列表高度 | `-`  |
+
+::: ifdef M84
+<iframe
+ src="//app.epoint.com.cn/m8mpdoc/showcase/m8.4/index.html#/modules/epshowcase/examples/ep-data-grid-m"
+ frameborder=0
+ allowfullscreen class="ui-showcase-iframe">
+</iframe>
+::: endif
+
+<style>
+ .ui-showcase-iframe {
+    position: fixed;
+    right: 3.5vw;
+    top: 17%;
+    width: 375px;
+    height: 75vh;
+    box-shadow: 0 0 12px 6px #eee;
+    border-radius: 15px;
+ }
+ .main .markdown-body {
+    padding: 45px;
+    width: calc(97vw - 661px);
+}
+ </style>