#我的鸿蒙开发手记#Stepper 组件自学指南原创

森淼笑笑

发布于 2025-5-15 12:26

浏览

0收藏

如果你正在开发需要引导用户分步操作的页面，比如注册流程、配置向导、问卷分步填写等，Stepper 组件绝对能帮上大忙。本文从“为什么用Step导航器”说起，一步步带你入门，最后还能玩点“进阶玩法”。

1. Stepper 能干啥？什么时候用？

Stepper（步骤导航器）主要用来把一个大流程拆成若干步骤，每一步都可独立显示和操作。比如常见的“下一步/上一步/跳过”，或者流程里有些步骤是可选跳过、或禁用状态。

你能用 Stepper 搭出注册向导、在线表单、安装引导页等，结构更清晰，用户体验直线上升。

2. Stepper 基础结构讲明白

Stepper 只能装 StepperItem
首先要知道，Stepper 组件只能包含 StepperItem 子组件，每个 StepperItem 就是一个“步骤页面”。
你可以把 Stepper 理解成一个“包裹多个步骤的容器”。

@Entry
@Component
struct SimpleStepperExample {
  @State stepIndex: number = 0

  build() {
    Stepper({ index: this.stepIndex }) {
      StepperItem() {
        Text('欢迎页')
          .fontSize(22).fontColor('#333').margin(20)
      }.nextLabel('下一步')

      StepperItem() {
        Text('第二步内容')
          .fontSize(22).fontColor('#333').margin(20)
      }.nextLabel('下一步').prevLabel('上一步')

      StepperItem() {
        Text('结束啦')
          .fontSize(22).fontColor('#007dFF').margin(20)
      }.prevLabel('上一步')
    }
    .onFinish(() => {
      // 这里可以写跳转页面或者弹窗等逻辑
      console.info('流程完成')
    })
    .onChange((prev, curr) => {
      this.stepIndex = curr
    })
    .backgroundColor('#FAFAFA')
  }
}

#我的鸿蒙开发手记#Stepper 组件自学指南-鸿蒙开发者社区
这样就是最基础的多步引导！
你可以点“下一步”“上一步”，会自动切换页面。点击最后一步的“下一步”会触发 onFinish。

3. Stepper 实用进阶：状态和事件

步骤页状态怎么用？
每个 StepperItem 都可以设置状态，比如正常（Normal）、跳过（Skip）、禁用（Disabled）、等待（Waiting）。实际开发常用于流程灵活控制，比如根据表单校验结果，动态禁用某步，或者允许用户跳过。

StepperItem()
  .status(ItemState.Disabled)   // 这一页变灰不能操作

支持动态切换状态，比如：

Button('禁用/恢复')
  .onClick(() => {
    this.secondState = this.secondState === ItemState.Disabled ? ItemState.Normal : ItemState.Disabled
  })

事件用法——让流程更灵活

Stepper 提供了很多事件让你和业务逻辑更好结合：
onFinish：点击最后一步的下一步时触发
onSkip：当前步骤设置为Skip时，点击“跳过”会触发
onChange：每次步骤变化都会触发（无论前进后退）
onNext/onPrevious：下一步/上一步单独的钩子

举例说明：

Stepper()
  .onFinish(() => { showDialog('流程结束，去首页吧！') })
  .onSkip(() => { showToast('你跳过了一步') })
  .onChange((prev, next) => { this.currentIndex = next })

4. 组件样式定制：让页面更有个性

你可以用 .backgroundColor()、.borderRadius()、.margin() 等API自定义Stepper和Step内容风格。比如下面这个风格比官方示例更温和：

@Styles function stepItemStyle() {
  .width('90%')
  .margin({ top: 36, left: 20, right: 20 })
  .borderRadius(18)
  .backgroundColor('#FFFFFF')
  .shadow({ radius: 8, color: '#D0D0D0', offsetX: 0, offsetY: 3 })
}

@Extend(Text) function stepTextStyle() {
  .fontColor('#1a1a1a').fontSize(30).fontWeight(600).opacity(0.95)
}

StepperItem() {
  Column() {
    Text('自定义样式步骤')
      .stepTextStyle()
    // 你自己的控件和内容
  }.stepItemStyle()
}

5. 实战进阶：状态切换 + 流程事件

完整例子如下，能动态改变步骤状态、监听流程事件，还能自定义每一步的内容和按钮：

// 导入系统模块
import promptAction from '@ohos.promptAction';

// 定义文本样式接口（解决类型报错）
interface TextStyle {
  fontSize: string;
  fontWeight: number;
  fontColor: string;
}

@Entry
@Component
struct StepperAdvancedDemo {
  @State index: number = 0
  @State states: ItemState[] = [ItemState.Normal, ItemState.Normal, ItemState.Normal]

  // 显式声明返回类型为 TextStyle 接口
  stepTextStyle(): TextStyle {
    return {
      fontSize: '18fp',
      fontWeight: 600,
      fontColor: '#333'
    }
  }

  build() {
    Stepper({ index: this.index }) {
      // 步骤一
      StepperItem() {
        Column({ space: 10 }) {
          Text('填写基本信息')
            .fontSize(this.stepTextStyle().fontSize)
            .fontWeight(this.stepTextStyle().fontWeight)
            .fontColor(this.stepTextStyle().fontColor)
          Button(this.states[0] === ItemState.Skip ? '恢复' : '设为跳过')
            .width('50%')
            .backgroundColor('#47B881')
            .fontColor('#fff')
            .onClick(() => {
              this.states[0] = this.states[0] === ItemState.Skip
                ? ItemState.Normal
                : ItemState.Skip
            })
        }
        .padding(20)
        .width('100%')
      }
      .status(this.states[0])
      .nextLabel('下一步')

      // 步骤二
      StepperItem() {
        Column({ space: 10 }) {
          Text('完善资料')
            .fontSize(this.stepTextStyle().fontSize)
            .fontWeight(this.stepTextStyle().fontWeight)
            .fontColor(this.stepTextStyle().fontColor)
          Button(this.states[1] === ItemState.Disabled ? '恢复' : '禁用')
            .width('50%')
            .backgroundColor('#F7B500')
            .fontColor('#fff')
            .onClick(() => {
              this.states[1] = this.states[1] === ItemState.Disabled
                ? ItemState.Normal
                : ItemState.Disabled
            })
        }
        .padding(20)
        .width('100%')
      }
      .status(this.states[1])
      .nextLabel('下一步')
      .prevLabel('上一步')

      // 步骤三
      StepperItem() {
        Column({ space: 10 }) {
          Text('完成设置')
            .fontSize(this.stepTextStyle().fontSize)
            .fontWeight(this.stepTextStyle().fontWeight)
            .fontColor(this.stepTextStyle().fontColor)
        }
        .padding(20)
        .width('100%')
      }
      .status(this.states[2])
      .prevLabel('上一步')
    }
    .backgroundColor('#F5F7FB')
    .onFinish(() => {
      this.showDialog('流程完成啦！')
    })
    .onSkip(() => {
      this.showToast('你跳过了某个步骤')
    })
    .onChange((prev: number, curr: number) => {
      this.index = curr
    })
  }

  // 弹窗提示方法
  showDialog(message: string) {
    promptAction.showDialog({
      title: '提示',
      message: message,
      buttons: [
        {
          text: '确定',
          color: '#007AFF'
        }
      ]
    })
  }

  // 轻量提示方法
  showToast(message: string) {
    promptAction.showToast({
      message: message,
      duration: 2000
    })
  }
}