• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Z-order Control
2
3The **zIndex** attribute sets the z-order of a component in the stacking context.
4
5>  **NOTE**
6>
7>  The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
8
9## zIndex
10
11zIndex(value: number)
12
13Sets the stack level of the component.
14
15**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
16
17**Atomic service API**: This API can be used in atomic services since API version 11.
18
19**System capability**: SystemCapability.ArkUI.ArkUI.Full
20
21**Parameters**
22
23| Name| Type  | Mandatory| Description                                                        |
24| ------ | ------ | ---- | ------------------------------------------------------------ |
25| value  | number | Yes  | Stacking order of the component relative to its sibling components in a container. The components with a larger z-index value cover those with a smaller one. When dynamically changing zIndex does not involve adding or removing sibling nodes, the components are sorted stably based on their previous stack level.|
26
27
28## Example
29
30### Example 1: Setting the Component Stacking Order
31
32This example demonstrates how to set the stacking order of components using **zIndex**.
33
34```ts
35// xxx.ets
36@Entry
37@Component
38struct ZIndexExample {
39  build() {
40    Column() {
41      Stack() {
42        // Components are stacked. By default, the component defined later is on the top. A component with a larger zIndex value is displayed before one with a smaller zIndex value.
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```
56Display of child components in the **Stack** component when **zIndex** is not set
57
58![nozindex.png](figures/nozindex.png)
59
60Display of child components in the **Stack** component when **zIndex** is set
61
62![zindex.png](figures/zindex.png)
63
64### Example 2: Dynamically Modifying the zIndex Attribute
65
66This example demonstrates dynamically modifying the **zIndex** attribute on a **Button** component.
67
68```ts
69// xxx.ets
70@Entry
71@Component
72struct ZIndexExample {
73  @State zIndex_ : number = 0
74  build() {
75    Column() {
76      // Clicking the Button component changes the zIndex value. Components are sorted stably based on their previous stacking order.
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
94Effect without clicking the **Button** component to change **zIndex**
95
96![zIndex_0.png](figures/zIndex_0.png)
97
98Effect after clicking the **Button** component to dynamically change **zIndex** so that **Text1** and **Text2** have the same **zIndex** value
99
100![zIndex_1.png](figures/zIndex_1.png)
101
102Effect after clicking the **Button** component to dynamically change **zIndex** so that **Text1** has a higher **zIndex** value than **Text2**
103
104![zIndex_2.png](figures/zIndex_2.png)
105