Skip to content

ListView 列表视图

ListView 组件用于以摘要信息的形式展示列表数据。

基础用法

通过data属性传入列表数据,可以通过item插槽定制每条数据的显示效果,如果没有item插槽则默认显示数据的文本字段的内容。
当列表滚动到底部时,将触发load事件,用于加载更多数据,可以通过listProps透传其它的列表组件属性。
通过enable-pull-refresh属性可以启用下拉刷新,然后通过refresh事件和v-model:refreshing属性来监听下拉刷新事件并控制刷新状态。
通过enable-multi-select属性可以启用多选功能,v-model:multiSelect属性表示当前是否处于多选状态,用户长按列表条目时将使得列表切换到多选状态。
通过multi-select-toolbar-items属性可以定制多选状态下的按钮工具栏。
通过fill属性可以使列表内容占满高度。

层级列表

通过child-field属性可以指定列表数据的子级条目字段,需要注意的是,只支持一层子级。

类型

typescript
interface ListViewToolbarItem {
  /** 按钮文本 */
  text: string;

  /** 点击事件回调方法 */
  handler: (item: ListViewToolbarItem) => void;

  /** 按钮样式类型 */
  type?: string;

  /** 是否禁用 */
  disabled?: boolean;
}

属性

属性名类型默认值说明
dataany[][]列表数据
enableMultiSelectbooleanfalse是否启用多选功能,默认不启用
multiSelectbooleanfalse是否处于多选状态,支持语法糖v-model:multiSelect,在非多选状态下且enableMultiSelect=true时,用户长按任意列表条目将切换至多选状态
multiSelectToolbarItemsArray as ListViewToolbarItem[][]多选状态下,如果本属性非空则在列表下方显示一个按钮工具栏
idFieldstring'id'ID 字段的编号,ID 字段用于唯一标识一条列表数据
textFieldstring'name'文本字段的编号
disableFieldstring'disabled'禁用字段的编号,如果列表条目数据的禁用字段为真则列表条目禁用勾选
childFieldstring''子级条目字段的编号,如果一条列表数据的子级条目字段非空,则该条数据以分组的形式渲染
selectedValuesstring[][]已勾选条目的 ID 数组
loadingbooleanfalse是否处于加载状态,支持语法糖v-model:loading,此状态下将在列表底部显示加载中提示文本
errorbooleanfalse是否处于加载失败状态,支持语法糖v-model:error,此状态下将在列表底部显示加载失败提示文本,用户点击提示将触发加载事件
finishedbooleanfalse是否加载完成,加载完成后将在列表下方显示加载完成提示文本,且不会再触发加载事件
listPropsObject as ListProps{}列表属性(除了loadingerrorfinished之外的其它列表组件属性)
enablePullRefreshbooleanfalse是否启用下拉刷新
refreshingbooleanfalse是否正在刷新,支持语法糖v-model:refreshingenablePullRefresh为真时有效
pullRefreshPropsObject as PullRefreshProps{}下拉刷新属性(除了modelValue之外的其它下拉刷新组件属性),enablePullRefresh为真时有效
fillbooleanfalse是否占满高度
splitbooleanfalse是否显示分隔线
emptyMessagestring''列表数据为空时显示的占位文本
checkboxPropsObject as CheckboxProps{ shape: 'round' }多选状态下,勾选框的属性

事件

事件名类型说明
loadEventEmitter<void>加载更多事件,列表滚动到底部时触发
clickItemEventEmitter<{ data: any; index: number }>列表条目点击事件,点击列表条目时触发
selectionChangeEventEmitter<any[]>多选变化事件,多选状态下,多选或取消勾选列表条目时触发
refreshEventEmitter<void>下拉刷新事件,下拉刷新时触发

插槽

名称说明
item列表条目
itemGroupHeader层级列表的分组标题
toolbar多选状态下,下方的按钮工具栏
empty列表内容为空时的提示
header列表头部,显示在列表内容和各种提示的上方
footer列表尾部,显示在列表内容和各种提示的下方
finished加载完成提示
loading加载中提示
error加载失败提示
loadMore加载更多提示
pullRefreshPulling下拉刷新,下拉状态下的提示
pullRefreshLoosing下拉刷新,释放状态下的提示
pullRefreshLoading下拉刷新,加载状态下的提示
pullRefreshComplete下拉刷新,刷新完成后的提示
default默认内容

组件实例

名称类型说明
check() => void如果列表已经滚动到底部或者因为内容太少而没有滚动条,则调用本方法将触发load事件
getSelectedItems() => any[]获取当前被勾选的数据
clearSelection() => void取消全部数据的勾选

CSS 变量

名称默认值说明
--fm-listview-checkbox-container-width40px--
--fm-listview-toolbar-height42px--
--fm-listview-split-line-colorrgb(230, 235, 235)--
--fm-listview-empty-text-colorvar(--fm-gray-5)--
--fm-listview-empty-text-font-sizevar(--fm-font-size-md, 14px)--
--fm-listview-empty-text-line-height50px--