鸿蒙uni-app x瀑布流waterflow组件API与适配实战

鸿蒙专家

在鸿蒙平台使用uni-app x开发时，瀑布流布局是电商、社区类应用的常见需求。waterflow是uni-app x提供的瀑布流组件，底层实现与list-view基本一致，都基于回收复用机制，子组件滑出屏幕会被回收，区别在于waterflow多列排列，list-view单列。鸿蒙4.81开始支持waterflow，且不支持Web和微信小程序。组件选择上，瀑布流用waterflow，单列列表用list-view，其他用scroll-view。

兼容性方面，鸿蒙平台API 20及以上版本支持滚动相关事件，API 18及以上版本支持load-more插槽。waterflow暂时只支持flow-item作为子组件，其他组件不可见。flow-item是瀑布流的子组件，每个flow-item代表一列内容，其type属性用于区分类型。

waterflow核心属性包括：cross-axis-count（列数）、cross-axis-gap（列间距）、main-axis-gap（行间距）、padding（内边距数组）、refresher-enabled（是否开启下拉刷新）、refresher-triggered（刷新状态）、refresher-default-style（下拉刷新样式，可设为none自定义）、associative-container（嵌套滚动关联容器）。事件有：@refresherrefresh（下拉刷新触发）、@scrolltolower（滚动到底部）、@scroll（滚动）、@refresherpulling（下拉中）、@refresherrestore（复位）、@refresherabort（中止）。load-more插槽用于上拉加载更多。

下面通过几个实战场景说明用法。

场景一：基础瀑布流。使用v-for循环生成flow-item，设置type='1'，每个卡片随机高度。

2. <template>
3. <waterflow style='flex: 1;'>
4. <flow-item v-for='(item, index) in dataList' :key='index' type='1'>
5. <view style='padding: 10px;'>
6. <view :style='{ height: item.height + "px", backgroundColor: item.color, borderRadius: "8px", alignItems: "center", justifyContent: "center" }'>
7. <text style='font-size: 16px; color: white; font-weight: bold;'>{{item.text}}</text>
8. </view>
9. </view>
10. </flow-item>
11. </waterflow>
12. </template>
13. <script setup lang='uts'>
14. type FlowItem = {
15. height: number
16. color: string
17. text: string
18. }
19. const colors = ['#E91E63', '#9C27B0', '#3F51B5', '#009688', '#FF9800', '#795548', '#607D8B']
20. const dataList = ref([] as Array<FlowItem>)
21. for (let i = 0; i < 30; i++) {
22. dataList.value.push({
23. height: 100 + Math.floor(Math.random() * 200),
24. color: colors[i % colors.length],
25. text: '卡片 ' + (i + 1)
26. })
27. }
28. </script>

复制代码

场景二：商品列表瀑布流。两列布局，支持下拉刷新和上拉加载。关键属性：cross-axis-count='2'，cross-axis-gap='8'，main-axis-gap='8'，refresher-enabled='true'。load-more插槽的flow-item设置type='2'。

