1# Overlay 2 3The overlay feature allows you to place elements on top of a component. 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## overlay 10 11overlay(value: string | CustomBuilder | ComponentContent, options?: OverlayOptions ) 12 13Adds an overlay to this component, which can be text, a custom component, or **ComponentContent**. The overlay is not rendered through the component tree, meaning some APIs (for example, [getRectangleById](../js-apis-arkui-componentUtils.md#componentutilsgetrectanglebyid)) cannot access components within the overlay. 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 | string \| [CustomBuilder](ts-types.md#custombuilder8)<sup>10+</sup> \| [ComponentContent](../js-apis-arkui-ComponentContent.md)<sup>12+</sup> | Yes | Content of the overlay, which can be text or a custom component.<br>**NOTE**<br>When the overlay is a custom component, it cannot obtain focus through sequential keyboard navigation. Using **CustomBuilder** will cause the overlay content to be destroyed and recreated on page refresh, which may incur performance overhead. For scenarios with frequent page updates, using **ComponentContent** is recommended.| 26| options | [OverlayOptions](#overlayoptions12) | No | Options for positioning the overlay.<br>**NOTE**<br>The value must be in JSON format.<br>In versions earlier than API version 12, **options** is defined as follows:<br>{<br>align?: [Alignment](ts-appendix-enums.md#alignment), <br>offset?: {x?: number, y?: number}<br>} | 27 28> **NOTE** 29> 30> The overlay node does not support events related to node mounting or unmounting, such as **onAppear** and **onDisappear**. 31 32## OverlayOptions<sup>12+</sup> 33 34**System capability**: SystemCapability.ArkUI.ArkUI.Full 35 36| Name | Type | Read Only| Optional | Description | 37| --------------------- | -------------------------------------------| --- | -------| --------------------------------------------------- | 38| align<sup>7+</sup> | [Alignment](ts-appendix-enums.md#alignment) | No | Yes |Alignment of the overlay relative to the component.<br>Default value: **TopStart** | 39| offset<sup>7+</sup> | [OverlayOffset](#overlayoffset12) | No | Yes |Offset of the overlay from the upper left corner. By default, the overlay is in the upper left corner of the component.| 40 41> **NOTE** 42> 43> When both **align** and **offset** are set, the effects are combined. The overlay is first aligned relative to the component and then offset from its current upper left corner. 44 45## OverlayOffset<sup>12+</sup> 46 47| Name | Type | Read Only| Optional | Description | 48| ------- | ---------------------------------------------------------| ---- | ------| --------------------------------------------------- | 49| x | number | No | Yes | Horizontal offset.<br>Unit: vp. | 50| y | number | No | Yes | Vertical offset.<br>Unit: vp. | 51 52## Example 53 54### Example 1: Setting an Overlay Using a String 55 56This example demonstrates how to set an overlay using a string. 57 58```ts 59// xxx.ets 60@Entry 61@Component 62struct OverlayExample { 63 build() { 64 Column() { 65 Column() { 66 Text('floating layer') 67 .fontSize(12).fontColor(0xCCCCCC).maxLines(1) 68 Column() { 69 Image($r('app.media.img')) 70 .width(240).height(240) 71 .overlay("Winter is a beautiful season, especially when it snows.", { 72 align: Alignment.Bottom, 73 offset: { x: 0, y: -15 } 74 }) 75 }.border({ color: Color.Black, width: 2 }) 76 }.width('100%') 77 }.padding({ top: 20 }) 78 } 79} 80``` 81 82 83 84### Example 2: Setting an Overlay Using a Custom Builder 85 86This example demonstrates how to set an overlay using a custom builder. 87 88```ts 89// xxx.ets 90@Entry 91@Component 92struct OverlayExample { 93 @Builder OverlayNode() { 94 Column() { 95 Image($r('app.media.img1')) 96 Text("This is overlayNode").fontSize(20).fontColor(Color.White) 97 }.width(180).height(180).alignItems(HorizontalAlign.Center) 98 } 99 100 build() { 101 Column() { 102 Image($r('app.media.img2')) 103 .overlay(this.OverlayNode(), { align: Alignment.Center }) 104 .objectFit(ImageFit.Contain) 105 }.width('100%') 106 .border({ color: Color.Black, width: 2 }).padding(20) 107 } 108} 109``` 110 111 112### Example 3: Setting an Overlay Using ComponentContent 113 114This example demonstrates how to use **ComponentContent** to dynamically change the background color of the overlay. 115 116```ts 117// xxx.ets 118import { ComponentContent } from '@kit.ArkUI'; 119 120class Params{ 121 backgroundColor: string | Resource = "" 122 constructor(backgroundColor: string | Resource) { 123 this.backgroundColor = backgroundColor; 124 } 125} 126 127@Builder 128function overlayBuilder(params: Params){ 129 Row(){ 130 }.width('100%').height('100%').backgroundColor(params.backgroundColor) 131} 132 133@Entry 134@Component 135struct Page_4040 { 136 @State overlayColor: string = 'rgba(0, 0, 0, 0.6)'; 137 private uiContext: UIContext = this.getUIContext(); 138 private overlayNode: ComponentContent<Params> = new ComponentContent(this.uiContext, wrapBuilder(overlayBuilder), new Params(this.overlayColor)) 139 140 aboutToAppear(): void { 141 setInterval(() => { 142 if (this.overlayColor.includes('0.6')) { 143 this.overlayColor = 'rgba(0, 0, 0, 0.1)' 144 this.overlayNode.update(new Params(this.overlayColor)); 145 } else { 146 this.overlayColor = 'rgba(0, 0, 0, 0.6)' 147 this.overlayNode.update(new Params(this.overlayColor)); 148 } 149 }, 1000) 150 } 151 152 build() { 153 Row() { 154 Column(){ 155 Text(this.overlayColor) 156 .fontSize(40) 157 .fontWeight(FontWeight.Bold) 158 } 159 .width('100%') 160 } 161 .height('100%') 162 .overlay(this.overlayNode) 163 } 164} 165``` 166 167
