【Harmony】鸿蒙自定义革新控件 BaseRefresh

先容

一个功能强盛的下拉革新和加载更多组件，支持自定义革新样式、空页面展示、加载更多状态、头布局和尾布局。组件内置了基础的革新动画、状态管理和数据管理，可以轻松实现列表的革新和加载功能。
功能特点

• 支持下拉革新与上拉加载更多功能
  
• 支持分页加载和数据管理
  
• 适配List/Grid/ScrollView/WaterFlow四种布局范例，也可以自行实现
  
• 内置空布局视图：可传入空布局参数改变空布局样式
  
• 支持自定义空布局
  
• 支持自定义革新样式和加载更多样式
  
• 头部/尾部扩展：支持自定义Header/Footer布局
  
• 支持页面数据不满一屏时主动触发上拉加载（必要手动开启）
  
• 支持数据分组，支持吸顶/吸尾
  
• 支持侧滑功能，包括左侧滑/右侧滑
  
• 兼容 V2 状态（该控件是 V2 控件）
  

链接

源码

示例

效果图

下载安装

在每个har/hsp模块中，通过ohpm工具下载安装库：

1. ohpm install @hzw/zrefresh

复制代码

利用方法

根本利用示例

1.   // BaseRefreshController用于更新刷新状态
2.   @Local controller: BaseRefreshController = new BaseRefreshController()
3. // BaseRefreshDataSource用于更新数据
4.   @Local data: BaseRefreshDataSource<String> = new BaseRefreshDataSource<String>()
6.   aboutToAppear() {
7.     this.controller.autoRefresh()
8.   }
10.   BaseRefresh({
11.     data: this.data, // 设置数据源
12.     controller: this.controller, // 设置状态管理
13.     type: BaseRefreshType.List, // 刷新内容类型，默认为滚动布局
14.     onRefresh: this.onRefresh, // 设置下拉刷新回调
15.     onLoadMore: this.onLoadMore, // 设置加载更多回调
16.     pageSize: 10, // 设置每页加载数量
17.     refreshModifier: new RefreshModifier(), // 设置Refresh样式
18.     listModifier: new ListModifier(), // 设置列表样式
19.     isShowHeader: false, // 设置是否显示头部布局
20.     isShowFooter: false, // 设置是否显示底部布局
21.     emptyStatus: {}, // 设置默认空布局样式，如果设置了，则数据为空时会显示默认布局
22.     customEmptyView: () => { // 设置自定义空布局，如果设置了，则数据为空时会显示自定义布局
23.       this.Empty()
24.     },
25.     customHeadView: () => { // 设置自定义头部布局
26.       this.Head()
27.     },
28.     customFootView: () => { // 设置自定义底部布局
29.       this.Footer()
30.     },
31.     customRefreshHeadView: () => { // 自定义刷新头布局
32.       this.RefreshHead()
33.     },
34.     customRefreshFootView: () => { // 自定义底部加载更多布局
35.       this.RefreshFoot()
36.     },
37.     builder: () => { // 内容
38.       this.Content()
39.     },
41.   })

复制代码

相关方法

触发革新

1. // this.controller 是 BaseRefreshController 的实例
2. this.controller.autoRefresh()

复制代码

添加数据

1. // this.data 是 BaseRefreshDataSource 的实例
2. this.data.complete(moreData)

复制代码

竣事下拉革新/竣事加载更多

1. this.controller.finishRefresh()
2. // 根据数据数量判断是否没有更多数据
3. const data = ["1", "2"]
4. this.controller.finishRefresh(data)
5. // 也可以传入参数来手动设置是否没有更多数据
6. this.controller.finishRefresh(noMore)

复制代码

竣事下拉革新

1. this.controller.finishRefresh()
2. // 根据数据数量判断是否没有更多数据
3. const data = ["1", "2"]
4. this.controller.finishRefresh(data)
5. // 也可以传入参数来手动设置是否没有更多数据
6. this.controller.finishRefresh(noMore)

复制代码

竣事加载更多

1. this.controller.finishLoadMore()
2. // 根据数据数量判断是否没有更多数据
3. const data = ["1", "2"]
4. this.controller.finishLoadMore(data)
5. // 也可以传入参数来手动设置是否没有更多数据
6. this.controller.finishLoadMore(noMore)