2. <template>
3. <waterflow :cross-axis-count='2' :cross-axis-gap='8' :main-axis-gap='8'
4. :padding='[0, 8, 8, 8]'
5. :refresher-enabled='true' :refresher-triggered='isRefreshing'
6. @refresherrefresh='onRefresh'
7. @scrolltolower='loadMore'
8. style='flex: 1;'>
9. <flow-item v-for='(item, index) in productList' :key='index' type='1'>
10. <view style='background-color: white; border-radius: 8px; overflow: hidden; margin-bottom: 8px;'>
11. <image :src='item.image' style='width: 100%; height: 200px;' mode='aspectFill'></image>
12. <view style='padding: 8px;'>
13. <text style='font-size: 14px; color: #333; lines: 2;'>{{item.title}}</text>
14. <view style='flex-direction: row; align-items: center; margin-top: 6px;'>
15. <text style='font-size: 16px; color: #F44336; font-weight: bold;'>¥{{item.price}}</text>
16. <text style='font-size: 12px; color: #999; margin-left: 5px; text-decoration: line-through;'>¥{{item.originalPrice}}</text>
17. </view>
18. <text style='font-size: 12px; color: #999; margin-top: 4px;'>{{item.sales}}人付款</text>
19. </view>
20. </view>
21. </flow-item>
22. <flow-item slot='load-more' type='2'>
23. <view style='padding: 15px; align-items: center;'>
24. <text style='font-size: 14px; color: #999;'>{{loadingText}}</text>
25. </view>
26. </flow-item>
27. </waterflow>
28. </template>
29. <script setup lang='uts'>
30. type Product = {
31. title: string
32. image: string
33. price: string
34. originalPrice: string
35. sales: string
36. }
37. const productList = ref([] as Array<Product>)
38. const isRefreshing = ref(false)
39. const loadingText = ref('加载更多...')
40. const page = ref(1)
41. const loadProducts = () => {
42. productList.value = []
43. for (let i = 1; i <= 20; i++) {
44. productList.value.push({
45. title: '这是商品标题，可能会比较长，需要两行显示',
46. image: 'https://picsum.photos/200/' + (200 + i * 10),
47. price: (99 + i * 10).toString(),
48. originalPrice: (199 + i * 10).toString(),
49. sales: (100 + i * 50).toString()
50. })
51. }
52. }
53. const onRefresh = () => {
54. isRefreshing.value = true
55. page.value = 1
56. loadingText.value = '加载更多...'
57. setTimeout(() => {
58. loadProducts()
59. isRefreshing.value = false
60. uni.showToast({ title: '刷新成功', icon: 'success' })
61. }, 1500)
62. }
63. const loadMore = () => {
64. if (loadingText.value == '没有更多了') return
65. loadingText.value = '加载中...'
66. setTimeout(() => {
67. const start = productList.value.length
68. for (let i = 1; i <= 15; i++) {
69. productList.value.push({
70. title: '新加载的商品标题 ' + (start + i),
71. image: 'https://picsum.photos/200/' + (200 + (start + i) * 10),
72. price: (99 + (start + i) * 10).toString(),
73. originalPrice: (199 + (start + i) * 10).toString(),
74. sales: (100 + (start + i) * 50).toString()
75. })
76. }
77. page.value++
78. if (page.value >= 5) {
79. loadingText.value = '没有更多了'
80. } else {
81. loadingText.value = '加载更多...'
82. }
83. }, 1000)
84. }
85. onMounted(() => {
86. loadProducts()
87. })
88. </script>

复制代码

场景三：图片瀑布流。类似小红书，图片高度随机，展示作者和点赞数。

2. <template>
3. <waterflow :cross-axis-count='2' :cross-axis-gap='6' :main-axis-gap='6'
4. :padding='[6, 6, 6, 6]'
5. style='flex: 1;'>
6. <flow-item v-for='(item, index) in imageList' :key='index' type='1'>
7. <view style='border-radius: 8px; overflow: hidden; background-color: white;'>
8. <image :src='item.url' :style='{ width: "100%", height: item.height + "px" }' mode='aspectFill'></image>
9. <view style='padding: 8px;'>
10. <text style='font-size: 14px; color: #333; lines: 2;'>{{item.desc}}</text>
11. <view style='flex-direction: row; align-items: center; margin-top: 6px; justify-content: space-between;'>
12. <view style='flex-direction: row; align-items: center;'>
13. <image :src='item.avatar' style='width: 20px; height: 20px; border-radius: 10px; margin-right: 5px;'></image>
14. <text style='font-size: 12px; color: #666;'>{{item.author}}</text>
15. </view>
16. <text style='font-size: 12px; color: #999;'>{{item.likes}}</text>
17. </view>
18. </view>
19. </view>
20. </flow-item>
21. </waterflow>
22. </template>
23. <script setup lang='uts'>
24. type ImageItem = {
25. url: string
26. height: number
27. desc: string
28. avatar: string
29. author: string
30. likes: string
31. }
32. const imageList = ref([] as Array<ImageItem>)
33. for (let i = 0; i < 20; i++) {
34. const h = 150 + Math.floor(Math.random() * 150)
35. imageList.value.push({
36. url: 'https://picsum.photos/200/' + h,
37. height: h,
38. desc: '这是第 ' + (i + 1) + ' 张图片的描述，可能会比较长',
39. avatar: 'https://picsum.photos/50/50',
40. author: '用户' + (i + 1),
41. likes: (Math.floor(Math.random() * 1000)).toString()
42. })
43. }
44. </script>

复制代码

场景四：三列瀑布流。设置cross-axis-count='3'即可。

2. <template>
3. <waterflow :cross-axis-count='3' :cross-axis-gap='5' :main-axis-gap='5'
4. :padding='[5, 5, 5, 5]'
5. style='flex: 1;'>
6. <flow-item v-for='(item, index) in dataList' :key='index' type='1'>
7. <view :style='{ height: item.height + "px", backgroundColor: item.color, borderRadius: "5px", alignItems: "center", justifyContent: "center" }'>
8. <text style='font-size: 13px; color: white;'>{{item.text}}</text>
9. </view>
10. </flow-item>
11. </waterflow>
12. </template>
13. <script setup lang='uts'>
14. type FlowItem = {
15. height: number
16. color: string
17. text: string
18. }
19. const colors = ['#E91E63', '#9C27B0', '#3F51B5', '#009688', '#FF9800', '#795548']
20. const dataList = ref([] as Array<FlowItem>)
21. for (let i = 0; i < 30; i++) {
22. dataList.value.push({
23. height: 80 + Math.floor(Math.random() * 150),
24. color: colors[i % colors.length],
25. text: '' + (i + 1)
26. })
27. }
28. </script>

