# UGridView 数据网格 - [示例](#示例) - [基本用法](#基本用法) - [只读状态、禁用状态、禁用某一项](#只读状态-禁用状态-禁用某一项) - [可取消](#可取消) - [多项选择](#多项选择) - [添加头部](#添加头部) - [添加尾部](#添加尾部) - [自定义内容](#自定义内容) - [表单验证](#表单验证) - [修改尺寸](#修改尺寸) - [过滤（搜索）](#过滤搜索) - [后端过滤（搜索）](#后端过滤搜索) - [前端分页与加载更多](#前端分页与加载更多) - [后端分页与加载更多](#后端分页与加载更多) - [自定义内容](#自定义内容-2) - [自定义内容](#自定义内容-3) - [结合卡片](#结合卡片) - [API]() - [Props/Attrs](#propsattrs) - [Slots](#slots) - [Events](#events) - [Methods](#methods) **Table** 用于列举大量数据的列表框，支持单选、多选、过滤（搜索）、分页等功能。 ## 示例 ### 基本用法 默认为单选模式，使用`v-model`双向绑定值。使用`data-source`属性添加数据，有两种方式： #### data-source 数组 直接向`data-source`属性中传入`Array`格式的数组，每个`Item`为这样格式的对象`{ text: string, value: any, disabled: boolean, ... }`。 ``` vue ``` #### data-source 函数 向`data-source`属性中传入一个加载函数，这种方式会自带 loading 加载、error 错误等效果，并且在下文中的前后端分页、过滤（搜索）等功能均需要采用这种传入数据的方式。 加载函数的格式是这样的 ``` ts (params) => Promise | { data: Array, total: number } | { data: Array, last: boolean }> ``` 组件会给加载函数提供过滤（搜索）、分页、加载更多等参数，要求返回一个如上的 Promise。 ``` vue ``` #### 指定选项字段名 如果你的数据中选项文本和值的字段不一定叫`'text'`和`'value'`，可以通过`text-field`和`value-field`两个属性快速指定。 ``` vue ``` ### 只读状态、禁用状态、禁用某一项 使用`disabled`属性禁用整个组件。在 item 对象中添加`disabled: true` 可以禁用掉对应选项。 ``` vue ``` ### 可取消 在单选模式中，设置`cancelable`属性，可以取消已选择的项。 尝试在同一个选项上点击两次。 ``` vue ``` ### 多项选择 使用`multiple`属性开启多选模式。注意：此时`v-model`双向绑定的类型为一个数组`Array`。 ``` vue ``` ### 添加头部 使用`show-head`属性可以添加头部，使用`title`属性修改列表标题。 ``` vue ``` ### 添加尾部 ``` vue ``` ### 自定义内容 ``` vue ``` ### 表单验证 ``` vue ``` ### 修改尺寸 通过`size`属性设置`normal`、`large`、`huge`、`full`、`auto`几种尺寸，宽高可以自由组合。 如果以上几种预设不能满足，也可以直接添加`style="width: 200px; height: 600px;"`来设置。 ``` vue ``` ### 过滤（搜索） #### 前端过滤（搜索） 如果数据源本身为前端数据或是从后端一次性拿过来的，设置`filterable`属性即可开启过滤功能。用于快速查找选项。 ``` vue ``` #### 匹配方式 在`match-method`属性中可以配置字符串的匹配方式，常见的有`includes`、`startsWith`、`endsWith`，也可以传一个函数。 ``` vue ``` #### 区分大小写 默认不区分大小写，可用`case-sensitive`属性开启。 ``` vue ``` ### 后端过滤（搜索） 如果需要通过后端接口进行过滤，在开启`filterable`属性的基础上，还要开启`remote-filtering`属性。 这时需要用最前面提到的 data-source 函数的方式传入数据。 加载函数的格式是这样的`({ filterText: string }) => Promise, total: number } | { data: Array, last: boolean }>>`。组件会给加载函数提供过滤输入框中的文本，要求返回一个 Promise。 可以看下面的示例，在数据栏中`result`为最新一次模拟请求的返回数据。 ``` vue ``` ### 前端分页与加载更多 #### 前端分页 如果数据源本身为前端数据或是从后端一次性拿过来的，设置`pageable`或`pageable="pagination"`即可开启分页功能，用`page-size`属性修改分页大小。 ``` vue ``` #### 加载更多 设置`pageable="load-more"`可开启手动点击加载更多功能，设置`pageable="auto-more"`可开启滚动自动加载更多功能。 ``` vue ``` ### 后端分页与加载更多 如果需要通过后端接口进行分页或加载更多，在开启`pageable`属性的基础上，还要开启`remote-paging`属性。 这时需要用最前面提到的 data-source 函数的方式传入数据。 加载函数的格式是这样的： ``` ts ({ paging: { size: number, // 每页大小 number: number, // 页数。从1开始计 offset: number, // 偏移量：(number - 1) * size limit: number, // 同 size } }) => Promise | { data: Array, total: number } | { data: Array, last: boolean }> ``` 组件会给加载函数提供分页器或加载位置的参数，要求返回如上的一个 Promise。翻页是否到底，如果 Promise 的结果为： - `{ data: Array, total: number }`，根据 total 数值判断是否翻到最底部 - `{ data: Array, last: boolean }`，根据 last 布尔值判断是否为最后一次 - `Array`，则根据数组为空判断为最后一次 可以看下面的示例，在数据栏中`result?`为最新一次模拟请求的返回数据。 ``` vue ``` ### 自定义内容 ``` vue ``` ### 自定义内容 ``` vue ``` ### 结合卡片 ``` vue ``` ## API ### Props/Attrs | Prop/Attr | Type | Options | Default | Description | | --------- | ---- | ------- | ------- | ----------- | | value.sync, v-model | any | | | 当前选择的值 | | field | string | | `'text'` | 选项文本的字段名 | | cancelable | boolean | | `false` | | | multiple | boolean | | `false` | | | clearable | boolean | | `false` | 搜索框是否有清除按钮 | | data-source | Array\ \| Function \| object \| DataSource | | | 展示数据的输入源，可设置为数据集对象或者返回数据集的逻辑 | | data-schema | schema | | | 数据源返回的数据结构的类型，自动识别类型进行展示说明 | | text-field | string | | `'text'` | 选项文本的字段名 | | value-field | string | | `'value'` | 选项值的字段名 | | pageable | boolean | | `false` | 设置是否分页展示数据 | | page-size | number | | `50` | | | page-number | number | | `1` | 当前默认展示在第几页 | | page-size-options | Array\ | | `[10, 20, 50]` | 每页条数切换器的选项 | | show-total | boolean | | `false` | | | show-sizer | boolean | | `false` | 显示每页条数切换器 | | show-jumper | boolean | | `false` | 显示页面跳转输入框 | | remote-paging | boolean | | `false` | | | remote-filtering | boolean | | `false` | | | match-method | string, Function | | `'includes'` | 过滤时的匹配方法 | | case-sensitive | string, Function | | `'includes'` | 过滤时是否区分大小写 | | placeholder | string | | `'请输入'` | 开启筛选后，搜索框为空时的占位符提示文本 | | repeat | number | | `5` | 每行排列几项 | | show-head | boolean | | `false` | | | title | string | | `'列表'` | | | show-foot | boolean | | `true` | | | initial-load | boolean | | `true` | 设置初始时是否立即加载 | | designer-mode | string | `[object Object]`
`[object Object]`
`[object Object]`
`[object Object]` | `'success'` | 设置不同状态的展示内容 | | loading-text | string | | `'正在加载中...'` | 加载中状态显示的提示文案 | | loading | boolean | | | 支持自定义状态的触发条件，未设置则默认为系统定义条件 | | error-text | string | | `'加载失败，请重试'` | 加载失败状态显示的提示文案 | | error | boolean | | | 加载失败状态的触发条件，未设置则默认为系统定义条件 | | empty-text | string | | `'暂无数据'` | 暂无数据状态显示的提示文案 | | readonly | boolean | | `false` | 正常显示，但禁止选择/输入 | | disabled | boolean | | `false` | 置灰显示，且禁止任何交互（焦点、点击、选择、输入等） | | width | string | `[object Object]`
`[object Object]`
`[object Object]`
`[object Object]`
`[object Object]` | `'auto'` | 设置数据网格宽度大小 | | height | string | `[object Object]`
`[object Object]`
`[object Object]`
`[object Object]`
`[object Object]` | `'normal'` | 设置数据网格高度大小 | ### Slots #### (default) 插入文本或 HTML #### item 自定义选项的结构和样式 ### Events #### @before-select 选择某一项前触发 | Param | Type | Description | | ----- | ---- | ----------- | | $event.value | any | 选择项的值 | | $event.oldValue | any | 旧的值 | | $event.item | object | 选择项相关对象 | | $event.itemVM | UListViewItem | 选择项子组件 | | $event.preventDefault | Function | 阻止选择流程 | | senderVM | UListView | 发送事件实例 | #### @input 选择某一项时触发 | Param | Type | Description | | ----- | ---- | ----------- | | $event | any | 选择项的值 | | senderVM | UListView | 发送事件实例 | #### @select 选择某一项时触发。单选模式中： | Param | Type | Description | | ----- | ---- | ----------- | | $event.value | any | 改变后的值 | | $event.oldValue | any | 旧的值 | | $event.item | object | 选择项相关对象 | | $event.oldItem | object | 旧的选择项相关对象 | | $event.itemVM | UListViewItem | 选择项子组件 | | $event.oldVM | UListViewItem | 旧的选择项子组件 | | senderVM | UListView | 发送事件实例 | #### @change 选择值改变时触发。单选模式中： | Param | Type | Description | | ----- | ---- | ----------- | | $event.value | any | 选择项的值 | | $event.oldValue | any | 旧的值 | | $event.item | object | 选择项相关对象 | | $event.oldItem | object | 旧的选择项相关对象 | | $event.itemVM | UListViewItem | 选择项子组件 | | $event.oldVM | UListViewItem | 旧的选择项子组件 | | senderVM | UListView | 发送事件实例 | #### @before-load 加载前触发 | Param | Type | Description | | ----- | ---- | ----------- | | $event.preventDefault | Function | 阻止加载流程 | | senderVM | UTableView | 发送事件实例 | #### @load 加载时触发 | Param | Type | Description | | ----- | ---- | ----------- | | $event | | 空 | | senderVM | UTableView | 发送事件实例 | Methods #### reload() 清除缓存，重新加载 | Param | Type | Default | Description | | ----- | ---- | ------- | ----------- |