Swiper

The <Swiper> component is able to display child components in looping mode.

NOTE

This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

Child Components

This component can contain child components.

NOTE

Built-in components and custom components are allowed, with support for (if/else, ForEach, and LazyForEach) rendering control.

When the <Swiper> component's displayMode attribute is set to SwiperDisplayMode.AutoLinear or its displayCount attribute is set to 'auto', the child component whose visibility attribute is set to None does not take up space in the viewport, but this does not affect the number of navigation dots.

If the child component has the visibility attribute set to None or Hidden, it takes up space in the viewport, but is not displayed.

When the number of child components is less than or equal to the total number of allowed nodes (totalDisplayCount = DisplayCount + prevMargin? (1: 0 ) + nextMargin? (1: 0 )) in the content area, the <Swiper> component uses the non-looping mode for layout. In this case, the child components specified by nextMargin and prevMargin take up space in the viewport, but are not displayed. The specifications of the <Swiper> component are calculated based on the value of totalDisplayCount.

Child components of the <Swiper> component are drawn based on their level if they have the offset attribute set. A child component with a higher level overwrites one with a lower level. For example, if the <Swiper> contains three child components and offset({ x: 100 }) is set for the third child component, the third child component overwrites the first child component during horizontal loop playback. To prevent the first child component from being overwritten, set its zIndex attribute to a value greater than that of the third child component.

APIs

Swiper(controller?: SwiperController)

Parameters

Attributes

In addition to the universal attributes, the following attributes are supported. Menu control is not supported.

SwiperDisplayMode

SwiperController

Controller of the <Swiper> component. You can bind this object to the <Swiper> component and use it to control page switching.

Objects to Import

let controller: SwiperController = new SwiperController()

showNext

showNext(): void

Turns to the next page. Page turning occurs with the animation, whose duration is specified by duration.

showPrevious

showPrevious(): void

Turns to the previous page. Page turning occurs with the animation, whose duration is specified by duration.

finishAnimation

finishAnimation(callback?: () => void): void

Stops an animation.

Parameters

Indicator¹⁰⁺

Sets the distance between the navigation point indicator and the <Swiper> component.

DotIndicator¹⁰⁺

Defines the navigation point indicator of the dot style, which inherits attributes and features from Indicator.

NOTE

When pressed, the navigation point indicator is zoomed in by 1.33 times. To account for this, there is a certain distance between the navigation point indicator's visible boundary and its actual boundary in the non-pressed state. The distance increases with the value of itemWidth, itemHeight, selectedItemWidth, and selectedItemHeight.

DigitIndicator¹⁰⁺

Defines the navigation point indicator of the digit style, which inherits attributes and features from Indicator.

ArrowStyle¹⁰⁺

Describes the left and right arrow attributes.

SwiperAutoFill¹⁰⁺

Describes the auto-fill attribute.

Events

In addition to the universal events, the following events are supported.

Example

Example 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)
      .loop(true)
      .duration(1000)
      .itemSpace(0)
      .indicator( // Set the style of the navigation point indicator.
        new DotIndicator()
          .itemWidth(15)
          .itemHeight(15)
          .selectedItemWidth(15)
          .selectedItemHeight(15)
          .color(Color.Gray)
          .selectedColor(Color.Blue))
      .displayArrow({ // Set the arrow style of the navigation point indicator.
        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 })
  }
}

Example 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.digit() // Set the navigation point indicator of the digit style.
        .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 })
  }
}