复制代码

场景五：自定义下拉刷新。设置refresher-default-style='none'，使用slot='refresher'的flow-item，并监听refresherpulling事件改变提示文字。注意自定义刷新元素不要放在第一个子元素位置。

2. <template>
3. <waterflow
4. refresher-default-style='none'
5. :refresher-enabled='true'
6. :refresher-triggered='isRefreshing'
7. @refresherpulling='onPulling'
8. @refresherrefresh='onRefresh'
9. @refresherrestore='onRestore'
10. @refresherabort='onAbort'
11. :cross-axis-count='2' :cross-axis-gap='8' :main-axis-gap='8'
12. style='flex: 1;'>
13. <flow-item v-for='(item, index) in dataList' :key='index' type='1'>
14. <view style='padding: 8px;'>
15. <view :style='{ height: item.height + "px", backgroundColor: "#E3F2FD", borderRadius: "8px", alignItems: "center", justifyContent: "center" }'>
16. <text style='font-size: 15px; color: #1976D2;'>{{item.text}}</text>
17. </view>
18. </view>
19. </flow-item>
20. <flow-item slot='refresher' type='2'>
21. <view style='height: 50px; align-items: center; justify-content: center;'>
22. <text style='font-size: 14px; color: #2196F3;'>{{refreshText}}</text>
23. </view>
24. </flow-item>
25. </waterflow>
26. </template>
27. <script setup lang='uts'>
28. type FlowItem = {
29. height: number
30. text: string
31. }
32. const dataList = ref([] as Array<FlowItem>)
33. const isRefreshing = ref(false)
34. const refreshText = ref('下拉刷新')
35. const onPulling = (event: UniRefresherEvent) => {
36. if (event.detail.dy > 45) {
37. refreshText.value = '释放立即刷新'
38. } else {
39. refreshText.value = '下拉刷新'
40. }
41. }
42. const onRefresh = () => {
43. isRefreshing.value = true
44. refreshText.value = '正在刷新...'
45. setTimeout(() => {
46. loadData()
47. isRefreshing.value = false
48. }, 1500)
49. }
50. const onRestore = () => {
51. refreshText.value = '下拉刷新'
52. }
53. const onAbort = () => {
54. refreshText.value = '下拉刷新'
55. }
56. const loadData = () => {
57. dataList.value = []
58. for (let i = 0; i < 20; i++) {
59. dataList.value.push({
60. height: 100 + Math.floor(Math.random() * 150),
61. text: '卡片 ' + (i + 1)
62. })
63. }
64. }
65. onMounted(() => {
66. loadData()
67. })
68. </script>

复制代码

场景六：嵌套滚动。将waterflow嵌套在scroll-view中，使用type='nested'，并设置waterflow的associative-container='nested-scroll-view'，配合nested-scroll-header和nested-scroll-body。

2. <template>
3. <scroll-view type='nested' style='flex: 1;'>
4. <nested-scroll-header>
5. <view style='height: 200px; background-color: #E3F2FD; align-items: center; justify-content: center;'>
6. <text style='font-size: 18px; color: #1976D2;'>头部区域</text>
7. </view>
8. </nested-scroll-header>
9. <nested-scroll-body>
10. <waterflow
11. associative-container='nested-scroll-view'
12. :cross-axis-count='2' :cross-axis-gap='8' :main-axis-gap='8'
13. style='flex: 1;'>
14. <flow-item v-for='i in 30' :key='i' type='1'>
15. <view style='padding: 8px;'>
16. <view :style='{ height: (100 + i * 10) + "px", backgroundColor: "#E8F5E9", borderRadius: "8px", alignItems: "center", justifyContent: "center" }'>
17. <text>卡片 {{i}}</text>
18. </view>
19. </view>
20. </flow-item>
21. </waterflow>
22. </nested-scroll-body>
23. </scroll-view>
24. </template>

复制代码

完整实战示例：一个商品瀑布流综合页面，包含标题栏、两列商品、下拉刷新、上拉加载和滚动监听。

