Swiper
滑塊視圖容器,提供子組件滑動輪播顯示的能力。
說明:
該組件從API Version 7開始支持。后續版本如有新增內容,則采用上角標單獨標記該內容的起始版本。
子組件
可以包含子組件。
說明:
開發前請熟悉鴻蒙開發指導文檔 :[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md
]
子組件類型:系統組件和自定義組件,支持渲染控制類型([if/else]、[ForEach]和[LazyForEach])。Swiper子組件的visibility屬性設置為None,Swiper的displayMode屬性設置為SwiperDisplayMode.AutoLinear或displayCount屬性設置為'auto'時,對應子組件在視窗內不占位,但不影響導航點個數。
Swiper子組件的visibility屬性設置為None,或者visibility屬性設置為Hidden時,對應子組件不顯示,但依然會在視窗內占位。
當Swiper子組件個數小于等于Swiper組件內容區內顯示的節點總個數(totalDisplayCount = DisplayCount + prevMargin? (1 : 0 ) + nextMargin? (1 : 0 ))時,按照非循環模式布局處理,此時,前后邊距對應子組件不顯示,但依然會在視窗內占位。Swiper組件按照totalDisplayCount個數判斷測算規格。
接口
Swiper(controller?: SwiperController)
參數:
參數名 | 參數類型 | 必填 | 參數描述 |
---|---|---|---|
controller | [SwiperController] | 否 | 給組件綁定一個控制器,用來控制組件翻頁。 |
屬性
除支持[通用屬性]外,還支持以下屬性,不支持[Menu控制]。
名稱 | 參數類型 | 描述 |
---|---|---|
index | number | 設置當前在容器中顯示的子組件的索引值。 默認值:0**說明:**設置小于0或大于等于子組件數量時,按照默認值0處理。 從API version 10開始,該屬性支持[$$]雙向綁定變量。 |
autoPlay | boolean | 子組件是否自動播放。 默認值:false**說明:**loop為false時,自動輪播到最后一頁時停止輪播。手勢切換后不是最后一頁時繼續播放。 |
interval | number | 使用自動播放時播放的時間間隔,單位為毫秒。 默認值:3000 |
indicator10+ | [DotIndicator] | [DigitIndicator] |
loop | boolean | 是否開啟循環。 設置為true時表示開啟循環,在LazyForEach懶循環加載模式下,加載的組件數量建議大于5個。 默認值:true |
duration | number | 子組件切換的動畫時長,單位為毫秒。 默認值:400 |
vertical | boolean | 是否為縱向滑動。 默認值:false |
itemSpace | number | string |
displayMode | SwiperDisplayMode | 主軸方向上元素排列的模式,優先以displayCount設置的個數顯示,displayCount未設置時本屬性生效。 默認值:SwiperDisplayMode.STRETCH |
cachedCount8+ | number | 設置預加載子組件個數。 默認值:1 |
disableSwipe8+ | boolean | 禁用組件滑動切換功能。 默認值:false |
curve8+ | [Curve] | string |
displayCount8+ | number | string |
effectMode8+ | [EdgeEffect] | 邊緣滑動效果,loop = false時生效。 目前支持的滑動效果參見EdgeEffect的枚舉說明。 默認值:EdgeEffect.Spring**說明:**控制器接口調用時不生效回彈。 |
displayArrow10+ | value:[ArrowStyle] | boolean, isHoverShow?: boolean |
nextMargin10+ | [Length] | 后邊距,用于露出后一項的一小部分。 默認值:0**說明:**僅當SwiperDisplayMode為STRETCH模式時生效。 當主軸方向為橫向布局時,nextmargin/prevmargin中任意一個大于子組件測算的寬度,nextmargin和prevmargin均不顯示。 當主軸方向為縱向布局時,nextmargin/prevmargin中任意一個大于子組件測算的高度,nextmargin和prevmargin均不顯示。 |
prevMargin10+ | [Length] | 前邊距,用于露出前一項的一小部分。 默認值:0**說明:**僅當SwiperDisplayMode為STRETCH模式時生效。 當主軸方向為橫向布局時,nextmargin/prevmargin中任意一個大于子組件測算的寬度,prevmargin和nextmargin均不顯示。 當主軸方向為縱向布局時,nextmargin/prevmargin中任意一個大于子組件測算的高度,nextmargin和prevmargin均不顯示。 |
SwiperDisplayMode枚舉說明
名稱 | 描述 |
---|---|
STRETCH10+ | Swiper滑動一頁的寬度為Swiper組件自身的寬度。 |
AUTO_LINEAR10+ | Swiper滑動一頁的寬度為視窗內最左側子組件的寬度。 |
SwiperController
Swiper容器組件的控制器,可以將此對象綁定至Swiper組件,然后通過它控制翻頁。
showNext
showNext(): void
翻至下一頁。翻頁帶動效切換過程,時長通過duration指定。
showPrevious
showPrevious(): void
翻至上一頁。翻頁帶動效切換過程,時長通過duration指定。
finishAnimation
finishAnimation(callback?: () => void): void
停止播放動畫。
參數:
參數名 | 參數類型 | 必填項 | 參數描述 |
---|---|---|---|
callback | () => void | 否 | 動畫結束的回調。 |
Indicator10+
設置導航點距離Swiper組件距離。
參數名 | 參數類型 | 必填項 | 參數描述 |
---|---|---|---|
left | [Length] | 否 | 設置導航點距離Swiper組件左邊的距離。 默認值:0 單位:vp |
top | [Length] | 否 | 設置導航點距離Swiper組件頂部的距離。 默認值:0 單位:vp |
right | [Length] | 否 | 設置導航點距離Swiper組件右邊的距離。 默認值:0 單位:vp |
bottom | [Length] | 否 | 設置導航點距離Swiper組件底部的距離。 默認值:0 單位:vp |
DotIndicator10+
圓點指示器屬性及功能繼承自Indicator。
參數名 | 參數類型 | 必填項 | 參數描述 |
---|---|---|---|
itemWidth | [Length] | 否 | 設置Swiper組件圓點導航指示器的寬,不支持設置百分比。 默認值:6 單位:vp |
itemHeight | [Length] | 否 | 設置Swiper組件圓點導航指示器的高,不支持設置百分比。 默認值:6 單位:vp |
selectedItemWidth | [Length] | 否 | 設置選中Swiper組件圓點導航指示器的寬,不支持設置百分比。 默認值:12 單位:vp |
selectedItemHeight | [Length] | 否 | 設置選中Swiper組件圓點導航指示器的高,不支持設置百分比。 默認值:6 單位:vp |
mask | boolean | 否 | 設置是否顯示Swiper組件圓點導航指示器的蒙版樣式。 默認值:false |
color | [ResourceColor] | 否 | 設置Swiper組件圓點導航指示器的顏色。 默認值:'#182431'(10%透明度) |
selectedColor | [ResourceColor] | 否 | 設置選中Swiper組件圓點導航指示器的顏色。 默認值:'#007DFF' |
DigitIndicator10+
數字指示器屬性及功能繼承自Indicator。
參數名 | 參數類型 | 必填項 | 參數描述 |
---|---|---|---|
fontColor | [ResourceColor] | 否 | 設置Swiper組件數字導航點的字體顏色。 默認值:'#ff182431' |
selectedFontColor | [ResourceColor] | 否 | 設置選中Swiper組件數字導航點的字體顏色。 默認值:'#ff182431' |
digitFont | { size?:[Length]weight?:number | [FontWeight] | string } |
selectedDigitFont | { size?:[Length] weight?:number | [FontWeight] | string } |
ArrowStyle10+
左右箭頭屬性。
參數名 | 參數類型 | 必填項 | 參數描述 |
---|---|---|---|
showBackground | boolean | 否 | 設置箭頭底板是否顯示。 默認值:false |
isSidebarMiddle | boolean | 否 | 設置箭頭顯示位置。 默認值:false 默認顯示在導航點指示器兩側。 |
backgroundSize | [Length] | 否 | 設置底板大小。 在導航點兩側顯示: 默認值:24vp 在組件兩側顯示: 默認值:32vp 不支持設置百分比。 |
backgroundColor | [ResourceColor] | 否 | 設置底板顏色。 在導航點兩側顯示: 默認值:'#00000000' 在組件兩側顯示: 默認值:'#19182431' |
arrowSize | [Length] | 否 | 設置箭頭大小。 在導航點兩側顯示時: 默認值:18vp 在組件兩側顯示時: 默認值:24vp**說明:**showBackground為true時,arrowSize為backgroundSize的3/4。 不支持設置百分比。 |
arrowColor | [ResourceColor] | 否 | 設置箭頭顏色。 默認值:'#182431' |
SwiperAutoFill10+
自適應屬性。
參數名 | 參數類型 | 必填項 | 參數描述 |
---|---|---|---|
minSize | [VP] | 是 | 設置元素顯示最小寬度。 默認值:0 |
事件
除支持[通用事件]外,還支持以下事件:
名稱 | 功能描述 |
---|---|
onChange(event: (index: number) => void) | 當前顯示的子組件索引變化時觸發該事件,返回值為當前顯示的子組件的索引值。 - index:當前顯示元素的索引。**說明:**Swiper組件結合LazyForEach使用時,不能在onChange事件里觸發子頁面UI的刷新。 |
onAnimationStart9+(event: (index: number, targetIndex10+: number, extraInfo10+: [SwiperAnimationEvent]) => void) | 切換動畫開始時觸發該回調。 - index:當前顯示元素的索引。 - targetIndex:切換動畫目標元素的索引。 - extraInfo:動畫相關信息,包括主軸方向上當前顯示元素和目標元素相對Swiper起始位置的位移,以及離手速度。**說明:**參數為動畫開始前的index值(不是最終結束動畫的index值),多列Swiper時,index為最左側組件的索引。 |
onAnimationEnd9+(event: (index: number, extraInfo: [SwiperAnimationEvent]) => void) | 切換動畫結束時觸發該回調。 - index:當前顯示元素的索引。 - extraInfo:動畫相關信息,只返回主軸方向上當前顯示元素相對于Swiper起始位置的位移。**說明:**當Swiper切換動效結束時觸發,包括動畫過程中手勢中斷,通過SwiperController調用finishAnimation。參數為動畫結束后的index值,多列Swiper時,index為最左側組件的索引。 |
onGestureSwipe10+(event: (index: number, extraInfo: [SwiperAnimationEvent]) => void) | 在頁面跟手滑動過程中,逐幀觸發該回調。 - index:當前顯示元素的索引。 - extraInfo:動畫相關信息,只返回主軸方向上當前顯示元素相對于Swiper起始位置的位移。**說明:**多列Swiper時,index為最左側組件的索引。 |
示例
示例1
// xxx.ets
class MyDataSource implements IDataSource {
private list: number[] = []
constructor(list: number[]) {
this.list = list
}
totalCount(): number {
return this.list.length
}
getData(index: number): number {
return this.list[index]
}
registerDataChangeListener(listener: DataChangeListener): void {
}
unregisterDataChangeListener() {
}
}
@Entry
@Component
struct SwiperExample {
private swiperController: SwiperController = new SwiperController()
private data: MyDataSource = new MyDataSource([])
aboutToAppear(): void {
let list: number[] = []
for (let i = 1; i <= 10; i++) {
list.push(i);
}
this.data = new MyDataSource(list)
}
build() {
Column({ space: 5 }) {
Swiper(this.swiperController) {
LazyForEach(this.data, (item: string) = > {
Text(item.toString())
.width('90%')
.height(160)
.backgroundColor(0xAFEEEE)
.textAlign(TextAlign.Center)
.fontSize(30)
}, (item: string) = > item)
}
.cachedCount(2)
.index(1)
.autoPlay(true)
.interval(4000)
.indicator(true)
.loop(true)
.duration(1000)
.itemSpace(0)
.displayArrow({
showBackground: true,
isSidebarMiddle: true,
backgroundSize: 24,
backgroundColor: Color.White,
arrowSize: 18,
arrowColor: Color.Blue
}, false)
.curve(Curve.Linear)
.onChange((index: number) = > {
console.info(index.toString())
})
.onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) = > {
console.info("index: " + index)
console.info("current offset: " + extraInfo.currentOffset)
})
.onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) = > {
console.info("index: " + index)
console.info("targetIndex: " + targetIndex)
console.info("current offset: " + extraInfo.currentOffset)
console.info("target offset: " + extraInfo.targetOffset)
console.info("velocity: " + extraInfo.velocity)
})
.onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) = > {
console.info("index: " + index)
console.info("current offset: " + extraInfo.currentOffset)
})
Row({ space: 12 }) {
Button('showNext')
.onClick(() = > {
this.swiperController.showNext()
})
Button('showPrevious')
.onClick(() = > {
this.swiperController.showPrevious()
})
}.margin(5)
}.width('100%')
.margin({ top: 5 })
}
}
示例2
// xxx.ets
class MyDataSource implements IDataSource {
private list: number[] = []
constructor(list: number[]) {
this.list = list
}
totalCount(): number {
return this.list.length
}
getData(index: number): number {
return this.list[index]
}
registerDataChangeListener(listener: DataChangeListener): void {
}
unregisterDataChangeListener() {
}
}
@Entry
@Component
struct SwiperExample {
private swiperController: SwiperController = new SwiperController()
private data: MyDataSource = new MyDataSource([])
aboutToAppear(): void {
let list: number[] = []
for (let i = 1; i <= 10; i++) {
list.push(i);
}
this.data = new MyDataSource(list)
}
build() {
Column({ space: 5 }) {
Swiper(this.swiperController) {
LazyForEach(this.data, (item: string) = > {
Text(item.toString())
.width('90%')
.height(160)
.backgroundColor(0xAFEEEE)
.textAlign(TextAlign.Center)
.fontSize(30)
}, (item: string) = > item)
}
.cachedCount(2)
.index(1)
.autoPlay(true)
.interval(4000)
.indicator(Indicator.dot()
.itemWidth(15)
.itemHeight(15)
.selectedItemWidth(15)
.selectedItemHeight(15)
.color(Color.Gray)
.selectedColor(Color.Blue))
.loop(true)
.duration(1000)
.itemSpace(0)
.displayArrow(true, true)
Row({ space: 12 }) {
Button('showNext')
.onClick(() = > {
this.swiperController.showNext()
})
Button('showPrevious')
.onClick(() = > {
this.swiperController.showPrevious()
})
}.margin(5)
}.width('100%')
.margin({ top: 5 })
}
}
示例3
// xxx.ets
class MyDataSource implements IDataSource {
private list: number[] = []
constructor(list: number[]) {
this.list = list
}
totalCount(): number {
return this.list.length
}
getData(index: number): number {
return this.list[index]
}
registerDataChangeListener(listener: DataChangeListener): void {
}
unregisterDataChangeListener() {
}
}
@Entry
@Component
struct SwiperExample {
private swiperController: SwiperController = new SwiperController()
private data: MyDataSource = new MyDataSource([])
aboutToAppear(): void {
let list: number[] = []
for (let i = 1; i <= 10; i++) {
list.push(i);
}
this.data = new MyDataSource(list)
}
build() {
Column({ space: 5 }) {
Swiper(this.swiperController) {
LazyForEach(this.data, (item: string) = > {
Text(item.toString())
.width('90%')
.height(160)
.backgroundColor(0xAFEEEE)
.textAlign(TextAlign.Center)
.fontSize(30)
}, (item: string) = > item)
}
.cachedCount(2)
.index(1)
.autoPlay(true)
.interval(4000)
.indicator(Indicator.digit()
.right("43%")
.top(200)
.fontColor(Color.Gray)
.selectedFontColor(Color.Gray)
.digitFont({ size: 20, weight: FontWeight.Bold })
.selectedDigitFont({ size: 20, weight: FontWeight.Normal }))
.loop(true)
.duration(1000)
.itemSpace(0)
.displayArrow(true, false)
Row({ space: 12 }) {
Button('showNext')
.onClick(() = > {
this.swiperController.showNext()
})
Button('showPrevious')
.onClick(() = > {
this.swiperController.showPrevious()
})
}.margin(5)
}.width('100%')
.margin({ top: 5 })
}
}
審核編輯 黃宇
-
組件
+關注
關注
1文章
513瀏覽量
17854 -
鴻蒙
+關注
關注
57文章
2371瀏覽量
42910
發布評論請先 登錄
相關推薦
評論