目录

ArcSwiper

The ArcSwiper component is designed for circular screens to display child components in a carousel-like manner.

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

Modules to Import

  • ArcSwiperAttribute is essential for configuring the ArcSwiper component. In API version 21 and earlier, you must manually import ArcSwiperAttribute after importing the ArcSwiper component. Otherwise, a compilation error is reported. However, starting from API version 22, the compilation toolchain automatically imports ArcSwiperAttribute when it detects the ArcSwiper component, so manual import is no longer necessary.
  • If you manually import ArcSwiperAttribute, DevEco Studio shows it as disabled (grayed out). In API version 21 and earlier, removing this import causes a compilation error. But from API version 22 onward, removing it does not affect the functionality.
  • This component can be used on phones, PCs, 2-in-1 devices, tablets, TVs, and wearables. In API version 22 and earlier versions, a compilation warning will be reported when this component is used on phones, PCs, 2-in-1 devices, tablets, and TVs, but the component can still run properly.

API version 21 and earlier:

import {
  ArcSwiper,
  ArcSwiperAttribute,
  ArcDotIndicator,
  ArcDirection,
  ArcSwiperController
} from '@kit.ArkUI';

API version 22 and later:

import {
  ArcSwiper,
  ArcDotIndicator,
  ArcDirection,
  ArcSwiperController
} from '@kit.ArkUI';

Child Components

This component can contain child components.

  • Allowed child component types: built-in and custom components, including rendering control types (if/else, ForEach, and LazyForEach).
  • Do not add or delete child components during a page turning animation. Doing so may result in child components not yet animated entering the viewport in advance and causing display exceptions.

APIs

ArcSwiper(controller?: ArcSwiperController)

Creates an ArcSwiper component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
controller ArcSwiperController No Controller bound to the component to control the page turning.

Attributes

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

[h2]index

index(index: Optional<number>)

Sets the index of the child component currently displayed in the container. If the value is less than 0 or greater than or equal to the number of child components, the default value 0 is used.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
index Optional<number> Yes

Index of the child component currently displayed in the container.

If index is set to undefined, the value 0 is used.

[h2]indicator

indicator(style: Optional<ArcDotIndicator | boolean>)

Sets the style of the arc dot navigation indicator.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
style Optional<ArcDotIndicator | boolean> Yes

Style of the arc dot navigation indicator.

- ArcDotIndicator: properties and behavior of the arc dot navigation indicator.

- boolean: whether to enable the arc dot navigation indicator. true to enable, false otherwise.

Default value: true

Default type: ArcDotIndicator

[h2]duration

duration(duration: Optional<number>)

Sets the duration of the animation for child component switching.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
duration Optional<number> Yes

Duration of the autoplay for child component switching.

Default value: 400

Unit: ms

[h2]vertical

vertical(isVertical: Optional<boolean>)

Sets whether vertical swiping is used.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
isVertical Optional<boolean> Yes

Whether vertical swiping is used.

The value true means vertical swiping, and false means horizontal swiping.

Default value: false

[h2]disableSwipe

disableSwipe(disabled: Optional<boolean>)

Sets whether to disable the swipe-to-switch feature of the component.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
disabled Optional<boolean> Yes

Whether to disable the swipe-to-switch feature of the component. The value true means to disable the feature, and false means the opposite.

Default value: false

[h2]digitalCrownSensitivity

digitalCrownSensitivity(sensitivity: Optional<CrownSensitivity>)

Sets the sensitivity to the digital crown rotation.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
sensitivity Optional<CrownSensitivity> Yes

Sensitivity to the digital crown rotation.

Default value: CrownSensitivity.MEDIUM.

[h2]effectMode

effectMode(edgeEffect: Optional<EdgeEffect>)

Sets the effect used when the scroll boundary is reached. For details about the supported effects, see EdgeEffect. The setting does not take effect when configured using the controller API.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
edgeEffect Optional<EdgeEffect> Yes

Effect used when the component is at one of the edges.

Default value: EdgeEffect.Spring

[h2]disableTransitionAnimation

disableTransitionAnimation(disabled: Optional<boolean>)

Sets whether to disable the transition animation.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
disabled Optional<boolean> Yes

Whether to disable the transition animation.

true: Disable the animation effect. false: Do not disable the animation effect.

If the input parameter is invalid, the value false is used.

ArcSwiperController

Implements the controller of the ArcSwiper component. You can bind this object to the ArcSwiper component and use it to control page switching.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

[h2]constructor

constructor()

A constructor used to create an ArcSwiperController instance.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

[h2]showNext

showNext()

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

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

[h2]showPrevious

showPrevious()

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

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

[h2]finishAnimation

finishAnimation(handler?: FinishAnimationHandler)

Stops an animation.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
handler FinishAnimationHandler No

Callback invoked when the animation stops.

