• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Stepper
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @mayaolll-->
5<!--Designer: @jiangdayuan-->
6<!--Tester: @lxl007-->
7<!--Adviser: @HelloCrease-->
8
9步骤导航器组件，适用于引导用户按照步骤完成任务的导航场景。
10
11
12>  **说明：**
13>
14> 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
15
16
17## 子组件
18
19仅能包含子组件[StepperItem](ts-basic-components-stepperitem.md)。
20
21
22## 接口
23
24Stepper(value?: { index?: number })
25
26创建步骤导航器组件。
27
28**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
29
30**系统能力：** SystemCapability.ArkUI.ArkUI.Full
31
32**参数：**
33
34| 参数名 | 类型 | 必填  | 说明 |
35| ------| -------- | --------------- | -------- |
36| value | { index?: number }   | 否 | 设置步骤导航器当前显示StepperItem的索引值。<br/>默认值：0<br />从API version 10开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。 |
37
38
39## 属性
40
41无
42
43## 事件
44
45### onFinish
46
47onFinish(callback: () => void)
48
49步骤导航器最后一个StepperItem的nextLabel被点击时，并且ItemState属性为Normal时，触发该回调。
50
51**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
52
53**系统能力：** SystemCapability.ArkUI.ArkUI.Full
54
55**参数：**
56
57| 参数名   | 类型                 | 必填 | 说明                                       |
58| -------- | -------------------  | ---- | ------------------------------------------ |
59| callback   |  &nbsp;()&nbsp;=&gt;&nbsp;void   | 是   | 步骤导航器最后一个StepperItem的nextLabel被点击时，并且ItemState属性为Normal时，触发该回调。|
60
61### onSkip
62
63onSkip(callback:&nbsp;()&nbsp;=&gt;&nbsp;void)
64
65当前显示的StepperItem状态为ItemState.Skip时，nextLabel被点击时触发该回调。
66
67**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
68
69**系统能力：** SystemCapability.ArkUI.ArkUI.Full
70
71**参数：**
72
73| 参数名   | 类型                 | 必填 | 说明                                       |
74| -------- | -------------------  | ---- | ------------------------------------------ |
75| callback   |  &nbsp;()&nbsp;=&gt;&nbsp;void   | 是   | 当前显示的StepperItem状态为ItemState.Skip时，nextLabel被点击时触发该回调。|
76
77### onChange
78
79onChange(callback:&nbsp;(prevIndex:&nbsp;number,&nbsp;index:&nbsp;number)&nbsp;=&gt;&nbsp;void)
80
81点击当前StepperItem的prevLabel进行步骤切换时触发该回调；或点击当前StepperItem的nextLabel，当前页面不为步骤导航器最后一个StepperItem且ItemState属性为Normal时，触发该回调。
82
83**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
84
85**系统能力：** SystemCapability.ArkUI.ArkUI.Full
86
87**参数：**
88
89| 参数名    | 类型   | 必填 | 说明                                       |
90| --------- | ------ | ---- | ------------------------------------------ |
91| prevIndex | number | 是   | 切换前的步骤页索引值。<br/>取值范围：[0, +∞) |
92| index     | number | 是   | 切换后的步骤页（前一页或者下一页）索引值。<br/>取值范围：[0, +∞) |
93
94### onNext
95
96onNext(callback:&nbsp;(index:&nbsp;number,&nbsp;pendingIndex:&nbsp;number)&nbsp;=&gt;&nbsp;void)
97
98点击StepperItem的nextLabel切换下一步骤时，当前页面不为步骤导航器最后一个StepperItem且ItemState属性为Normal时，触发该回调。
99
100**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
101
102**系统能力：** SystemCapability.ArkUI.ArkUI.Full
103
104**参数：**
105
106| 参数名       | 类型   | 必填 | 说明               |
107| ------------ | ------ | ---- | ------------------ |
108| index        | number | 是   | 当前步骤页索引值。 |
109| pendingIndex | number | 是   | 下一步骤页索引值。 |
110
111### onPrevious
112
113onPrevious(callback:&nbsp;(index:&nbsp;number,&nbsp;pendingIndex:&nbsp;number)&nbsp;=&gt;&nbsp;void)
114
115点击StepperItem的prevLabel切换上一步骤时触发该回调。
116
117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
118
119**系统能力：** SystemCapability.ArkUI.ArkUI.Full
120
121**参数：**
122
123| 参数名       | 类型   | 必填 | 说明               |
124| ------------ | ------ | ---- | ------------------ |
125| index        | number | 是   | 当前步骤页索引值。 |
126| pendingIndex | number | 是   | 上一步骤页索引值。 |
127
128
129## 示例
130
131该示例主要演示如何使用步骤导航器组件。
132
133```ts
134// xxx.ets
135@Styles function itemStyle () {
136  .width(336)
137  .height(621)
138  .margin({ top: 48, left: 12 })
139  .borderRadius(24)
140  .backgroundColor('#FFFFFF')
141}
142
143@Extend(Text) function itemTextStyle () {
144  .fontColor('#182431')
145  .fontSize(36)
146  .fontWeight(500)
147  .opacity(0.4)
148  .margin({ top: 82, bottom: 40 })
149}
150
151@Entry
152@Component
153struct StepperExample {
154  @State currentIndex: number = 0;
155  @State firstState: ItemState = ItemState.Normal;
156  @State secondState: ItemState = ItemState.Normal;
157  @State thirdState: ItemState = ItemState.Normal;
158
159  build() {
160    Stepper({
161      index: this.currentIndex
162    }) {
163      // 第一个步骤页
164      StepperItem() {
165        Column() {
166          Text('Page One')
167            .itemTextStyle()
168          Button('change status:' + this.firstState)
169            .backgroundColor('#007dFF')
170            .onClick(() => {
171              this.firstState = this.firstState === ItemState.Skip ? ItemState.Normal : ItemState.Skip;
172            })
173        }.itemStyle()
174      }
175      .nextLabel('Next')
176      .status(this.firstState)
177      // 第二个步骤页
178      StepperItem() {
179        Column() {
180          Text('Page Two')
181            .itemTextStyle()
182          Button('change status:' + this.secondState)
183            .backgroundColor('#007dFF')
184            .onClick(() => {
185              this.secondState = this.secondState === ItemState.Disabled ? ItemState.Normal : ItemState.Disabled;
186            })
187        }.itemStyle()
188      }
189      .nextLabel('Next')
190      .prevLabel('Previous')
191      .status(this.secondState)
192      // 第三个步骤页
193      StepperItem() {
194        Column() {
195          Text('Page Three')
196            .itemTextStyle()
197          Button('change status:' + this.thirdState)
198            .backgroundColor('#007dFF')
199            .onClick(() => {
200              this.thirdState = this.thirdState === ItemState.Waiting ? ItemState.Normal : ItemState.Waiting;
201            })
202        }.itemStyle()
203      }
204      .status(this.thirdState)
205      // 第四个步骤页
206      StepperItem() {
207        Column() {
208          Text('Page Four')
209            .itemTextStyle()
210        }.itemStyle()
211      }
212    }
213    .backgroundColor('#F1F3F5')
214    .onFinish(() => {
215      // 此处可处理点击最后一页的Finish时的逻辑，例如路由跳转等
216      console.info('onFinish');
217    })
218    .onSkip(() => {
219      // 此处可处理点击跳过时的逻辑，例如动态修改Stepper的index值使其跳转到某一步骤页等
220      console.info('onSkip');
221    })
222    .onChange((prevIndex?: number, index?: number) => {
223      if(index){
224        this.currentIndex = index;
225      }
226    })
227  }
228}
229```
230
231
232![stepper](figures/stepper.gif)
233
234