How to create an onboard screen?

#harmonyos #onboardscreen #pangesture #arkui

Read the original article：How to create an onboard screen?

Context

The onboard screen can be used to introduce the app or a functionality to first-time users.

Description

User wants to create an onboard screen using the Swiper component. The swiper should be controllable with the crown. The user wants to close the app with the swipe left action on the first page.

Solution

To create an onboard screen, you can use the Swiper.

Step 1: Create a local storage variable to store the onboard status. Modify EntryAbility.ets

onWindowStageCreate(windowStage: window.WindowStage): void {
  // Main window is created, set main page for this ability
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (err) => {
    if (err.code) {
      hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
      return;
    }
    hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');

    // Add this line
    PersistentStorage.persistProp('onboard', false)
  });
}

Step 2: Use the Swiper and create the onboard screen. Create Onboard.ets

import { common } from '@kit.AbilityKit'

@Component
export default struct Onboard {
  @State swiperIndex: number = 0
  total: number = 0
  sc: SwiperController = new SwiperController()

  build() {
    Column() {
      Swiper(this.sc) {
        Column() {
          Text('Page 1')
        }.padding({ left: '10%', right: '10%' })

        Column() {
          Text('Page 2')
        }.padding({ left: '10%', right: '10%' })

        Column() {
          Text('Page 3')
        }.padding({ left: '10%', right: '10%' })

        Column() {
          Text('Page 4')
        }.padding({ left: '10%', right: '10%' })
      }
      .loop(false)
      .effectMode(EdgeEffect.None)
      .defaultFocus(true)
      .onDigitalCrown((event) => {
        if (event.action === CrownAction.BEGIN) {
          this.total = event.degree
        } else {
          this.total += event.degree
        }

        if (this.total > 50) {
          this.sc.showPrevious()
          this.total = 0
        } else if (this.total < -50) {
          this.sc.showNext()
          this.total = 0
        }
      })
      .onChange((index: number) => {
        this.swiperIndex = index
      })
      .size({ width: '100%', height: '60%' })
      .margin({ top: '20%' })

      if (this.swiperIndex !== 0) {
        Button('Finish')
          .fontColor(Color.Blue)
          .backgroundColor(Color.Transparent)
          .onClick(() => {
            AppStorage.set('onboard', true)
          })
      }
    }
    .size({ width: '100%', height: '100%' })
    .parallelGesture(
      PanGesture({ direction: PanDirection.Right })
        .onActionUpdate((event) => {
          const horizontalDistance = event.offsetX;

          if (this.swiperIndex === 0 && horizontalDistance > 50) {
            (this.getUIContext().getHostContext() as common.UIAbilityContext).moveAbilityToBackground()
          }
        })
    )
  }
}

Swipe to close

.parallelGesture(
  PanGesture({ direction: PanDirection.Right })
    .onActionUpdate((event) => {
      const horizontalDistance = event.offsetX;

      if (this.swiperIndex === 0 && horizontalDistance > 50) {
        (this.getUIContext().getHostContext() as common.UIAbilityContext).moveAbilityToBackground()
      }
    })
)

Use crown to change

.defaultFocus(true)
.onDigitalCrown((event) => {
  if (event.action === CrownAction.BEGIN) {
    this.total = event.degree
  } else {
    this.total += event.degree
  }

  if (this.total > 50) {
    this.sc.showPrevious()
    this.total = 0
  } else if (this.total < -50) {
    this.sc.showNext()
    this.total = 0
  }
}

Step 3: Finally, modify the Index.ets to use the Onboard Page.

import Onboard from '../components/Onboard';

@Entry
@Component
struct Index {
  @StorageProp('onboard') onboard: boolean = false;

  build() {
    Stack() {
      if (!this.onboard) {
        Onboard()
      } else {
        Text('Main App')
      }
    }
    .height('100%')
    .width('100%')
  }
}