1# FolderStack
2
3The **FolderStack** component extends the **Stack** component by adding the hover feature for foldable devices. With the **upperItems** parameter set, it can automatically avoid the crease area of the foldable device and move the content to the upper half screen.
4
5>  **NOTE**
6>
7>  This component is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version.
8
9
10## Child Components
11
12Multiple child components are supported.
13
14
15## APIs
16
17FolderStack(options?: FolderStackOptions)
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name      | Type                                   | Mandatory| Description                                                                |
26| ------------ | ------------------------------------------- | ---- |----------------------------------------------------------------------|
27| options |  [FolderStackOptions](#folderstackoptions14) | No  | Configuration of the **FolderStack** component.|
28
29## FolderStackOptions<sup>14+</sup>
30
31**Atomic service API**: This API can be used in atomic services since API version 14.
32
33**System capability**: SystemCapability.ArkUI.ArkUI.Full
34
35| Name      | Type        | Mandatory| Description                      |
36| ------------ | -------------------------- | ---- |----------------------------|
37| upperItems |    Array<string\>  | No  | Configuration of the **FolderStack** component.<br>**upperItems**: array of IDs of child components that will be moved to the upper half screen in the hover state. On hover, child components with IDs in this array automatically shift away from the folding screen's crease area and move to the upper half screen, while other components are stacked in the lower half screen.|
38
39## Attributes
40
41In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
42
43### alignContent
44
45alignContent(value: Alignment)
46
47Alignment of child components in the container. When both this attribute and the universal attribute [align](ts-universal-attributes-location.md) are set, whichever is set last takes effect.
48
49**Atomic service API**: This API can be used in atomic services since API version 12.
50
51**System capability**: SystemCapability.ArkUI.ArkUI.Full
52
53**Parameters**
54
55| Name| Type                                       | Mandatory| Description                                                   |
56| ------ | ------------------------------------------- | ---- | ------------------------------------------------------- |
57| value  | [Alignment](ts-appendix-enums.md#alignment) | Yes  | Alignment of child components in the container.<br>Default value: **Alignment.Center**|
58
59### enableAnimation
60
61enableAnimation(value: boolean)
62
63Whether to enable the default animation.
64
65**Atomic service API**: This API can be used in atomic services since API version 12.
66
67**System capability**: SystemCapability.ArkUI.ArkUI.Full
68
69**Parameters**
70
71| Name| Type                                       | Mandatory| Description                               |
72| ------ | ------------------------------------------- | ---- | ----------------------------------- |
73| value  | boolean | Yes  | Whether to enable the default animation.<br>Default value: **true**|
74
75### autoHalfFold
76
77autoHalfFold(value: boolean)
78
79Sets whether to enable auto rotation. This attribute is effective only when auto rotation is disabled in device system settings.
80
81**Atomic service API**: This API can be used in atomic services since API version 12.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85**Parameters**
86
87| Name| Type   | Mandatory| Description                               |
88| ------ | ------- | ---- | ----------------------------------- |
89| value  | boolean | Yes  | Whether to enable auto rotation.<br>Default value: **true**|
90
91>  **NOTE**
92>
93>  Setting the **offset** and **margin** attributes may cause the upper and lower half screens to block the crease area. Therefore, avoid setting these attributes with this component.
94
95## Events
96
97In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
98
99### onFolderStateChange
100
101onFolderStateChange(callback: OnFoldStatusChangeCallback)
102
103Called when the folding state changes. This API takes effect only in landscape mode.
104
105**Atomic service API**: This API can be used in atomic services since API version 12.
106
107**System capability**: SystemCapability.ArkUI.ArkUI.Full
108
109**Parameters**
110
111| Name    | Type                                           | Mandatory| Description                |
112| ---------- | ----------------------------------------------- | ---- | -------------------- |
113| callback | [OnFoldStatusChangeCallback](#onfoldstatuschangecallback14) | Yes  | Current fold state of the device.|
114
115
116### onHoverStatusChange<sup>12+</sup>
117
118onHoverStatusChange(handler: OnHoverStatusChangeCallback)
119
120Invoked when the hover status changes.
121
122**Atomic service API**: This API can be used in atomic services since API version 12.
123
124**System capability**: SystemCapability.ArkUI.ArkUI.Full
125
126**Parameters**
127
128| Name    | Type                                           | Mandatory| Description                |
129| ---------- | ----------------------------------------------- | ---- | -------------------- |
130| handler | [OnHoverStatusChangeCallback](#onhoverstatuschangecallback14) | Yes  | Callback invoked when the hover status changes.|
131
132## OnHoverStatusChangeCallback<sup>14+</sup>
133
134type OnHoverStatusChangeCallback = (param: HoverEventParam) => void
135
136Callback invoked when the hover status changes.
137
138**Atomic service API**: This API can be used in atomic services since API version 14.
139
140**System capability**: SystemCapability.ArkUI.ArkUI.Full
141
142| Name    | Type                                           | Mandatory| Description                |
143| ---------- | ----------------------------------------------- | ---- | -------------------- |
144| param | [HoverEventParam](#hovereventparam12) | Yes  | Callback invoked when the hover status changes.|
145
146## OnFoldStatusChangeCallback<sup>14+</sup>
147
148type OnFoldStatusChangeCallback = (event: OnFoldStatusChangeInfo) => void
149
150Current fold state of the device.
151
152**Atomic service API**: This API can be used in atomic services since API version 14.
153
154**System capability**: SystemCapability.ArkUI.ArkUI.Full
155
156| Name    | Type                                           | Mandatory| Description                |
157| ---------- | ----------------------------------------------- | ---- | -------------------- |
158| callback | [OnFoldStatusChangeInfo](#onfoldstatuschangeinfo14) | Yes  | Current fold state of the device.|
159
160
161## OnFoldStatusChangeInfo<sup>14+</sup>
162
163Called when the folding state changes. This API takes effect only in landscape mode.
164
165**Atomic service API**: This API can be used in atomic services since API version 14.
166
167**System capability**: SystemCapability.ArkUI.ArkUI.Full
168
169| Name    | Type                                           | Mandatory| Description                |
170| ---------- | ----------------------------------------------- | ---- | -------------------- |
171| foldStatus | [FoldStatus](ts-appendix-enums.md#foldstatus11) | Yes  | Current fold state of the device.|
172
173## HoverEventParam<sup>12+</sup>
174
175**Atomic service API**: This API can be used in atomic services since API version 12.
176
177**System capability**: SystemCapability.ArkUI.ArkUI.Full
178
179| Name             | Type                                                         | Mandatory| Description        |
180|------------------|-------------------------------------------------------------| --- |------------|
181| foldStatus       | [FoldStatus](ts-appendix-enums.md#foldstatus11)             | Yes  | Current fold state of the device.|
182| isHoverMode      | boolean                                                     | Yes  | Whether the device is in hover state. |
183| appRotation      | [AppRotation](ts-appendix-enums.md#approtation12)           | Yes  | Current orientation.   |
184| windowStatusType | [WindowStatusType<sup>12+</sup>](#windowstatustype12) | Yes  | Window mode.   |
185
186## WindowStatusType<sup>12+</sup>
187
188type WindowStatusType = WindowStatusType
189
190Enumerates the window modes.
191
192**Atomic service API**: This API can be used in atomic services since API version 12.
193
194**System capability**: SystemCapability.ArkUI.ArkUI.Full
195
196| Type       | Description                |
197| ---------- | ---------------------|
198| [WindowStatusType](../js-apis-window.md#windowstatustype11)  | Window mode.|
199
200
201## Example
202
203This example implements the foldable device hover capability.
204
205```ts
206@Entry
207@Component
208struct Index {
209  @State len_wid: number = 480
210  @State w: string = "40%"
211
212  build() {
213    Column() {
214      // Set upperItems to IDs of the child components to be moved to the upper half screen in the hover state. Other components are stacked in the lower half screen.
215      FolderStack({ upperItems: ["upperitemsId"] }) {
216        // This column is automatically moved up to the upper half screen.
217        Column() {
218          Text("video zone").height("100%").width("100%").textAlign(TextAlign.Center).fontSize(25)
219        }.backgroundColor('rgb(0, 74, 175)').width("100%").height("100%").id("upperitemsId")
220
221        // The following two columns are stacked in the lower half screen.
222        Column() {
223          Text("video title")
224            .width("100%")
225            .height(50)
226            .textAlign(TextAlign.Center)
227            .backgroundColor('rgb(213, 213, 213)')
228            .fontSize(25)
229        }.width("100%").height("100%").justifyContent(FlexAlign.Start)
230
231        Column() {
232          Text("video bar ")
233            .width("100%")
234            .height(50)
235            .textAlign(TextAlign.Center)
236            .backgroundColor('rgb(213, 213, 213)')
237            .fontSize(25)
238        }.width("100%").height("100%").justifyContent(FlexAlign.End)
239      }
240      .backgroundColor('rgb(39, 135, 217)')
241      // Set whether to enable animation.
242      .enableAnimation(true)
243      // Set whether to enable auto-rotate.
244      .autoHalfFold(true)
245      // Called when the folding status changes.
246      .onFolderStateChange((msg) => {
247        if (msg.foldStatus === FoldStatus.FOLD_STATUS_EXPANDED) {
248          console.info("The device is currently in the expanded state")
249        } else if (msg.foldStatus === FoldStatus.FOLD_STATUS_HALF_FOLDED) {
250          console.info("The device is currently in the half folded state")
251        } else {
252          // .............
253        }
254      })
255      // The hoverStatusChange callback is invoked when the hover status changes.
256      .onHoverStatusChange((msg) => {
257        console.log('this foldStatus:' + msg.foldStatus);
258        console.log('this isHoverMode:' + msg.isHoverMode);
259        console.log('this appRotation:' + msg.appRotation);
260        console.log('this windowStatusType:' + msg.windowStatusType);
261      })
262      // If the folderStack component does not occupy the full screen, it is used as a common stack.
263      .alignContent(Alignment.Bottom)
264      .height("100%")
265      .width("100%")
266      .backgroundColor('rgb(39, 135, 217)')
267
268    }
269    .height("100%")
270    .width("100%")
271    .borderWidth(1)
272    .borderColor('rgb(213, 213, 213)')
273    .backgroundColor('rgb(0, 74, 175)')
274    .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
275  }
276}
277```
278**Figure 1** Expanded state in landscape mode
279<br> ![FolderStack01.png](figures/FolderStack01.png)
280<br> **Figure 2** Half-folded state in landscape mode
281<br> ![FolderStack02.png](figures/FolderStack02.png)
282