复制代码

空页面表现潜伏，不传默认表现

1. this.controller.showEmpty(visible)

复制代码

头布局表现潜伏，不传默认表现

1. this.controller.showHead(visible)

复制代码

底布局表现潜伏，不传默认表现

1. this.controller.showFoot(visible)

复制代码

底部加载更多布局表现潜伏，不传默认表现

1. this.controller.showRefreshFooter(visible)

复制代码

重置状态

1. this.controller.resetStatus()

复制代码

关于 List(列表) 的革新示例，通过BaseRefreshController的实例的complete()方法设置数据

1. @ComponentV2
2. export struct RefreshListDemo {
3.   @Local controller: BaseRefreshController = new BaseRefreshController()
4.   @Local data: BaseRefreshDataSource<String> = new BaseRefreshDataSource<String>()
5.   @Local emptyData: boolean = false
6.   @Local pageSize: number = 15
8.   aboutToAppear() {
9.     this.controller.autoRefresh()
10.   }
12.   onRefresh = () => {
13.     this.loadData()
14.   }
15.   onLoadMore = () => {
16.     this.loadData()
17.   }
19.   loadData() {
20.     setTimeout(() => {
21.       if (this.emptyData) {
22.         this.data.complete([])
23.         this.controller.finishState([])
24.         return
25.       }
27.       const arr: number[] = []
28.       const start = (this.controller.pageIndex - 1) * this.pageSize
29.       if (this.controller.pageIndex == 2) {
30.         for (let i = start; i < start + 5; i++) {
31.           arr.push(i)
32.         }
33.       } else {
34.         for (let i = start; i < start + this.pageSize; i++) {
35.           arr.push(i)
36.         }
37.       }
38.       const result = Array.from(arr, (item, i) => `Item ${item + 1}`)
40.       this.data.complete(result)
41.       this.controller.finishState(result)
42.       return undefined
43.     }, 700)
44.   }
46.   build() {
47.     BaseRefresh({
48.       data: this.data, // 设置数据源
49.       controller: this.controller, // 设置状态管理
50.       type: BaseRefreshType.List, // 刷新内容类型，默认为滚动布局，当前设置为列表类型
51.       onRefresh: this.onRefresh, // 设置下拉刷新回调
52.       onLoadMore: this.onLoadMore, // 设置加载更多回调
53.       pageSize: this.pageSize, // 设置每页加载数量
54.       refreshModifier: new RefreshModifier(), // 设置Refresh样式
55.       listModifier: new ListModifier(), // 设置列表样式
56.       builder: () => { // 内容
57.         this.Content()
58.       },
60.     })
61.   }
63.   @Builder
64.   Content() {
65.     LazyForEach(this.data, (item: string) => {
66.       ListItem() {
67.         Stack() {
68.           Text(`${item}`)
69.             .borderRadius(10)
70.             .fontSize(20)
71.             .fontWeight(FontWeight.Bold)
72.             .fontColor(Color.White)
73.             .width('100%')
74.             .height('100%')
75.             .textAlign(TextAlign.Center)
76.             .backgroundColor(Color.Blue)
77.         }
78.         .width('100%')
79.         .height(100)
80.         .padding({ left: 10, right: 10, top: 10 })
81.       }
82.     }, (item: string, index: number) => `${item}${index}`)
83.   }
84. }

复制代码

关于 Scroll(滚动) 的革新示例

