1# Z序控制
2
3组件的Z序，设置组件的堆叠顺序。
4
5>  **说明：**
6>
7>  从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8
9## zIndex
10
11zIndex(value: number)
12
13设置组件的堆叠顺序。
14
15**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
16
17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
18
19**系统能力：** SystemCapability.ArkUI.ArkUI.Full
20
21**参数：**
22
23| 参数名 | 类型   | 必填 | 说明                                                         |
24| ------ | ------ | ---- | ------------------------------------------------------------ |
25| value  | number | 是   | 同一容器中兄弟组件显示层级关系。zIndex值越大，显示层级越高，即zIndex值大的组件会覆盖在zIndex值小的组件上方。当不涉及新增或减少兄弟节点，动态改变zIndex时会在zIndex改变前层级顺序的基础上进行稳定排序。 |
26
27
28## 示例
29
30### 示例1（设置组件堆叠顺序）
31
32该示例通过zIndex设置组件堆叠顺序。
33
34```ts
35// xxx.ets
36@Entry
37@Component
38struct ZIndexExample {
39  build() {
40    Column() {
41      Stack() {
42        // stack会重叠组件, 默认后定义的在最上面，具有较高zIndex值的元素在zIndex较小的元素前面
43        Text('1, zIndex(2)')
44          .size({ width: '40%', height: '30%' }).backgroundColor(0xbbb2cb)
45          .zIndex(2)
46        Text('2, default zIndex(1)')
47          .size({ width: '70%', height: '50%' }).backgroundColor(0xd2cab3).align(Alignment.TopStart)
48          .zIndex(1)
49        Text('3, zIndex(0)')
50          .size({ width: '90%', height: '80%' }).backgroundColor(0xc1cbac).align(Alignment.TopStart)
51      }.width('100%').height(200)
52    }.width('100%').height(200)
53  }
54}
55```
56Stack容器内子组件不设置zIndex的效果
57
58![nozindex.png](figures/nozindex.png)
59
60Stack容器子组件设置zIndex后效果
61
62![zindex.png](figures/zindex.png)
63
64### 示例2（动态修改zIndex属性）
65
66该示例使用Button组件动态修改zIndex属性。
67
68```ts
69// xxx.ets
70@Entry
71@Component
72struct ZIndexExample {
73  @State zIndex_ : number = 0
74  build() {
75    Column() {
76      // 点击Button改变zIndex后，在点击Button前的层级顺序上根据zIndex进行稳定排序。
77      Button("change Text2 zIndex")
78        .onClick(()=>{
79          this.zIndex_ = (this.zIndex_ + 1) % 3;
80        })
81      Stack() {
82        Text('1, zIndex(1)')
83          .size({ width: '70%', height: '50%' }).backgroundColor(0xd2cab3).align(Alignment.TopStart)
84          .zIndex(1)
85        Text('2, default zIndex(0), now zIndex:' + this.zIndex_)
86          .size({ width: '90%', height: '80%' }).backgroundColor(0xc1cbac).align(Alignment.TopStart)
87          .zIndex(this.zIndex_)
88      }.width('100%').height(200)
89    }.width('100%').height(200)
90  }
91}
92```
93
94不点击Button修改zIndex值的效果。
95
96![zIndex_0.png](figures/zIndex_0.png)
97
98点击Button动态修改zIndex，使Text1和Text2的zIndex相等，因为在点击Button前的层级顺序上根据zIndex进行稳定排序，层级顺序不发生改变。
99
100![zIndex_1.png](figures/zIndex_1.png)
101
102点击Button动态修改zIndex，使Text1的zIndex大于Text2，层级发生改变。
103
104![zIndex_2.png](figures/zIndex_2.png)