介紹

瀑布流滾動(dòng)加載，用于展示長(zhǎng)列表，當(dāng)列表即將滾動(dòng)到底部時(shí)，會(huì)觸發(fā)事件并加載更多列表項(xiàng)。

引入

通過(guò)以下方式來(lái)全局注冊(cè)組件，更多注冊(cè)方式請(qǐng)參考組件注冊(cè)。

import { createApp } from 'vue';
import { List } from 'vant';

const app = createApp();
app.use(List);

代碼演示

基礎(chǔ)用法

List 組件通過(guò) ?loading? 和 ?finished? 兩個(gè)變量控制加載狀態(tài)，當(dāng)組件滾動(dòng)到底部時(shí)，會(huì)觸發(fā) ?load? 事件并將 ?loading? 設(shè)置成 ?true?。此時(shí)可以發(fā)起異步操作并更新數(shù)據(jù)，數(shù)據(jù)更新完畢后，將 ?loading? 設(shè)置成 ?false? 即可。若數(shù)據(jù)已全部加載完畢，則直接將 ?finished? 設(shè)置成 ?true? 即可。

<van-list
  v-model:loading="loading"
  :finished="finished"
  finished-text="沒有更多了"
  @load="onLoad"
>
  <van-cell v-for="item in list" :key="item" :title="item" />
</van-list>

import { ref } from 'vue';

export default {
  setup() {
    const list = ref([]);
    const loading = ref(false);
    const finished = ref(false);

    const onLoad = () => {
      // 異步更新數(shù)據(jù)
      // setTimeout 僅做示例，真實(shí)場(chǎng)景中一般為 ajax 請(qǐng)求
      setTimeout(() => {
        for (let i = 0; i < 10; i++) {
          list.value.push(list.value.length + 1);
        }

        // 加載狀態(tài)結(jié)束
        loading.value = false;

        // 數(shù)據(jù)全部加載完成
        if (list.value.length >= 40) {
          finished.value = true;
        }
      }, 1000);
    };

    return {
      list,
      onLoad,
      loading,
      finished,
    };
  },
};

錯(cuò)誤提示

若列表數(shù)據(jù)加載失敗，將 ?error? 設(shè)置成 ?true? 即可顯示錯(cuò)誤提示，用戶點(diǎn)擊錯(cuò)誤提示后會(huì)重新觸發(fā) load 事件。

<van-list
  v-model:loading="loading"
  v-model:error="error"
  error-text="請(qǐng)求失敗，點(diǎn)擊重新加載"
  @load="onLoad"
>
  <van-cell v-for="item in list" :key="item" :title="item" />
</van-list>

import { ref } from 'vue';

export default {
  setup() {
    const list = ref([]);
    const error = ref(false);
    const loading = ref(false);
    const onLoad = () => {
      fetchSomeThing().catch(() => {
        error.value = true;
      });
    };

    return {
      list,
      error,
      onLoad,
      loading,
    };
  },
};

下拉刷新

List 組件可以與 PullRefresh 組件結(jié)合使用，實(shí)現(xiàn)下拉刷新的效果。

<van-pull-refresh v-model="refreshing" @refresh="onRefresh">
  <van-list
    v-model:loading="loading"
    :finished="finished"
    finished-text="沒有更多了"
    @load="onLoad"
  >
    <van-cell v-for="item in list" :key="item" :title="item" />
  </van-list>
</van-pull-refresh>

import { ref } from 'vue';

export default {
  setup() {
    const list = ref([]);
    const loading = ref(false);
    const finished = ref(false);
    const refreshing = ref(false);

    const onLoad = () => {
      setTimeout(() => {
        if (refreshing.value) {
          list.value = [];
          refreshing.value = false;
        }

        for (let i = 0; i < 10; i++) {
          list.value.push(list.value.length + 1);
        }
        loading.value = false;

        if (list.value.length >= 40) {
          finished.value = true;
        }
      }, 1000);
    };

    const onRefresh = () => {
      // 清空列表數(shù)據(jù)
      finished.value = false;

      // 重新加載數(shù)據(jù)
      // 將 loading 設(shè)置為 true，表示處于加載狀態(tài)
      loading.value = true;
      onLoad();
    };

    return {
      list,
      onLoad,
      loading,
      finished,
      onRefresh,
      refreshing,
    };
  },
};

API

Props

Events

方法