1. @ComponentV2
2. export struct RefreshScrollDemo {
3.   @Local controller: BaseRefreshController = new BaseRefreshController()
4.   @Local emptyData: boolean = false
6.   aboutToAppear() {
7.     this.controller.autoRefresh()
8.   }
10.   onRefresh = () => {
11.     this.loadData()
12.   }
13.   onLoadMore = () => {
14.     this.loadData()
15.   }
17.   loadData() {
18.     setTimeout(() => {
19.       this.controller.showEmpty(this.emptyData)
21.       this.controller.finishRefresh()
22.       return undefined
23.     }, 700)
24.   }
26.   build() {
27.     Column() {
28.       OperateView({
29.         controller: this.controller,
30.         emptyData: this.emptyData!!
31.       })
32.       BaseRefresh({
33.         controller: this.controller, // 设置状态管理
34.         type: BaseRefreshType.ScrollView, // 刷新内容类型，默认为滚动布局，当前设置为滚动类型
35.         onRefresh: this.onRefresh, // 设置下拉刷新回调
36.         onLoadMore: this.onLoadMore, // 设置加载更多回调
37.         refreshModifier: new RefreshModifier(), // 设置Refresh样式
38.         scrollModifier: new ScrollModifier(), // 设置滚动样式
39.         isShowHeader: false, // 设置是否显示头部布局
40.         isShowFooter: false, // 设置是否显示底部布局
41.         emptyStatus: {}, // 设置默认空布局样式，如果设置了，则数据为空时会显示默认布局
42.         customEmptyView: () => { // 设置自定义空布局，如果设置了，则数据为空时会显示自定义布局
43.           this.Empty()
44.         },
45.         customHeadView: () => { // 设置自定义头部布局
46.           this.Head()
47.         },
48.         customFootView: () => { // 设置自定义底部布局
49.           this.Footer()
50.         },
51.         customRefreshHeadView: () => { // 自定义刷新头布局
52.           this.RefreshHead()
53.         },
54.         customRefreshFootView: () => { // 自定义底部加载更多布局
55.           this.RefreshFoot()
56.         },
57.         builder: () => { // 内容
58.           this.Content()
59.         },
61.       })
62.         .width('100%')
63.         .layoutWeight(1)
64.     }
65.     .width('100%')
66.       .height('100%')
67.       .backgroundColor(Color.White)
68.   }
70.   @Builder
71.   Content() {
72.     Stack() {
73.       Text(`滚动内容`)
74.         .borderRadius(10)
75.         .fontSize(20)
76.         .fontWeight(FontWeight.Bold)
77.         .fontColor(Color.White)
78.         .width('100%')
79.         .height('120%')
80.         .textAlign(TextAlign.Center)
81.         .backgroundColor(Color.Orange)
82.     }
83.     .padding({ left: 10, right: 10, top: 10 })
84.   }
86.   @Builder
87.   Empty() {
88.     CustomEmpty()
89.   }
91.   @Builder
92.   Head() {
93.     CustomHead()
94.   }
96.   @Builder
97.   Footer() {
98.     CustomFooter()
99.   }
101.   @Builder
102.   RefreshHead() {
103.     CustomRefreshHead()
104.   }
106.   @Builder
107.   RefreshFoot() {
108.     CustomRefreshFoot({ showEnd: this.controller.showEnd })
109.   }
110. }

复制代码

关于 Grid(网格) 的革新示例

