1# 浮层 2 3设置组件的浮层。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## overlay 10 11overlay(value: string | CustomBuilder | ComponentContent, options?: OverlayOptions ) 12 13在当前组件上，增加遮罩文本或者叠加自定义组件以及ComponentContent作为该组件的浮层。 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 | string \| [CustomBuilder](ts-types.md#custombuilder8)<sup>10+</sup> \| [ComponentContent](../js-apis-arkui-ComponentContent.md)<sup>12+</sup> | 是 | 遮罩文本内容或自定义组件构造函数。<br/>**说明：**<br/>自定义组件作为浮层时，不支持键盘走焦到自定义组件中。 | 26| options | [OverlayOptions](#overlayoptions12) | 否 | 浮层的定位。<br/>**说明：**<br/>需要解析为Json格式。<br/>API version 12之前，options: <br/>{<br/>align?: [Alignment](ts-appendix-enums.md#alignment), <br/>offset?: {x?: number, y?: number}<br/>} | 27 28> **说明：** 29> 30> overlay节点不支持onAppear和onDisappear等和节点生命周期相关的事件。 31 32## OverlayOptions<sup>12+</sup> 33 34**系统能力：** SystemCapability.ArkUI.ArkUI.Full 35 36| 名称 | 类型 | 只读 | 可选 | 说明 | 37| --------------------- | -------------------------------------------| --- | -------| --------------------------------------------------- | 38| align<sup>7+</sup> | [Alignment](ts-appendix-enums.md#alignment) | 否 | 是 |设置浮层相对于组件的方位。<br/>默认值：TopStart | 39| offset<sup>7+</sup> | [OverlayOffset](#overlayoffset12) | 否 | 是 |设置浮层基于自身左上角的偏移量。浮层默认处于组件左上角。 | 40 41> **说明：** 42> 43> align和offset都设置时，效果重叠，浮层相对于组件方位定位后，再基于当前位置的左上角进行偏移。 44 45## OverlayOffset<sup>12+</sup> 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ------- | ---------------------------------------------------------| ---- | ------| --------------------------------------------------- | 49| x | number | 否 | 是 | 横向偏移量 | 50| y | number | 否 | 是 | 纵向偏移量 | 51 52## 示例 53 54### 示例1 55 56```ts 57// xxx.ets 58@Entry 59@Component 60struct OverlayExample { 61 build() { 62 Column() { 63 Column() { 64 Text('floating layer') 65 .fontSize(12).fontColor(0xCCCCCC).maxLines(1) 66 Column() { 67 Image($r('app.media.img')) 68 .width(240).height(240) 69 .overlay("Winter is a beautiful season, especially when it snows.", { 70 align: Alignment.Bottom, 71 offset: { x: 0, y: -15 } 72 }) 73 }.border({ color: Color.Black, width: 2 }) 74 }.width('100%') 75 }.padding({ top: 20 }) 76 } 77} 78``` 79 80 81 82### 示例2 83 84```ts 85// xxx.ets 86@Entry 87@Component 88struct OverlayExample { 89 @Builder OverlayNode() { 90 Column() { 91 Image($r('app.media.img1')) 92 Text("This is overlayNode").fontSize(20).fontColor(Color.White) 93 }.width(180).height(180).alignItems(HorizontalAlign.Center) 94 } 95 96 build() { 97 Column() { 98 Image($r('app.media.img2')) 99 .overlay(this.OverlayNode(), { align: Alignment.Center }) 100 .objectFit(ImageFit.Contain) 101 }.width('100%') 102 .border({ color: Color.Black, width: 2 }).padding(20) 103 } 104} 105``` 106 107 108### 示例3 109通过overlay传入了ComponentContent使backgroundColor不断发生变化 110```ts 111// xxx.ets 112import { ComponentContent } from '@kit.ArkUI'; 113 114class Params{ 115 backgroundColor: string | Resource = "" 116 constructor(backgroundColor: string | Resource) { 117 this.backgroundColor = backgroundColor; 118 } 119} 120 121@Builder 122function overlayBuilder(params: Params){ 123 Row(){ 124 }.width('100%').height('100%').backgroundColor(params.backgroundColor) 125} 126 127@Entry 128@Component 129struct Page_4040 { 130 @State overlayColor: string = 'rgba(0, 0, 0, 0.6)'; 131 private uiContext: UIContext = this.getUIContext(); 132 private overlayNode: ComponentContent<Params> = new ComponentContent(this.uiContext, wrapBuilder(overlayBuilder), new Params(this.overlayColor)) 133 134 aboutToAppear(): void { 135 setInterval(() => { 136 if (this.overlayColor.includes('0.6')) { 137 this.overlayColor = 'rgba(0, 0, 0, 0.1)' 138 this.overlayNode.update(new Params(this.overlayColor)); 139 } else { 140 this.overlayColor = 'rgba(0, 0, 0, 0.6)' 141 this.overlayNode.update(new Params(this.overlayColor)); 142 } 143 }, 1000) 144 } 145 146 build() { 147 Row() { 148 Column(){ 149 Text(this.overlayColor) 150 .fontSize(40) 151 .fontWeight(FontWeight.Bold) 152 } 153 .width('100%') 154 } 155 .height('100%') 156 .overlay(this.overlayNode) 157 } 158} 159``` 160 161
