A list component to show items and control loading status.
\nRegister component globally via app.use, refer to Component Registration for more registration ways.
import { createApp } from 'vue';\nimport { List } from 'vant';\n\nconst app = createApp();\napp.use(List);\n<van-list\n v-model:loading="loading"\n :finished="finished"\n finished-text="Finished"\n @load="onLoad"\n>\n <van-cell v-for="item in list" :key="item" :title="item" />\n</van-list>\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const list = ref([]);\n const loading = ref(false);\n const finished = ref(false);\n\n const onLoad = () => {\n setTimeout(() => {\n for (let i = 0; i < 10; i++) {\n list.value.push(list.value.length + 1);\n }\n loading.value = false;\n\n if (list.value.length >= 40) {\n finished.value = true;\n }\n }, 1000);\n };\n\n return {\n list,\n onLoad,\n loading,\n finished,\n };\n },\n};\n<van-list\n v-model:loading="loading"\n v-model:error="error"\n error-text="Request failed. Click to reload"\n @load="onLoad"\n>\n <van-cell v-for="item in list" :key="item" :title="item" />\n</van-list>\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const list = ref([]);\n const error = ref(false);\n const loading = ref(false);\n const onLoad = () => {\n fetchSomeThing().catch(() => {\n loading.value = false;\n error.value = true;\n });\n };\n\n return {\n list,\n error,\n onLoad,\n loading,\n };\n },\n};\n<van-pull-refresh v-model="refreshing" @refresh="onRefresh">\n <van-list\n v-model:loading="loading"\n :finished="finished"\n finished-text="Finished"\n @load="onLoad"\n >\n <van-cell v-for="item in list" :key="item" :title="item" />\n </van-list>\n</van-pull-refresh>\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const list = ref([]);\n const loading = ref(false);\n const finished = ref(false);\n const refreshing = ref(false);\n\n const onLoad = () => {\n setTimeout(() => {\n if (refreshing.value) {\n list.value = [];\n refreshing.value = false;\n }\n\n for (let i = 0; i < 10; i++) {\n list.value.push(list.value.length + 1);\n }\n loading.value = false;\n\n if (list.value.length >= 40) {\n finished.value = true;\n }\n }, 1000);\n };\n\n const onRefresh = () => {\n finished.value = false;\n loading.value = true;\n onLoad();\n };\n\n return {\n list,\n onLoad,\n loading,\n finished,\n onRefresh,\n refreshing,\n };\n },\n};\n| Attribute | \nDescription | \nType | \nDefault | \n
|---|---|---|---|
| v-model:loading | \nWhether to show loading info, the load event will not be Emitted when loading | \nboolean | \nfalse | \n
| v-model:error | \nWhether loading is error, the load event will be Emitted only when error text clicked | \nboolean | \nfalse | \n
| finished | \nWhether loading is finished, the load event will not be Emitted when finished | \nboolean | \nfalse | \n
| offset | \nThe load event will be Emitted when the distance between the scrollbar and the bottom is less than offset | \nnumber | string | \n300 | \n
| loading-text | \nLoading text | \nstring | \nLoading... | \n
| finished-text | \nFinished text | \nstring | \n- | \n
| error-text | \nError loaded text | \nstring | \n- | \n
| immediate-check | \nWhether to check loading position immediately after mounted | \nboolean | \ntrue | \n
| disabled | \nWhether to disable the load event | \nboolean | \nfalse | \n
| direction | \nScroll direction, can be set to up | \nstring | \ndown | \n
scroller v4.6.4 | \nSpecifies the node that needs to listen for scroll events, defaults to the nearest parent scroll node | \nElement | \n- | \n
| Event | \nDescription | \nArguments | \n
|---|---|---|
| load | \nEmitted when the distance between the scrollbar and the bottom is less than offset | \n- | \n
Use ref to get List instance and call instance methods.
\n| Name | \nDescription | \nAttribute | \nReturn value | \n
|---|---|---|---|
| check | \nCheck scroll position | \n- | \n- | \n
The component exports the following type definitions:
\nimport type { ListProps, ListInstance, ListDirection } from 'vant';\nListInstance is the type of component instance:
import { ref } from 'vue';\nimport type { ListInstance } from 'vant';\n\nconst listRef = ref<ListInstance>();\n\nlistRef.value?.check();\n| Name | \nDescription | \n
|---|---|
| default | \nList content | \n
| loading | \nCustom loading tips | \n
| finished | \nCustom finished tips | \n
| error | \nCustom error tips | \n
The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.
\n| Name | \nDefault Value | \nDescription | \n
|---|---|---|
| --van-list-text-color | \nvar(--van-text-color-2) | \n- | \n
| --van-list-text-font-size | \nvar(--van-font-size-md) | \n- | \n
| --van-list-text-line-height | \n50px | \n- | \n
| --van-list-loading-icon-size | \n16px | \n- | \n
List will listen to the scroll event of the browser and calculate the position. When the distance between the bottom of the list and the visible area is less than offset, the List component will trigger a load event.
A load event will be triggered immediately to load the first screen data. This feature can be disabled by the immediate-check prop.
If the amount of data loaded in one request is too small, the List will continue to trigger the load event until the content fills the screen or the data is fully loaded.
Therefore, you need to adjust the amount of data per request. Ideally, the amount of data per request should be able to fill the height of one screen.
\nList has three states, understanding these states will help you use the component:
loading = false: Not in loading. The component will detect whether to trigger the load event according to the scroll position (if the content of the list is less than one screen, it will be triggered directly).loading = true: During loading. Indicating that an request is being sent, and the load event will not be triggered.finished = true: Loading is complete. No load will not be triggered.After each request, you need to manually set loading to false, indicating the end of loading.
If you use the float layout on the content, you can add the van-clearfix class to the container to clear the float, so that the List can get the element position correctly.
<van-list>\n <div class="van-clearfix">\n <div class="float-item" />\n <div class="float-item" />\n <div class="float-item" />\n </div>\n</van-list>\nIf the overflow-x: hidden style is set on the html and body tags, it will cause the List to always trigger loading.
html,\nbody {\n overflow-x: hidden;\n}\nThe reason is that when an element is styled with overflow-x: hidden, the element\'s overflow-y will be set to auto by the browser, instead of the default value of visible, causing the List can not determine the scroll container correctly. The workaround is to remove this style, or add the height: 100% style to the html and body tags.
Setting the direction prop to up will trigger the loading of the List component when the scrollbar is at the page top.
When using this prop, it is recommended to scroll the scroll bar to the page bottom after each data request is completed.
\n