1. @ComponentV2
2. export struct RefreshGridDemo {
3.   @Local controller: BaseRefreshController = new BaseRefreshController()
4.   @Local data: BaseRefreshDataSource<String> = new BaseRefreshDataSource<String>()
5.   @Local emptyData: boolean = false
6.   @Local col: number = 2
7.   @Local pageSize: number = 15
9.   @Computed
10.   get colStr() {
11.     const arr: string[] = []
12.     for (let i = 0; i < this.col; i++) {
13.       arr.push('1fr')
14.     }
15.     return arr.join(' ')
16.   }
18.   aboutToAppear() {
19.     this.controller.autoRefresh()
20.   }
22.   onRefresh = () => {
23.     this.loadData()
24.   }
25.   onLoadMore = () => {
26.     this.loadData()
27.   }
29.   loadData() {
30.     setTimeout(() => {
31.       if (this.emptyData) {
32.         this.data.complete([])
33.         this.controller.finishState([])
34.         return
35.       }
37.       const arr: number[] = []
38.       const start = (this.controller.pageIndex - 1) * this.pageSize
39.       if (this.controller.pageIndex == 2) {
40.         for (let i = start; i < start + 5; i++) {
41.           arr.push(i)
42.         }
43.       } else {
44.         for (let i = start; i < start + this.pageSize; i++) {
45.           arr.push(i)
46.         }
47.       }
48.       const result = Array.from(arr, (item, i) => `Item ${item + 1}`)
50.       this.data.complete(result)
51.       this.controller.finishState(result)
52.       return undefined
53.     }, 700)
54.   }
56.   build() {
57.     BaseRefresh({
58.       data: this.data, // 设置数据源
59.       controller: this.controller, // 设置状态管理
60.       type: BaseRefreshType.Grid, // 刷新内容类型，默认为滚动布局，当前设置为网格类型
61.       onRefresh: this.onRefresh, // 设置下拉刷新回调
62.       onLoadMore: this.onLoadMore, // 设置加载更多回调
63.       pageSize: this.pageSize, // 设置每页加载数量
64.       refreshModifier: new RefreshModifier(), // 设置Refresh样式
65.       gridModifier: new GridModifier().columnsTemplate(this.colStr), // 设置网格样式
66.       builder: () => { // 内容
67.         this.Content()
68.       },
69.     })
70.   }
72.   @Builder
73.   Content() {
74.     LazyForEach(this.data, (item: string) => {
75.       GridItem() {
76.         Stack() {
77.           Text(`${item}`)
78.             .borderRadius(10)
79.             .fontSize(20)
80.             .fontWeight(FontWeight.Bold)
81.             .fontColor(Color.White)
82.             .width('100%')
83.             .height('100%')
84.             .textAlign(TextAlign.Center)
85.             .backgroundColor(Color.Blue)
86.         }
87.         .width('100%')
88.           .height(100)
89.           .padding({ left: 10, right: 10, top: 10 })
90.       }
91.     }, (item: string, index: number) => `${item}${index}`)
92.   }
93. }

复制代码

关于 WaterFlow(瀑布流) 的革新示例

1. @ComponentV2
2. export struct RefreshWaterFlowDemo {
3.   @Local controller: BaseRefreshController = new BaseRefreshController()
4.   @Local data: BaseRefreshDataSource<String> = new BaseRefreshDataSource<String>()
5.   @Local emptyData: boolean = false
6.   @Local col: number = 2
7.   @Local pageSize: number = 15
9.   @Computed
10.   get colStr() {
11.     const arr: string[] = []
12.     for (let i = 0; i < this.col; i++) {
13.       arr.push('1fr')
14.     }
15.     return arr.join(' ')
16.   }
18.   aboutToAppear() {
19.     this.controller.autoRefresh()
20.   }
22.   onRefresh = () => {
23.     this.loadData()
24.   }
25.   onLoadMore = () => {
26.     this.loadData()
27.   }
29.   loadData() {
30.     setTimeout(() => {
31.       if (this.emptyData) {
32.         this.data.complete([])
33.         this.controller.finishState([])
34.         return
35.       }
37.       const arr: number[] = []
38.       const start = (this.controller.pageIndex - 1) * this.pageSize
39.       if (this.controller.pageIndex == 2) {
40.         for (let i = start; i < start + 5; i++) {
41.           arr.push(i)
42.         }
43.       } else {
44.         for (let i = start; i < start + this.pageSize; i++) {
45.           arr.push(i)
46.         }
47.       }
48.       const result = Array.from(arr, (item, i) => `Item ${item + 1}`)
50.       this.data.complete(result)
51.       this.controller.finishState(result)
52.       return undefined
53.     }, 700)
54.   }
56.   build() {
57.     BaseRefresh({
58.       data: this.data, // 设置数据源
59.       controller: this.controller, // 设置状态管理
60.       type: BaseRefreshType.WaterFlow, // 刷新内容类型，默认为滚动布局，当前设置为瀑布流类型
61.       onRefresh: this.onRefresh, // 设置下拉刷新回调
62.       onLoadMore: this.onLoadMore, // 设置加载更多回调
63.       pageSize: this.pageSize, // 设置每页加载数量
64.       refreshModifier: new RefreshModifier(), // 设置Refresh样式
65.       scrollModifier: new ScrollModifier(), // 设置滚动样式，因为瀑布流类型是 Scroll嵌套WaterFlow来实现头尾布局，所以用到了Scroll控件
66.       waterFlowModifier: new WaterFlowModifier().columnsTemplate(this.colStr), // 设置瀑布流样式
67.       builder: () => { // 内容
68.         this.Content()
69.       },
70.     })
71.   }
73.   @Builder
74.   Content() {
75.     LazyForEach(this.data, (item: string, index: number) => {
76.       FlowItem() {
77.         Stack() {
78.           Text(`${item}`)
79.             .borderRadius(10)
80.             .fontSize(20)
81.             .fontWeight(FontWeight.Bold)
82.             .fontColor(Color.White)
83.             .width('100%')
84.             .height('100%')
85.             .textAlign(TextAlign.Center)
86.             .backgroundColor(Color.Blue)
87.         }
88.         .height(Math.random() * 100 + 100)
89.           .padding({ left: 10, right: 10, top: 10 })
90.       }
91.       .width('100%')
92.     }, (item: string, index: number) => `${item}${index}`)
93.   }
94. }

