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