1# FolderStack 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @fenglinbailu--> 5<!--Designer: @lanshouren--> 6<!--Tester: @liuli0427--> 7<!--Adviser: @HelloCrease--> 8 9FolderStack继承于Stack(层叠布局)控件，新增了<!--RP1-->折叠屏悬停<!--RP1End-->能力，通过在配置项[FolderStackOptions](#folderstackoptions18对象说明)的upperItems数组上设置子组件id，使相应子组件自动避让折叠屏折痕区后移到上半屏。 10 11> **说明：** 12> 13> 该组件从API version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 该组件的悬停态能力针对<!--RP2-->双折叠<!--RP2End-->设计，只在双折叠设备生效。 16> 17> 当该组件的父组件为[if/else条件渲染节点](../../../ui/state-management/arkts-rendering-control-ifelse.md)时，折叠屏悬停能力将会失效。 18 19 20## 子组件 21 22可以包含多个子组件。 23 24 25## 接口 26 27FolderStack(options?: FolderStackOptions) 28 29**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 30 31**系统能力：** SystemCapability.ArkUI.ArkUI.Full 32 33**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| ------------ | ------------------------------------------- | ---- |----------------------------------------------------------------------| 39| options | [FolderStackOptions](#folderstackoptions18对象说明) | 否 | FolderStack的配置项。 | 40 41## FolderStackOptions<sup>18+</sup>对象说明 42 43> **说明：** 44> 45> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 46 47**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.ArkUI.ArkUI.Full 50 51**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 52 53| 名称 | 类型 | 只读 | 可选 | 说明 | 54| -------- | -------- | -------- | -------- | -------- | 55| upperItems<sup>11+</sup> | Array<string\> | 否 | 是 | FolderStack的配置项。<br/>upperItems：定义悬停态会被移到上半屏的子组件的id，组件id在此数组中的子组件悬停触发时自动避让折叠屏折痕区后移到上半屏，其它组件堆叠在下半屏区域。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56 57## 属性 58 59> **说明：** 60> 61> 设置offset和margin属性，可能会导致上下半屏遮挡折痕区，不建议开发者使用。 62 63除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 64 65### alignContent 66 67alignContent(value: Alignment) 68 69设置子组件在容器内的对齐方式。该属性与[通用属性align](ts-universal-attributes-location.md)同时设置时，后设置的属性生效。 70 71**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 72 73**系统能力：** SystemCapability.ArkUI.ArkUI.Full 74 75**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 76 77**参数：** 78 79| 参数名 | 类型 | 必填 | 说明 | 80| ------ | ------------------------------------------- | ---- | ------------------------------------------------------- | 81| value | [Alignment](ts-appendix-enums.md#alignment) | 是 | 子组件在容器内的对齐方式。<br/>默认值：Alignment.Center <br />非法值：按默认值处理。 | 82 83### enableAnimation 84 85enableAnimation(value: boolean) 86 87设置是否使用默认动效。 88 89**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 90 91**系统能力：** SystemCapability.ArkUI.ArkUI.Full 92 93**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ------------------------------------------- | ---- | ----------------------------------- | 99| value | boolean | 是 | 是否使用默认动效。<br/>默认值：true，设置true表示使用默认动效，设置false表示不使用默认动效。<br />非法值：按默认值处理。 | 100 101### autoHalfFold 102 103autoHalfFold(value: boolean) 104 105设置是否开启自动旋转，仅在系统自动旋转关闭时该属性生效。 106 107**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 108 109**系统能力：** SystemCapability.ArkUI.ArkUI.Full 110 111**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| ------ | ------- | ---- | ----------------------------------- | 117| value | boolean | 是 | 是否开启自动旋转。<br/>默认值：true，设置true表示FolderStack在[半折叠状态](ts-appendix-enums.md#foldstatus11)进行布局时开启自动旋转，设置false表示关闭自动旋转。该属性不区分设备类型。<br />非法值：按默认值处理。 | 118 119## 事件 120 121除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 122 123### onFolderStateChange 124 125onFolderStateChange(callback: OnFoldStatusChangeCallback) 126 127当折叠状态改变的时候回调，仅在横屏状态下生效。 128 129**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 130 131**系统能力：** SystemCapability.ArkUI.ArkUI.Full 132 133**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 134 135**参数：** 136 137| 参数名 | 类型 | 必填 | 说明 | 138| ---------- | ----------------------------------------------- | ---- | -------------------- | 139| callback | [OnFoldStatusChangeCallback](#onfoldstatuschangecallback18) | 是 | 当前设备的折叠状态。 | 140 141 142### onHoverStatusChange<sup>12+</sup> 143 144onHoverStatusChange(handler: OnHoverStatusChangeCallback) 145 146当悬停状态改变的时候回调。 147 148**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 153 154**参数：** 155 156| 参数名 | 类型 | 必填 | 说明 | 157| ---------- | ----------------------------------------------- | ---- | -------------------- | 158| handler | [OnHoverStatusChangeCallback](#onhoverstatuschangecallback18) | 是 | 当悬停状态改变的时候触发回调。 | 159 160## OnHoverStatusChangeCallback<sup>18+</sup> 161 162type OnHoverStatusChangeCallback = (param: HoverEventParam) => void 163 164当悬停状态改变的时候触发回调。 165 166**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 167 168**系统能力：** SystemCapability.ArkUI.ArkUI.Full 169 170**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ---------- | ----------------------------------------------- | ---- | -------------------- | 176| param | [HoverEventParam](#hovereventparam12对象说明) | 是 | 当悬停状态改变的时候触发回调。 | 177 178## OnFoldStatusChangeCallback<sup>18+</sup> 179 180type OnFoldStatusChangeCallback = (event: OnFoldStatusChangeInfo) => void 181 182当前设备的折叠状态。 183 184**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 185 186**系统能力：** SystemCapability.ArkUI.ArkUI.Full 187 188**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 189 190**参数：** 191 192| 参数名 | 类型 | 必填 | 说明 | 193| ---------- | ----------------------------------------------- | ---- | -------------------- | 194| event | [OnFoldStatusChangeInfo](#onfoldstatuschangeinfo18) | 是 | 当前设备的折叠状态。 | 195 196 197## OnFoldStatusChangeInfo<sup>18+</sup> 198 199当折叠状态改变的时候回调，仅在横屏状态下生效。 200 201> **说明：** 202> 203> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 204 205**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 206 207**系统能力：** SystemCapability.ArkUI.ArkUI.Full 208 209**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 210 211| 名称 | 类型 | 只读 | 可选 | 说明 | 212| -------- | -------- | -------- | -------- | -------- | 213| foldStatus<sup>11+</sup> | [FoldStatus](ts-appendix-enums.md#foldstatus11) | 否 | 否 | 当前设备的折叠状态。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 214 215## HoverEventParam<sup>12+</sup>对象说明 216 217**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 218 219**系统能力：** SystemCapability.ArkUI.ArkUI.Full 220 221**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 222 223| 名称 | 类型 | 只读 | 可选 | 说明 | 224| -------- | -------- | -------- | -------- | -------- | 225| foldStatus | [FoldStatus](ts-appendix-enums.md#foldstatus11) | 否 | 否 | 当前设备的折叠状态。 | 226| isHoverMode | boolean | 否 | 否 | 当前是否为悬停态。设置为true时表示当前为悬停态，设置为false时表示当前为非悬停态。 | 227| appRotation | [AppRotation](ts-appendix-enums.md#approtation12) | 否 | 否 | 当前应用方向。 | 228| windowStatusType | [WindowStatusType](#windowstatustype12) | 否 | 否 | 窗口模式枚举。 | 229 230## WindowStatusType<sup>12+</sup> 231 232type WindowStatusType = WindowStatusType 233 234窗口模式枚举。 235 236**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 237 238**系统能力：** SystemCapability.ArkUI.ArkUI.Full 239 240**设备行为差异：** 该接口在Wearable设备上使用时，应用程序运行异常，异常信息中提示接口未定义，在其他设备中可正常调用。 241 242| 类型 | 说明 | 243| ---------- | ---------------------| 244| [WindowStatusType](../arkts-apis-window-e.md#windowstatustype11) | 窗口模式枚举。 | 245 246## 示例 247 248### 示例1（FolderStack折叠屏悬停能力） 249 250该示例实现了折叠屏悬停能力。 251 252```ts 253@Entry 254@Component 255struct Index { 256 @State len_wid: number = 480 257 @State w: string = "40%" 258 259 build() { 260 Column() { 261 // upperItems将所需要的悬停到上半屏的id放入upperItems传入，其余组件会堆叠在下半屏区域 262 FolderStack({ upperItems: ["upperitemsId"] }) { 263 // 此Column会自动上移到上半屏 264 Column() { 265 Text("video zone").height("100%").width("100%").textAlign(TextAlign.Center).fontSize(25) 266 }.backgroundColor('rgb(0, 74, 175)').width("100%").height("100%").id("upperitemsId") 267 268 // 下列两个Column堆叠在下半屏区域 269 Column() { 270 Text("video title") 271 .width("100%") 272 .height(50) 273 .textAlign(TextAlign.Center) 274 .backgroundColor('rgb(213, 213, 213)') 275 .fontSize(25) 276 }.width("100%").height("100%").justifyContent(FlexAlign.Start) 277 278 Column() { 279 Text("video bar ") 280 .width("100%") 281 .height(50) 282 .textAlign(TextAlign.Center) 283 .backgroundColor('rgb(213, 213, 213)') 284 .fontSize(25) 285 }.width("100%").height("100%").justifyContent(FlexAlign.End) 286 } 287 .backgroundColor('rgb(39, 135, 217)') 288 // 是否启动动效 289 .enableAnimation(true) 290 // 是否自动旋转 291 .autoHalfFold(true) 292 // folderStack回调 当折叠状态改变时回调 293 .onFolderStateChange((msg) => { 294 if (msg.foldStatus === FoldStatus.FOLD_STATUS_EXPANDED) { 295 console.info("The device is currently in the expanded state") 296 } else if (msg.foldStatus === FoldStatus.FOLD_STATUS_HALF_FOLDED) { 297 console.info("The device is currently in the half folded state") 298 } else { 299 // ............. 300 } 301 }) 302 // hoverStatusChange回调 当悬停状态改变时回调 303 .onHoverStatusChange((msg) => { 304 console.info('this foldStatus:' + msg.foldStatus); 305 console.info('this isHoverMode:' + msg.isHoverMode); 306 console.info('this appRotation:' + msg.appRotation); 307 console.info('this windowStatusType:' + msg.windowStatusType); 308 }) 309 // folderStack如果不撑满页面全屏，作为普通Stack使用 310 .alignContent(Alignment.Bottom) 311 .height("100%") 312 .width("100%") 313 .backgroundColor('rgb(39, 135, 217)') 314 315 } 316 .height("100%") 317 .width("100%") 318 .borderWidth(1) 319 .borderColor('rgb(213, 213, 213)') 320 .backgroundColor('rgb(0, 74, 175)') 321 .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM]) 322 } 323} 324``` 325**图1** 横屏展开 326</br>  327</br> **图2** 横屏半折叠 328</br>  329 330### 示例2（使用attributeModifier动态设置FolderStack组件的属性及方法） 331 332该示例展示了如何使用attributeModifier动态设置FolderStack组件的onFolderStateChange和onHoverStatusChange方法。 333 334```ts 335// xxx.ets 336class MyFolderStackModifier implements AttributeModifier<FolderStackAttribute> { 337 applyNormalAttribute(instance: FolderStackAttribute): void { 338 // folderStack回调 当折叠状态改变时回调 339 instance.onFolderStateChange((msg) => { 340 if (msg.foldStatus === FoldStatus.FOLD_STATUS_EXPANDED) { 341 console.info("The device is currently in the expanded state") 342 } else if (msg.foldStatus === FoldStatus.FOLD_STATUS_HALF_FOLDED) { 343 console.info("The device is currently in the half folded state") 344 } else if (msg.foldStatus === FoldStatus.FOLD_STATUS_FOLDED) { 345 console.info("The device is currently in the folded state") 346 } else { 347 // ............. 348 } 349 }) 350 // hoverStatusChange回调 当悬停状态改变时回调 351 instance.onHoverStatusChange((msg) => { 352 console.info('this foldStatus:' + msg.foldStatus); 353 console.info('this isHoverMode:' + msg.isHoverMode); 354 console.info('this appRotation:' + msg.appRotation); 355 console.info('this windowStatusType:' + msg.windowStatusType); 356 }) 357 } 358} 359 360@Entry 361@Component 362struct attributeDemo { 363 @State modifier: MyFolderStackModifier = new MyFolderStackModifier() 364 365 build() { 366 Column() { 367 // upperItems将所需要的悬停到上半屏的id放入upperItems传入，其余组件会堆叠在下半屏区域 368 FolderStack({ upperItems: ["upperitemsId"] }) { 369 // 此Column会自动上移到上半屏 370 Column() { 371 Text("video zone").height("100%").width("100%").textAlign(TextAlign.Center).fontSize(25) 372 }.backgroundColor('rgb(0, 74, 175)').width("100%").height("100%").id("upperitemsId") 373 374 // 下列两个Column堆叠在下半屏区域 375 Column() { 376 Text("video title") 377 .width("100%") 378 .height(50) 379 .textAlign(TextAlign.Center) 380 .backgroundColor('rgb(213, 213, 213)') 381 .fontSize(25) 382 }.width("100%").height("100%").justifyContent(FlexAlign.Start) 383 384 Column() { 385 Text("video bar ") 386 .width("100%") 387 .height(50) 388 .textAlign(TextAlign.Center) 389 .backgroundColor('rgb(213, 213, 213)') 390 .fontSize(25) 391 }.width("100%").height("100%").justifyContent(FlexAlign.End) 392 } 393 .backgroundColor('rgb(39, 135, 217)') 394 // 是否启动动效 395 .enableAnimation(true) 396 // 是否自动旋转 397 .autoHalfFold(true) 398 .attributeModifier(this.modifier) 399 // folderStack如果不撑满页面全屏，作为普通Stack使用 400 .alignContent(Alignment.Bottom) 401 .height("100%") 402 .width("100%") 403 .backgroundColor('rgb(39, 135, 217)') 404 } 405 .height("100%") 406 .width("100%") 407 .borderWidth(1) 408 .borderColor('rgb(213, 213, 213)') 409 .backgroundColor('rgb(0, 74, 175)') 410 .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM]) 411 } 412} 413``` 414 415**图1** 横屏展开 416</br> 预期日志： 417</br> The device is currently in the expanded state 418</br> this foldStatus:1 419</br> this isHoverMode:0 420</br> this appRotation:3 421</br> this windowStatusType:1 422</br>  423</br> **图2** 横屏半折叠 424</br> 预期日志： 425</br> The device is currently in the half folded state 426</br> this foldStatus:3 427</br> this isHoverMode:1 428</br> this appRotation:3 429</br> this windowStatusType:1 430</br> 
