el-lists
列表式、清单型数据展示组件,相比表格展示el-table-ts (opens new window)会更突出某一系列数据
# 特性
- 传递 data 和 column 两个必要属性即可渲染出列表。
- 支持 slot / jsx(参考 babel-plugin-transform-vue-jsx (opens new window)) / h 函数三种方式自定义渲染列项标题,列项数据。
- 可同级渲染列,并支持展开/关闭,使得同类数据归纳更便捷。
- 集成 el-pagination 分页组件,并扩展插槽,自定义分页渲染更便捷。
- 完善的类型声明,可完美运行在 ts 项目中。
# 安装和引入
安装
npm install el-lists -S
引入
该组件强依赖于 element-ui,请确保使用该组件前已引入
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
import ElLists from 'el-lists'
import 'el-lists/dist/el-lists.css'
Vue.use(ElementUI)
Vue.use(ElLists)
2
3
4
5
6
7
8
# 阅前约定
列由多个列项组成,列项由列项标题、列项数据(列项值)组成
例如 姓名(列项标题): 刘飞朋(列项数据)
# 基础用法
data
和 columns
两个属性
data
定义表格数据,columns
定义列属性
该组件内置状态status
、标题title
,因此你需要在data
对象数组中定义这两个属性的值,更多内置属性请查看
- 1
# 定义列头数据
该组件内置了列标题title,列状态status,列状态描述statusType三种属性,如果你不指定,相应位置则什么都不渲染
statusType 的值也可为 css class(样式类名),这时你可以自己写status的样式
- 1
# 控制列项的显示与隐藏
使用columns
对象中的hidden
属性来控制列项的显示与隐藏,查看详情
- 1
# 布局
el-lists 组件布局基于 element layout
通过组件的 layout 属性定义列表布局,layout 对象结构为{row, col}
,分别对应Row Attributes (opens new window),Col Attributes (opens new window)。
同时columns属性中也支持col属性定义单项布局,且优先级高于layout.col
- 1
# 内置 showTooltip
组件在数据超过其容器宽度时将会折叠数据text-overflow: ellipsis;
,鼠标移入后将会激活一个 toolTip,将折叠的数据完全显示。
行配置项中,配置 showTooltip: false
将不激活 toolTip,但数据依旧被折叠
- 1
# 内置插槽
# left
列头左侧插槽(即 status,title 所在位置),只有在 status、title 都未指定,status、title 插槽都未指定的情况下才起作用,可获取的数据有该列所有的数据及**h**函数
使用方式参考:
#left="{data, h}"
或#left="row" 此时 row = {data, h}
- 1
# status
列状态插槽,可获取的数据有该列所有的数据及**h**函数
使用方式参考:
#status="{data, h}"
或#status="row" 此时 row = {data, h}
- 1
# title
列标题插槽,可获取的数据有该列所有的数据及**h**函数
使用方式参考:
#title="{data, h}"
或#title="row" 此时 row = {data, h}
- 1
# right
列头右侧插槽,可获取的数据有该列所有的数据及**h**函数
使用方式参考:
#right="{data, h}"
或#right="row" 此时 row = {data, h}
- 1
# opera
列右侧操作区域插槽,可获取的数据有该列所有的数据及**h**函数
使用方式参考:
#opera="{data, h}"
或#opera="row" 此时 row = {data, h}
- 1
# 自定义列-列项标题/列项值
支持 jsx/slot/h
函数三种方式的自定义渲染。 你可以在自定义渲染中获取到 {} 对象 slot
语法:可以在列属性scopedSlots.customRender
的属性值设置为 slot 名称,然后在
template 模板中写 slot jsx/h 语法:可直接在列定义中设置customRender
函数中返回
JSX(注意此时需要 jsx 支持),或者返回 h 函数生成的 VNode。
- 1
# 折叠与展开
应用场景,同一标题下有相同的列表数据
可在定义列表数据时通过extra
属性传入更多的数据
- 1
# scroll 事件
按下 F12(打开控制台),滚动表格查看scroll
事件
- 1
# 集成 pagination
默认展示
分页器,参考 el-pagination 文档 (opens new window),
默认分页配置为
const defPagination = {
currentPage: 1,
pageSizes: [10, 20, 30, 50],
pageSize: 10,
layout: 'prev, pager, next, sizes, total',
background: true,
}
2
3
4
5
6
7
增加内置插槽,名为pagination
(使用方法见下方代码示例),可访问到总数total
,分页配置项config
注意
el-pagination 中的 current-change 事件改为 page-change
- 1
- 2
- 3
- 4
- 5
- 6
- 10
# API
# el-lists 属性
参数 | 类型 | 默认值 | 说明 |
---|---|---|---|
data | Array | [] | 列表数据 详细见data-attributes |
columns | Array | [] | column item 配置列表, 详细见columns-attributes |
pagination | Object|Boolean | true | { currentPage: 1, pageSizes: [10, 20, 30, 50], pageSize: 10, layout: 'prev, pager, next, sizes, total', background: true } | 翻页器配置,默认显示翻页器。 相关 api 可查看el-pagination (opens new window) |
total | Number | 0 | 翻页器条数总数 |
layout | Object | { row: { gutter: 20, }, // 优先级低于 columns 列配置内的 col 配置项 col: { span: 6 }, } | 整体的布局配置,基于element Layout 布局 (opens new window) |
# el-lists 事件
事件名称 | 说明 | 说明 |
---|---|---|
scroll | el-lists 滚动事件 | e |
page-change | currentPage 改变时会触发 | { pageSize, currentPage } |
size-change | pageSize 改变时会触发 | { pageSize, currentPage } |
prev-click | 用户点击上一页按钮改变当前页后触发 | { pageSize, currentPage } |
next-click | 用户点击下一页按钮改变当前页后触发 | { pageSize, currentPage } |
# data Attributes 属性
以下属于内置属性
属性 | 类型 | 默认值 | 说明 |
---|---|---|---|
title | string | ||
status | string | ||
statusType | string | 'wait' |
内置的 statusType | 值 |
---|---|
’success‘ | #00C1CE |
‘error’ | #FF637B |
’warning‘ | #EEC08E |
‘wait’ | #92A5FC |
’back‘ | #C0C4CC |
’other‘ | #FF9BAA |
# columns Attributes 属性
属性 | 类型 | 默认值 | 说明 |
---|---|---|---|
label | String | 列项名称 | |
prop | String | 列项数据字段,支持多层对象嵌套,如 user.age | |
hidden | Boolean |Function | false | 是否隐藏该列。为 Function 时,可以在回调函数中获取当前列的所有数据,需返回一个 boolean 值来确定隐藏与否 |
showTooltip | Boolean | 是否在列表项数据被折叠,鼠标移入时展示一个 toolTip | |
col | Object | col-attributes (opens new window) | |
customRender | Function | 自定义列数据渲染。customRender({cellValue, row, column, $index, h, store, _self}),支持 jsx 和 h 函数 | |
customTitle | Function | 自定义列头部渲染。({column, $index, h, store, _self}),支持 jsx 和 h 函数 | |
scopedSlots | Object | 使用 slot 方式自定义渲染,可替换 customRender/customTitle 函数,优先级低。比如:scopedSlots: { customRender: 'slotName1', customTitle: 'slotName2' } |
# 内置插槽
内置分页器插槽,名为pagination
使用见集成-pagination 章节示例,可访问到总数total
,分页配置项`config