2. <template>
3. <view style='flex: 1;'>
4. <view style='height: 45px; background-color: white; border-bottom: 1px solid #eee; align-items: center; justify-content: center;'>
5. <text style='font-size: 16px; font-weight: bold;'>商品瀑布流</text>
6. </view>
7. <waterflow
8. :cross-axis-count='2' :cross-axis-gap='8' :main-axis-gap='8'
9. :padding='[0, 8, 8, 8]'
10. :refresher-enabled='true' :refresher-triggered='isRefreshing'
11. @refresherrefresh='onRefresh'
12. @scrolltolower='loadMore'
13. @scroll='onScroll'
14. style='flex: 1;'>
15. <flow-item v-for='(item, index) in productList' :key='index' type='1'>
16. <view style='background-color: white; border-radius: 8px; overflow: hidden; margin-bottom: 8px;'>
17. <image :src='item.image' :style='{ width: "100%", height: item.imgHeight + "px" }' mode='aspectFill'></image>
18. <view style='padding: 8px;'>
19. <text style='font-size: 14px; color: #333; lines: 2;'>{{item.title}}</text>
20. <view style='flex-direction: row; align-items: center; margin-top: 6px;'>
21. <text style='font-size: 16px; color: #F44336; font-weight: bold;'>¥{{item.price}}</text>
22. <text style='font-size: 12px; color: #999; margin-left: 5px; text-decoration: line-through;'>¥{{item.originalPrice}}</text>
23. </view>
24. <view style='flex-direction: row; align-items: center; margin-top: 4px; justify-content: space-between;'>
25. <text style='font-size: 12px; color: #999;'>{{item.sales}}人付款</text>
26. <text style='font-size: 12px; color: #FF9800;'>{{item.shop}}</text>
27. </view>
28. </view>
29. </view>
30. </flow-item>
31. <flow-item slot='load-more' type='2'>
32. <view style='padding: 15px; align-items: center;'>
33. <text style='font-size: 14px; color: #999;'>{{loadingText}}</text>
34. </view>
35. </flow-item>
36. </waterflow>
37. </view>
38. </template>
39. <script setup lang='uts'>
40. type Product = {
41. title: string
42. image: string
43. imgHeight: number
44. price: string
45. originalPrice: string
46. sales: string
47. shop: string
48. }
49. const productList = ref([] as Array<Product>)
50. const isRefreshing = ref(false)
51. const loadingText = ref('加载更多...')
52. const page = ref(1)
53. const scrollPos = ref(0)
54. const shops = ['旗舰店', '自营店', '专营店', '专卖店']
55. const loadProducts = () => {
56. productList.value = []
57. for (let i = 1; i <= 20; i++) {
58. const h = 180 + Math.floor(Math.random() * 100)
59. productList.value.push({
60. title: '这是商品标题，可能会比较长需要两行显示 ' + i,
61. image: 'https://picsum.photos/200/' + h,
62. imgHeight: h,
63. price: (99 + i * 10).toString(),
64. originalPrice: (199 + i * 10).toString(),
65. sales: (100 + i * 50).toString(),
66. shop: shops[i % shops.length]
67. })
68. }
69. }
70. const onRefresh = () => {
71. isRefreshing.value = true
72. page.value = 1
73. loadingText.value = '加载更多...'
74. setTimeout(() => {
75. loadProducts()
76. isRefreshing.value = false
77. uni.showToast({ title: '刷新成功', icon: 'success' })
78. }, 1500)
79. }
80. const loadMore = () => {
81. if (loadingText.value == '没有更多了') return
82. loadingText.value = '加载中...'
83. setTimeout(() => {
84. const start = productList.value.length
85. for (let i = 1; i <= 15; i++) {
86. const h = 180 + Math.floor(Math.random() * 100)
87. productList.value.push({
88. title: '新加载的商品 ' + (start + i),
89. image: 'https://picsum.photos/200/' + h,
90. imgHeight: h,
91. price: (99 + (start + i) * 10).toString(),
92. originalPrice: (199 + (start + i) * 10).toString(),
93. sales: (100 + (start + i) * 50).toString(),
94. shop: shops[(start + i) % shops.length]
95. })
96. }
97. page.value++
98. if (page.value >= 5) {
99. loadingText.value = '没有更多了'
100. } else {
101. loadingText.value = '加载更多...'
102. }
103. }, 1000)
104. }
105. const onScroll = (event: UniScrollEvent) => {
106. scrollPos.value = event.detail.scrollTop
107. }
108. onMounted(() => {
109. loadProducts()
110. })
111. </script>

复制代码

注意事项：自定义下拉刷新元素不能放在第一个子元素位置；load-more插槽的flow-item需设置type='2'；鸿蒙平台滚动相关事件需API 20及以上版本，load-more插槽需API 18及以上版本；waterflow子组件仅支持flow-item。

总结：waterflow为鸿蒙平台uni-app x提供了高效的瀑布流实现，底层基于回收复用，支持多列布局、下拉刷新、上拉加载及嵌套滚动。开发时需注意鸿蒙版本兼容性和子组件限制，合理使用属性与事件即可快速构建商品列表、图片社区等场景。