1# 浮层 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9设置组件的浮层。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## overlay 16 17overlay(value: string | CustomBuilder | ComponentContent, options?: OverlayOptions ): T 18 19在当前组件上，增加遮罩文本或者叠加自定义组件以及ComponentContent作为该组件的浮层。浮层的定位同样基于当前组件进行计算。浮层不通过组件树进行渲染，部分接口（例如[getRectangleById](../js-apis-arkui-componentUtils.md#componentutilsgetrectanglebyiddeprecated)）不支持获取浮层中的组件。 20 21>**说明：** 22> 23> overlay会将浮层组件覆盖在所绑定的组件上方，阻塞用户对浮层下方组件的所有交互操作。若需用户可操作下方组件，应参照[示例2（通过builder设置浮层）](#示例2通过builder设置浮层)中的实现，在浮层builder的最外层组件上配置`.hitTestBehavior(HitTestMode.Transparent)`。此配置在通过浮层实现水印时尤其重要，因为水印显示不应妨碍用户对下层组件的操作。 24 25**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 35| value | string \| [CustomBuilder](ts-types.md#custombuilder8)<sup>10+</sup> \| [ComponentContent](#componentcontent12)<sup>12+</sup> | 是 | 遮罩文本内容或自定义组件构造函数。<br/>**说明：**<br/>自定义组件作为浮层时，不支持键盘走焦到自定义组件中。通过CustomBuilder设置浮层时，浮层中的内容会在页面刷新时销毁并重新创建，存在一定的性能损耗，页面频繁刷新的场景推荐使用ComponentContent方式设置浮层。 | 36| options | [OverlayOptions](#overlayoptions12) | 否 | 浮层的定位。<br/>**说明：**<br/>API version 12之前，options: <br/>{<br/>align?: [Alignment](ts-appendix-enums.md#alignment), <br/>offset?: {x?: number, y?: number}<br/>} | 37 38**返回值：** 39 40| 类型 | 说明 | 41| -------- | -------- | 42| T | 返回当前组件。 | 43 44> **说明：** 45> 46> overlay节点不支持onAppear和onDisappear等和节点挂载/卸载相关的事件。 47 48## OverlayOptions<sup>12+</sup> 49 50> **说明：** 51> 52> 为规范匿名对象的定义，API 12版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 53 54**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 55 56**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 57 58**系统能力：** SystemCapability.ArkUI.ArkUI.Full 59 60| 名称 | 类型 | 只读 | 可选 | 说明 | 61| --------------------- | -------------------------------------------| --- | -------| --------------------------------------------------- | 62| align<sup>7+</sup> | [Alignment](ts-appendix-enums.md#alignment) | 否 | 是 |设置浮层相对于组件的方位。<br/>默认值：TopStart<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 63| offset<sup>7+</sup> | [OverlayOffset](#overlayoffset12) | 否 | 是 |设置浮层基于自身左上角的偏移量。浮层默认处于组件左上角。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 64 65> **说明：** 66> 67> align和offset都设置时，效果重叠，浮层相对于组件方位定位后，再基于当前位置的左上角进行偏移。 68 69## OverlayOffset<sup>12+</sup> 70 71> **说明：** 72> 73> 为规范匿名对象的定义，API 12版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 74 75**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 76 77**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 78 79**系统能力：** SystemCapability.ArkUI.ArkUI.Full 80 81| 名称 | 类型 | 只读 | 可选 | 说明 | 82| ------- | ---------------------------------------------------------| ---- | ------| --------------------------------------------------- | 83| x<sup>7+</sup> | number | 否 | 是 | 横向偏移量。<br />单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 84| y<sup>7+</sup> | number | 否 | 是 | 纵向偏移量。<br />单位：vp<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 85 86## ComponentContent<sup>12+</sup> 87 88type ComponentContent\<T \= Object\> = ComponentContent\<T\> 89 90组件内容的实体封装。 91 92**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 93 94**系统能力：** SystemCapability.ArkUI.ArkUI.Full 95 96| 类型|说明 | 97| ----- | ----------------- | 98| [ComponentContent](../js-apis-arkui-ComponentContent.md) | 组件内容的实体封装。| 99 100## 示例 101 102### 示例1（通过string设置浮层） 103 104该示例通过传入string设置浮层。 105 106```ts 107// xxx.ets 108@Entry 109@Component 110struct OverlayExample { 111 build() { 112 Column() { 113 Column() { 114 Text('floating layer') 115 .fontSize(12).fontColor(0xCCCCCC).maxLines(1) 116 Column() { 117 Image($r('app.media.img')) 118 .width(240).height(240) 119 .overlay("Winter is a beautiful season, especially when it snows.", { 120 align: Alignment.Bottom, 121 offset: { x: 0, y: -15 } 122 }) 123 }.border({ color: Color.Black, width: 2 }) 124 }.width('100%') 125 }.padding({ top: 20 }) 126 } 127} 128``` 129 130 131 132### 示例2（通过builder设置浮层） 133 134该示例通过传入builder设置浮层。 135 136```ts 137// xxx.ets 138@Entry 139@Component 140struct OverlayExample { 141 @Builder OverlayNode() { 142 Column() { 143 Image($r('app.media.img1')) 144 Text("This is overlayNode").fontSize(20).fontColor(Color.White) 145 } 146 .width(180) 147 .height(180) 148 .alignItems(HorizontalAlign.Center) 149 .hitTestBehavior(HitTestMode.Transparent) // 配置浮层不阻塞交互 150 } 151 152 build() { 153 Column() { 154 Image($r('app.media.img2')) 155 .overlay(this.OverlayNode(), { align: Alignment.Center }) 156 .objectFit(ImageFit.Contain) 157 }.width('100%') 158 .border({ color: Color.Black, width: 2 }).padding(20) 159 } 160} 161``` 162 163 164### 示例3（通过ComponentContent设置浮层） 165 166该示例通过overlay传入了ComponentContent使backgroundColor不断发生变化。 167 168```ts 169// xxx.ets 170import { ComponentContent } from '@kit.ArkUI'; 171 172class Params{ 173 backgroundColor: string | Resource = "" 174 constructor(backgroundColor: string | Resource) { 175 this.backgroundColor = backgroundColor; 176 } 177} 178 179@Builder 180function overlayBuilder(params: Params){ 181 Row(){ 182 }.width('100%').height('100%').backgroundColor(params.backgroundColor) 183} 184 185@Entry 186@Component 187struct Page_4040 { 188 @State overlayColor: string = 'rgba(0, 0, 0, 0.6)'; 189 private uiContext: UIContext = this.getUIContext(); 190 private overlayNode: ComponentContent<Params> = new ComponentContent(this.uiContext, wrapBuilder(overlayBuilder), new Params(this.overlayColor)) 191 192 aboutToAppear(): void { 193 setInterval(() => { 194 if (this.overlayColor.includes('0.6')) { 195 this.overlayColor = 'rgba(0, 0, 0, 0.1)' 196 this.overlayNode.update(new Params(this.overlayColor)); 197 } else { 198 this.overlayColor = 'rgba(0, 0, 0, 0.6)' 199 this.overlayNode.update(new Params(this.overlayColor)); 200 } 201 }, 1000) 202 } 203 204 build() { 205 Row() { 206 Column(){ 207 Text(this.overlayColor) 208 .fontSize(40) 209 .fontWeight(FontWeight.Bold) 210 } 211 .width('100%') 212 } 213 .height('100%') 214 .overlay(this.overlayNode) 215 } 216} 217``` 218 219
