• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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```ts
33// xxx.ets
34@Entry
35@Component
36struct ZIndexExample {
37  build() {
38    Column() {
39      Stack() {
40        // stack会重叠组件, 默认后定义的在最上面，具有较高zIndex值的元素在zIndex较小的元素前面
41        Text('1, zIndex(2)')
42          .size({ width: '40%', height: '30%' }).backgroundColor(0xbbb2cb)
43          .zIndex(2)
44        Text('2, default zIndex(1)')
45          .size({ width: '70%', height: '50%' }).backgroundColor(0xd2cab3).align(Alignment.TopStart)
46          .zIndex(1)
47        Text('3, zIndex(0)')
48          .size({ width: '90%', height: '80%' }).backgroundColor(0xc1cbac).align(Alignment.TopStart)
49      }.width('100%').height(200)
50    }.width('100%').height(200)
51  }
52}
53```
54Stack容器内子组件不设置zIndex的效果
55
56![nozindex.png](figures/nozindex.png)
57
58Stack容器子组件设置zIndex后效果
59
60![zindex.png](figures/zindex.png)
61
62### 示例2
63
64使用Button组件动态修改zIndex属性。
65
66```ts
67// xxx.ets
68@Entry
69@Component
70struct ZIndexExample {
71  @State zIndex_ : number = 0
72  build() {
73    Column() {
74      // 点击Button改变zIndex后，在点击Button前的层级顺序上根据zIndex进行稳定排序。
75      Button("change Text2 zIndex")
76        .onClick(()=>{
77          this.zIndex_ = (this.zIndex_ + 1) % 3;
78        })
79      Stack() {
80        Text('1, zIndex(1)')
81          .size({ width: '70%', height: '50%' }).backgroundColor(0xd2cab3).align(Alignment.TopStart)
82          .zIndex(1)
83        Text('2, default zIndex(0), now zIndex:' + this.zIndex_)
84          .size({ width: '90%', height: '80%' }).backgroundColor(0xc1cbac).align(Alignment.TopStart)
85          .zIndex(this.zIndex_)
86      }.width('100%').height(200)
87    }.width('100%').height(200)
88  }
89}
90```
91
92不点击Button修改zIndex值的效果。
93
94![zIndex_0.png](figures/zIndex_0.png)
95
96点击Button动态修改zIndex，使Text1和Text2的zIndex相等，因为在点击Button前的层级顺序上根据zIndex进行稳定排序，层级顺序不发生改变。
97
98![zIndex_1.png](figures/zIndex_1.png)
99
100点击Button动态修改zIndex，使Text1的zIndex大于Text2，层级发生改变。
101
102![zIndex_2.png](figures/zIndex_2.png)