复制代码

关于 No(不指定滚动布局范例，自行实现) 的革新示例

1. @ComponentV2
2. export struct RefreshNoDemo {
3.   @Local controller: BaseRefreshController = new BaseRefreshController()
4.   @Local emptyData: boolean = false
6.   aboutToAppear() {
7.     this.controller.autoRefresh()
8.   }
10.   onRefresh = () => {
11.     this.loadData()
12.   }
13.   onLoadMore = () => {
14.     this.loadData()
15.   }
17.   loadData() {
18.     setTimeout(() => {
19.       this.controller.showEmpty(this.emptyData)
21.       this.controller.finishRefresh()
22.       return undefined
23.     }, 700)
24.   }
26.   build() {
27.     BaseRefresh({
28.       controller: this.controller, // 设置状态管理
29.       type: BaseRefreshType.No, // 刷新内容类型，无滚动类型（不内置滚动控件，交由使用者自定义）
30.       onRefresh: this.onRefresh, // 设置下拉刷新回调
31.       onLoadMore: this.onLoadMore, // 设置加载更多回调
32.       refreshModifier: new RefreshModifier(), // 设置Refresh样式
33.       scrollModifier: new ScrollModifier(), // 设置滚动样式
34.       builder: () => { // 内容
35.         this.Content()
36.       },
37.     })
38.   }
40.   @Builder
41.   Content() {
42.     Scroll() {
43.       Stack() {
44.         Text(`滚动内容`)
45.           .borderRadius(10)
46.           .fontSize(20)
47.           .fontWeight(FontWeight.Bold)
48.           .fontColor(Color.White)
49.           .width('100%')
50.           .height('120%')
51.           .textAlign(TextAlign.Center)
52.           .backgroundColor(Color.Orange)
53.       }
54.       .padding({ left: 10, right: 10, top: 10 })
55.     }
56.   }
57. }

复制代码

参数分析

BaseRefresh 组件参数