通過(guò) ref 可以獲取到 List 實(shí)例并調(diào)用實(shí)例方法，詳見組件實(shí)例方法。

類型定義

組件導(dǎo)出以下類型定義：

import type { ListProps, ListInstance, ListDirection } from 'vant';

ListInstance 是組件實(shí)例的類型，用法如下：

import { ref } from 'vue';
import type { ListInstance } from 'vant';

const listRef = ref<ListInstance>();

listRef.value?.check();

Slots

主題定制

樣式變量

組件提供了下列 CSS 變量，可用于自定義樣式，使用方法請(qǐng)參考 ConfigProvider 組件。

常見問題

List 的運(yùn)行機(jī)制是什么？

List 會(huì)監(jiān)聽瀏覽器的滾動(dòng)事件并計(jì)算列表的位置，當(dāng)列表底部與可視區(qū)域的距離小于 ?offset? 時(shí)，List 會(huì)觸發(fā)一次 ?load? 事件。

為什么 List 初始化后會(huì)立即觸發(fā) load 事件？

List 初始化后會(huì)觸發(fā)一次 load 事件，用于加載第一屏的數(shù)據(jù)，這個(gè)特性可以通過(guò) ?immediate-check? 屬性關(guān)閉。

為什么會(huì)連續(xù)觸發(fā) load 事件？

如果一次請(qǐng)求加載的數(shù)據(jù)條數(shù)較少，導(dǎo)致列表內(nèi)容無(wú)法鋪滿當(dāng)前屏幕，List 會(huì)繼續(xù)觸發(fā) ?load? 事件，直到內(nèi)容鋪滿屏幕或數(shù)據(jù)全部加載完成。

因此你需要調(diào)整每次獲取的數(shù)據(jù)條數(shù)，理想情況下每次請(qǐng)求獲取的數(shù)據(jù)條數(shù)應(yīng)能夠填滿一屏高度。

loading 和 finished 分別是什么含義？

?List? 有以下三種狀態(tài)，理解這些狀態(tài)有助于你正確地使用 ?List? 組件：

• 非加載中，?loading? 為 ?false?，此時(shí)會(huì)根據(jù)列表滾動(dòng)位置判斷是否觸發(fā) ?load? 事件（列表內(nèi)容不足一屏幕時(shí)，會(huì)直接觸發(fā)）。
• 加載中，?loading? 為 ?true?，表示正在發(fā)送異步請(qǐng)求，此時(shí)不會(huì)觸發(fā) ?load? 事件。
• 加載完成，?finished? 為 ?true?，此時(shí)不會(huì)觸發(fā) ?load? 事件。

在每次請(qǐng)求完畢后，需要手動(dòng)將 ?loading? 設(shè)置為 ?false?，表示加載結(jié)束。

使用 float 布局后一直觸發(fā)加載？

若 List 的內(nèi)容使用了 float 布局，可以在容器上添加 ?van-clearfix? 類名來(lái)清除浮動(dòng)，使得 List 能正確判斷元素位置。

<van-list>
  <div class="van-clearfix">
    <div class="float-item" />
    <div class="float-item" />
    <div class="float-item" />
  </div>
</van-list>

在 html、body 上設(shè)置 overflow 后一直觸發(fā)加載？

如果在 html 和 body 標(biāo)簽上設(shè)置了 ?overflow-x: hidden? 樣式，會(huì)導(dǎo)致 List 一直觸發(fā)加載。

html,
body {
  overflow-x: hidden;
}

這個(gè)問題的原因是當(dāng)元素設(shè)置了 ?overflow-x: hidden? 樣式時(shí)，該元素的 ?overflow-y? 會(huì)被瀏覽器設(shè)置為 ?auto?，而不是默認(rèn)值 ?visible?，導(dǎo)致 List 無(wú)法正確地判斷滾動(dòng)容器。解決方法是去除該樣式，或者在 html 和 body 標(biāo)簽上添加 ?height: 100%? 樣式。

direction 屬性設(shè)置為 up 后一直觸發(fā)加載？

設(shè)置 ?direction? 屬性為 up 后，當(dāng)滾動(dòng)條處于頁(yè)面頂部時(shí)，就會(huì)觸發(fā) List 組件的加載。

因此在使用該屬性時(shí)，建議在每次數(shù)據(jù)加載完成后，將滾動(dòng)條滾動(dòng)至頁(yè)面底部或非頂部的位置。