If no value is provided, no callback is performed.

ArcDotIndicator

Describes the properties and behavior of the arc dot navigation indicator.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

[h2]constructor

constructor()

A constructor used to create an ArcDotIndicator instance.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

[h2]arcDirection

arcDirection(direction: Optional<ArcDirection>): ArcDotIndicator

Sets the direction of the arc navigation indicator.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
direction Optional<ArcDirection> Yes

Direction of the arc navigation indicator.

Default value: ArcDirection.SIX_CLOCK_DIRECTION (6 o'clock direction)

Return value

Type Description
ArcDotIndicator Properties and functionality of the arc navigation indicator.

[h2]itemColor

itemColor(color: Optional<ResourceColor>): ArcDotIndicator

Sets the color of the unselected navigation points in the arc navigation indicator.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
color Optional<ResourceColor> Yes

Color of the unselected navigation points in the arc navigation indicator.

Default value: '#A9FFFFFF'

Return value

Type Description
ArcDotIndicator Properties and functionality of the arc navigation indicator.

[h2]selectedItemColor

selectedItemColor(color: Optional<ResourceColor>): ArcDotIndicator

Sets the color of the selected navigation point in the arc navigation indicator.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
color Optional<ResourceColor> Yes

Color of the selected navigation point in the arc navigation indicator.

Default value: #FF5EA1FF

Return value

Type Description
ArcDotIndicator Properties and functionality of the arc navigation indicator.

[h2]backgroundColor

backgroundColor(color: Optional<ResourceColor>): ArcDotIndicator

Sets the color of the arc navigation indicator when it is long-pressed.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
color Optional<ResourceColor> Yes

Color of the arc navigation indicator when it is long-pressed.

Default value: '#FF404040'

Return value

Type Description
ArcDotIndicator Properties and functionality of the arc navigation indicator.

[h2]maskColor

maskColor(color: Optional<LinearGradient>): ArcDotIndicator

Sets the mask gradient color of the arc navigation indicator.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
color Optional<LinearGradient> Yes

Mask gradient color of the arc navigation indicator.

Default start color: '#00000000'

Default end color: '#FF000000'

Return value

Type Description
ArcDotIndicator Properties and functionality of the arc navigation indicator.

[h2]ArcDirection

Enumerates the directions of the arc navigation indicator.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Name Value Description
THREE_CLOCK_DIRECTION 0 3 o'clock direction.
SIX_CLOCK_DIRECTION 1 6 o'clock direction.
NINE_CLOCK_DIRECTION 2 9 o'clock direction.

FinishAnimationHandler

type FinishAnimationHandler = () => void

Defines the callback to notify the application when the animation stops playing.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

IndexChangedHandler

type IndexChangedHandler = (index: number) => void

Defines the callback to notify the application when the index of the currently displayed element changes.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
index number Yes Index of the currently displayed element. The index is zero-based.

AnimationStartHandler

type AnimationStartHandler = (index: number, targetIndex: number, event: SwiperAnimationEvent) => void

Defines the callback triggered when the page transition animation starts.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
index number Yes Index of the currently displayed element before the animation starts (not the final index after the animation ends).
targetIndex number Yes Index of the target element to switch to.
event SwiperAnimationEvent Yes Extra information of the animation, including the offset of the currently displayed element and target element relative to the start position of the ArcSwiper along the main axis, and the hands-off velocity.

AnimationEndHandler

type AnimationEndHandler = (index: number, event: SwiperAnimationEvent) => void

Defines the callback triggered when the page transition animation ends.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
index number Yes Index of the currently displayed element.
event SwiperAnimationEvent Yes Extra information of the animation, which is the offset of the currently displayed element relative to the start position of the ArcSwiper along the main axis.

GestureSwipeHandler

type GestureSwipeHandler = (index: number, event: SwiperAnimationEvent) => void

Defines the callback triggered on a frame-by-frame basis during a swipe-based page turn.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
index number Yes Index of the currently displayed element.
event SwiperAnimationEvent Yes Extra information of the animation, which is the offset of the currently displayed element relative to the start position of the ArcSwiper along the main axis.

Events

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

[h2]onChange

onChange(handler: Optional<IndexChangedHandler>)

Triggered when the index of the currently displayed child component changes. The return value is the index of the currently displayed child component.

When the ArcSwiper component is used together with LazyForEach, the subpage UI update cannot be triggered in the onChange event.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
handler Optional<IndexChangedHandler> Yes Callback for the index of the currently displayed element.

[h2]onAnimationStart

onAnimationStart(handler: Optional<AnimationStartHandler>)

Triggered when the page transition animation starts.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
handler Optional<AnimationStartHandler> Yes Triggered when the page transition animation starts.

[h2]onAnimationEnd

onAnimationEnd(handler: Optional<AnimationEndHandler>)

Triggered when the page transition animation ends.

This event is triggered when the page transition animation of the ArcSwiper component ends, whether it is caused by gesture interruption or by calling finishAnimation through SwiperController. The index parameter indicates the index after the animation ends. When the ArcSwiper component contains multiple columns, the index is of the leftmost element.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
handler Optional<AnimationEndHandler> Yes Triggered when the page transition animation ends.

[h2]onGestureSwipe

onGestureSwipe(handler: Optional<GestureSwipeHandler>)

Triggered on a frame-by-frame basis when the page is turned by a swipe.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
handler Optional<GestureSwipeHandler> Yes Triggered on a frame-by-frame basis when the page is turned by a swipe.

[h2]customContentTransition

customContentTransition(transition: Optional<SwiperContentAnimatedTransition>)

Defines a custom page transition animation. During finger-following swipes and post-release transition animations, this triggers a frame-by-frame callback for all pages in the viewport, allowing you to customize animations by modifying properties like opacity, scale, and translation.

During finger-following swipes and post-release transition animations, the SwiperContentTransitionProxy callback is invoked for all pages in the viewport on a frame-by-frame basis. For example, when there are two pages whose subscripts are 0 and 1 in the viewport, two callbacks whose indexes are 0 and 1 are invoked in each frame.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Parameters

Name Type Mandatory Description
transition Optional<SwiperContentAnimatedTransition> Yes Information about the custom page transition animation.

SwiperContentAnimatedTransition

Provides the information about the custom page transition animation.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Name Type Read-Only Optional Description
timeout number No Yes Timeout for the custom page transition animation. The timeout timer starts when the default animation (page scrolling) reaches the point where the first frame is moved out of the viewport. If you do not call the finishTransition API of SwiperContentTransitionProxy before the timer expires, the component considers that the custom animation of the page ends and immediately removes the page node from the render tree. The unit is ms. The default value is 0.
transition Callback<SwiperContentTransitionProxy> No No Content of the custom page transition animation.

SwiperContentTransitionProxy

Implements the proxy object returned during the execution of the custom page transition animation of the ArcSwiper component. You can use this object to obtain the page information in the custom animation viewport. You can also call the finishTransition API of this object to notify the ArcSwiper component that the custom animation has finished playing.

  • For example, when the index of the currently selected child component is 0, during a transition animation from page 0 to page 1, the callback is triggered for all pages within the viewport on every frame. When pages 0 and 1 are both in the viewport, the callback is triggered twice per frame. The first callback has selectedIndex as 0, index as 0, position as the ratio of how much page 0 has moved relative to its position before the animation started on the current frame, and mainAxisLength as the length of page 0 on the main axis. The second callback has selectedIndex as 0, index as 1, position as the ratio of how much page 1 has moved relative to page 0 before the animation started on the current frame, and mainAxisLength as the length of page 1 on the main axis.

  • If the animation curve is a spring interpolation curve, during the transition animation from page 0 to page 1, due to the position and velocity when the user lifts their finger off the screen, animation may overshoot and slide past to page 2, then bounce back to page 1. Throughout this process, a callback is triggered for pages 1 and 2 within the viewport on every frame.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

[h2]Properties

Name Type Read-Only Optional Description
selectedIndex number No No Index of the currently selected page.
index number No No Index of a page in the viewport.
position number No No Position of the page specified by index relative to the start position of the ArcSwiper main axis (start position of the page corresponding to selectedIndex).
mainAxisLength number No No Length of the page specified by index along the main axis.

[h2]finishTransition

finishTransition(): void

Notifies the ArcSwiper component that the custom animation has finished playing.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Circle

Example

[h2]Example 1: Configuring the Basic Attributes of arcSwiper

This example demonstrates the basic functionality of the ArcSwiper component.

// xxx.ets
import {
  CircleShape,
  ArcSwiper,
  ArcSwiperAttribute,
  ArcDotIndicator,
  ArcDirection,
  ArcSwiperController
} from '@kit.ArkUI';
// Starting from API version 22, you do not need to manually import ArcSwiperAttribute. For details, refer to the Modules to Import section of the ArcSwiper reference document.

class MyDataSource implements IDataSource {
  private list: Color[] = [];

  constructor(list: Color[]) {
    this.list = list;
  }

  totalCount(): number {
    return this.list.length;
  }

  getData(index: number): Color {
    return this.list[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {
  }

  unregisterDataChangeListener() {
  }
}

@Entry
@Component
struct TestNewInterface {
  @State itemSimpleColor: Color | number | string = '';
  @State selectedItemSimpleColor: Color | number | string = '';
  private wearableSwiperController: ArcSwiperController = new ArcSwiperController();
  private arcDotIndicator: ArcDotIndicator = new ArcDotIndicator();
  private data: MyDataSource = new MyDataSource([]);
  @State backgroundColors: Color[] =
    [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.White, Color.Gray, Color.Orange, Color.Transparent];
  innerSelectedIndex: number = 0;

  aboutToAppear(): void {
    let list: Color[] = [];
    for (let i = 1; i <= 6; i++) {
      list.push(i);
    }
    this.data = new MyDataSource(this.backgroundColors);
  }

  build() {
    Column() {
      Row() {
        ArcSwiper(this.wearableSwiperController) {
          LazyForEach(this.data, (backgroundColor: Color, index: number) => {
            Text(index.toString())
              .width(233)
              .height(233)
              .backgroundColor(backgroundColor)
              .textAlign(TextAlign.Center)
              .fontSize(30)
          })
        }
        .clipShape(new CircleShape({ width: 233, height: 233 }))
        .effectMode(EdgeEffect.None)
        .backgroundColor(Color.Transparent)
        .index(0)
        .duration(400)
        .vertical(false)
        .indicator(this.arcDotIndicator
          .arcDirection(ArcDirection.SIX_CLOCK_DIRECTION)
          .itemColor(this.itemSimpleColor)
          .selectedItemColor(this.selectedItemSimpleColor)
        )
        .disableSwipe(false)
        .digitalCrownSensitivity(CrownSensitivity.MEDIUM)
        .onChange((index: number) => {
          console.info("onChange:" + index.toString());
        })
        .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => {
          this.innerSelectedIndex = targetIndex;
          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);
        })
        .onGestureRecognizerJudgeBegin((event: BaseGestureEvent, current: GestureRecognizer,
          others: Array<GestureRecognizer>): GestureJudgeResult => { // When the implementation is about to succeed, set the recognizer enabling state based on the current component state.
          if (current) {
            let target = current.getEventTargetInfo();
            if (target && current.isBuiltIn() && current.getType() == GestureControl.GestureType.PAN_GESTURE) {
              // Check whether the ArcSwiper has scrolled to the beginning: swiperTarget.isBegin() or innerSelectedIndex === 0.
              let swiperTarget = target as ScrollableTargetInfo
              if (swiperTarget instanceof ScrollableTargetInfo &&
                (swiperTarget.isBegin() || this.innerSelectedIndex === 0)) {
                let panEvent = event as PanGestureEvent;
                if (panEvent && panEvent.offsetX > 0 && (swiperTarget.isBegin() || this.innerSelectedIndex === 0)) {
                  return GestureJudgeResult.REJECT;
                }
              }
            }
          }
          return GestureJudgeResult.CONTINUE;
        })
        .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => {
          console.info("index: " + index);
          console.info("current offset: " + extraInfo.currentOffset);
        })
        .disableTransitionAnimation(false)
      }.height('100%')
    }.width('100%')
  }
}

