List 列表

介绍

滚动加载，用于展示长列表，当列表即将滚动到底部/顶部时，会触发事件并加载更多列表项。

基础用法

需要搭配 scroller 或 scrollbar 组件使用，在页面滚动到一定阈值后触发加载下一页。

<vd-scroller name="page" scroll-y>
  <vd-list
    v-model:loading="state.loading"
    v-model:error="state.error"
    :finished="state.finished"
    scroller="page"
    @load="hanleLoad"
  >
    <view v-for="item in state.data" :key="item.id" class="item">
      {{ item.name }}
    </view>
  </vd-list>
</vd-scroller>

const state = reactive({
  data: [] as any[],
  error: false,
  loading: false,
  finished: false,
});

// 模拟请求数据
async function getListData() {
  await timeout(300);
  const len = state.data.length;

  if (len >= 50) {
    return [];
  }

  return Array.from({ length: 5 }, num => num + len);
}

// 模拟加载下一页
async function hanleLoad() {
  const data = await getListData();

  if (!data.length) {
    state.finished = true; // 没有更多数据
  } else {
    state.data = [...state.data, ...data];
  }

  state.loading = false;
}

.item {
  padding: $vd-padding-md;
  border-radius: $vd-radius-md;
  background: $vd-background;
  color: $vd-color-text;
  font-size: $vd-font-size-md;

  & + .item {
    margin-top: $vd-padding-sm;
  }
}

API

Props

参数	说明	类型	默认值
loading	是否处于加载状态，加载过程中不触发 load 事件	boolean	false
error	是否加载失败，加载失败后点击错误提示可以重新触发 load 事件	boolean	false
finished	是否已加载完成，加载完成后不再触发 load 事件	boolean	false
offset	滚动条与顶/底部距离小于 offset 时触发 load 事件	string | number	200
direction	滚动触发加载的方向，可选值为 up down	ListDirection	'down'
show-loding	是否展示加载中提示	boolean	true
loading-type	加载中类型，同 loading 组件加载类型	LoadingType	-
loading-text	加载中状态时的提示文案	string	-
show-error	是否展示加载失败提示	boolean	true
error-text	加载失败状态时的提示文案	string	-
show-finished	是否展示加载完成后提示	boolean	true
finished-text	加载完成后状态时的提示文案	string	-
immediate	是否在初始化时立即执行滚动位置检查	boolean	true
disabled	是否禁用滚动加载	boolean	false
scroller	监听滚动事件的滚动条节点名称，默认是监听最近的可 y轴 滚动的滚动条	string	-

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
load	加载下一页时触发	-
update:loading	加载状态更新时触发	boolean
update:error	错误状态更新时触发	boolean

Slots

名称	说明
default	自定义内容
loading	加载中提示
error	加载失败提示
finished	加载完成提示

Expose

方法名	说明	参数	返回值
check	检查是否到达触发位置	-	Promise<void>

类型定义

组件导出以下类型定义：

import type {
  ListDirection,
  ListInstance,
  ListThemeVars,
} from 'vital-design';

主题变量

通过 ConfigProvider 的 theme-vars.list 覆盖：

名称	说明	默认值
status-color	状态区文字颜色	$vd-color-text-3
status-font-size	状态区字号	$vd-font-size-md
status-line-height	状态区行高	$vd-line-height-md
status-padding	状态区（loading / error / finished）内边距	$vd-padding-sm $vd-padding-md
status-loading-icon-size	加载图标尺寸	$vd-font-size-lg
status-loading-icon-gap	加载图标与文案间距	$vd-gap-xs