参数名范例默认值必填分析dataBaseAbsRefreshDataSource | undefinedundefined是数据源，需继续BaseAbsRefreshDataSourcetypeBaseRefreshTypeScrollView否内容范例：List/ScrollView/Grid/WaterFlow/NoenableRefreshbooleantrue否是否启用下拉革新enableLoadMorebooleantrue否是否启用加载更多pageSizenumber20否每页加载数量controllerBaseRefreshControllernew BaseRefreshController()是状态控制器scrollerScrollernew Scroller()是滚动控制器实例refreshModifierRefreshModifiernew RefreshModifier()否革新控件样式设置listModifierListModifiernew ListModifier()否列表样式设置scrollModifierScrollModifiernew ScrollModifier()否滚动视图样式设置gridModifierGridModifiernew GridModifier()否网格布局样式设置waterFlowModifierWaterFlowModifiernew WaterFlowModifier()否瀑布流样式设置listItemModifierListItemModifiernew ListItemModifier()否列表项样式设置（需设置listBuilder收效）onRefresh() => Promise<Object[]|undefined>async () => {}是下拉革新回调函数onLoadMore() => Promise<Object[]|undefined>async () => {}是加载更多回调函数builder() => voidthis.doBuilder是内容构建函数listBuilder(data: Object, index: number) => voidundefined否列表项构建函数（设置后builder属性失效）swipeLeftBuilder(data: Object, index: number) => voidundefined否列表项左滑布局（需设置listBuilder收效）swipeRightBuilder(data: Object, index: number) => voidundefined否列表项右滑布局（需设置listBuilder收效）isShowHeaderbooleanfalse否是否表现头部布局isShowFooterbooleanfalse否是否表现底部布局isShowRefreshFooterbooleantrue否是否表现加载更多布局groupDataBaseAbsRefreshDataSource | undefinedundefined是分组数据源（需设置listBuilder收效）listItemGroupModifierListItemGroupModifiernew ListItemGroupModifier()否列表项分组样式设置（需设置listBuilder和groupData收效）listItemGroupHeadBuilder(data: BaseRefreshGroupItem, index: number) => voidundefined否列表分组头部构建函数（需设置listBuilder和groupData收效）listItemGroupFootBuilder(data: BaseRefreshGroupItem, index: number) => voidundefined否列表分组底部构建函数（需设置listBuilder和groupData收效）groupStyleListItemGroupStyle | undefinedundefined否列表分组样式设置（需设置listBuilder和groupData收效）isGroupTopStickybooleantrue否列表分组是否顶部吸顶（需设置listBuilder和groupData收效）isGroupFootStickybooleanfalse否列表分组是否底部吸顶（需设置listBuilder和groupData收效）isAutoLoadMoreWhileNoFullbooleanfalse否页面数据不满一屏时是否主动触发上拉加载customEmptyView() => voidundefined否自定义空布局组件customHeadView() => voidundefined否自定义头部布局customFootView() => voidundefined否自定义底部布局customRefreshHeadView() => voidundefined否自定义革新头部组件customRefreshFootView() => voidundefined否自定义加载底部组件emptyStatusBaseRefreshEmptyStatus | undefinedundefined否空布局状态设置gridLayoutOptionsGridLayoutOptions | undefinedundefined否网格布局设置选项BaseRefreshController 类方法

方法名参数返回值分析autoRefresh-void主动触发革新finishStatenoMore: (Object | undefined | null)[] | undefined | null | booleanvoid根据当前状态竣事革新/加载finishRefreshnoMore?: (Object | undefined | null)[] | undefined | null | booleanvoid竣事革新状态finishLoadMorenoMore?: (Object | undefined | null)[] | undefined | null | booleanvoid竣事加载更多状态showEmptyvisible?: boolean控制空页面表现showHeadvisible?: booleanvoid控制头部布局表现状态showFootvisible?: booleanvoid控制底部布局表现状态showRefreshFootervisible?: booleanvoid控制加载更多布局表现状态resetStatus-void重置全部状态到初始值（包罗refreshing/loadMore/showEnd等）onScrollIndexstart: number, end: numbervoid列表/网格滚动索引变革回调，当滚动到底部时触发加载onScrollEdgeedge: Edgevoid滚动视图到达边沿回调（Edge.Bottom时触发加载）onScrollFrameBeginoffset: numberBaseRefreshOffsetInterface滚动偏移量变革回调，用于判断滑动方向BaseRefreshDataSource 类方法

方法名参数返回值分析add1stItemdata: Tvoid在列表头部插入元素addLastItemdata: Tvoid在列表尾部追加元素addItemindex: number, data: Tvoid在指定位置插入元素delete1stItem-void删除第一个元素deleteItemByIndexindex: numbervoid删除指定索引元素deleteItemdata: Tvoid删除指定元素setItemindex: number, data: Tvoid更新指定位置元素clear-void清空全部数据notifyDataReload-void关照数据重载notifyDataAddindex: numbervoid关照数据添加变乱notifyDataChangeindex: numbervoid关照数据变更变乱notifyDataDeleteindex: numbervoid关照数据删除变乱completedata: T[] | undefinedvoid完成加载利用（根据革新状态决定更换或追加数据）作者其他库

• 鸿蒙数据库工具：https://gitee.com/HW-Commons/ZDbUtil
  

接洽我们

接待各人提交issue、PR（可以同一收集标题，方便更多人查阅，会第一时间复兴处理处罚） ，或进群交换(+v: _hhbin)。