[h2]Example 2: Customizing a Page Transition Animation for ArcSwiper

In this example, the customContentTransition API is used to define a custom switching animation for the ArcSwiper component.

import { Decimal } from '@kit.ArkTS';
import { CircleShape, ArcSwiper, ArcSwiperAttribute } from '@kit.ArkUI';

// Starting from API version 22, you do not need to manually import ArcSwiperAttribute. For details, refer to the Modules to Import section of the ArcSwiper reference document.
@Entry
@Component
struct TestNewInterface {
  private backgroundColors: Color[] =
    [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.White, Color.Gray, Color.Orange];
  @State scaleList: number[] = [];

  aboutToAppear(): void {
    for (let i = 0; i < this.backgroundColors.length; i++) {
      this.scaleList.push(1.0);
    }
  }

  build() {
    Column() {
      Row() {
        ArcSwiper() {
          ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => {
            Text(index.toString())
              .width(233)
              .height(233)
              .backgroundColor(backgroundColor)
              .textAlign(TextAlign.Center)
              .fontSize(30)
              .scale({ x: this.scaleList[index], y: this.scaleList[index] })
          })
        }
        .clipShape(new CircleShape({ width: 233, height: 233 }))
        .effectMode(EdgeEffect.None)
        .onChange((index: number) => {
          console.info('onChange:' + index.toString());
        })
        .customContentTransition({
          // The page is removed from the render tree when 1000 ms (timeout time) has elapsed.
          timeout: 1000,
          // Called on a frame-by-frame basis for all pages in the viewport. You can change the values of attributes such as opacity in the callback to implement a custom animation.
          transition: (proxy: SwiperContentTransitionProxy) => {
            if (proxy.position <= -1 || proxy.position >= 1) {
              // When a group of pages is completely scrolled out of the viewport, reset the attribute values.
              this.scaleList[proxy.index] = 1.0;
            } else {
              let position: number = Decimal.abs(proxy.position).toNumber();
              this.scaleList[proxy.index] = 1 - position;
            }
          }
        })
        .disableTransitionAnimation(false)
      }.height('100%')
    }.width('100%')
  }
}