1# Popup Control 2 3You can bind a popup to a component, specifying its content, interaction logic, and display status. 4 5> **NOTE** 6> 7> This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## APIs 11 12 13| Name | Type | Description | 14| --------- | ---------------------------------------- | ---------------------------------------- | 15| bindPopup | show: boolean,<br>popup: [PopupOptions](#popupoptions) \| [CustomPopupOptions](#custompopupoptions8)<sup>8+</sup> | Binds a popup to the component.<br>**show**: whether to show the popup. The default value is **false**, indicating that the popup is hidden. As the popup can be displayed only after building of all pages is completed, **show** cannot be set to **true** during page building. Otherwise, the display position and shape of the popup will be incorrect.<br>**popup**: parameters of the popup.| 16 17## PopupOptions 18 19| Name | Type | Mandatory| Description | 20| ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 21| message | string | Yes | Content of the popup message. | 22| placementOnTop | boolean | No | Whether to display the popup above the component.<br>Default value: **false** | 23| primaryButton | {<br>value: string,<br>action: () => void<br>} | No | Primary button.<br>**value**: text of the primary button in the popup.<br>**action**: callback for clicking the primary button.| 24| secondaryButton | {<br>value: string,<br>action: () => void<br>} | No | Secondary button.<br>**value**: text of the secondary button in the popup.<br>**action**: callback for clicking the secondary button.| 25| onStateChange | (event: { isVisible: boolean }) => void | No | Callback for the popup status change event.<br>**isVisible**: whether the popup is visible. | 26| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup.<br>When the arrow is at the top or bottom of the popup: The value **0** indicates that the arrow is located on the leftmost, and any other value indicates the distance from the arrow to the leftmost; the arrow is centered by default.<br>When the arrow is on the left or right side of the popup: The value indicates the distance from the arrow to the top; the arrow is centered by default.<br/>When the popup is displayed on either edge of the screen, it will automatically deviate leftward or rightward to stay within the safe area. When the value is **0**, the arrow always points to the bound component. | 27| showInSubWindow<sup>9+</sup> | boolean | No | Whether to show the popup in the subwindow.<br/>Default value: **false** | 28 29## CustomPopupOptions<sup>8+</sup> 30 31| Name | Type | Mandatory | Description | 32| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 33| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Popup builder.<br>**NOTE**<br>The **popup** attribute is a universal attribute. A custom popup does not support display of another popup. The **position** attribute cannot be used for the first-layer container under the builder. If the **position** attribute is used, the popup will not be displayed. | 34| placement | [Placement](ts-appendix-enums.md#placement8) | No | Preferred position of the popup. If the set position is insufficient for holding the popup, it will be automatically adjusted.<br>Default value: **Placement.Bottom**| 35| popupColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the popup. | 36| enableArrow | boolean | No | Whether to display an arrow.<br>Since API version 9, if the position set for the popup is not large enough, the arrow will not be displayed. For example, if **placement** is set to **Left**, but the popup height (80 vp) is less than the sum of the arrow width (32 vp) and diameter of popup rounded corner (48 vp), the arrow will not be displayed.<br>Default value: **true**| 37| autoCancel | boolean | No | Whether to automatically close the popup when an operation is performed on the page.<br>Default value: **true** | 38| onStateChange | (event: { isVisible: boolean }) => void | No | Callback for the popup status change event.<br>**isVisible**: whether the popup is visible. | 39| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup.<br>When the arrow is at the top or bottom of the popup: The value **0** indicates that the arrow is located on the leftmost, and any other value indicates the distance from the arrow to the leftmost; the arrow is centered by default.<br/>When the arrow is on the left or right side of the popup: The value indicates the distance from the arrow to the top; the arrow is centered by default.<br/>When the popup is displayed on either edge of the screen, it will automatically deviate leftward or rightward to stay within the safe area. When the value is **0**, the arrow always points to the bound component. | 40| showInSubWindow<sup>9+</sup> | boolean | No | Whether to show the popup in the subwindow.<br/>Default value: **false** | 41 42## Example 43```ts 44// xxx.ets 45@Entry 46@Component 47struct PopupExample { 48 @State handlePopup: boolean = false 49 @State customPopup: boolean = false 50 51 // Popup builder 52 @Builder popupBuilder() { 53 Row({ space: 2 }) { 54 Image($r("app.media.image")).width(24).height(24).margin({ left: -5 }) 55 Text('Custom Popup').fontSize(10) 56 }.width(100).height(50).padding(5) 57 } 58 59 build() { 60 Flex({ direction: FlexDirection.Column }) { 61 // PopupOptions for setting the popup 62 Button('PopupOptions') 63 .onClick(() => { 64 this.handlePopup = !this.handlePopup 65 }) 66 .bindPopup(this.handlePopup, { 67 message: 'This is a popup with PopupOptions', 68 placementOnTop: true, 69 showInSubWindow:false, 70 primaryButton: { 71 value: 'confirm', 72 action: () => { 73 this.handlePopup = !this.handlePopup 74 console.info('confirm Button click') 75 } 76 }, 77 // Secondary button 78 secondaryButton: { 79 value: 'cancel', 80 action: () => { 81 this.handlePopup = !this.handlePopup 82 console.info('cancel Button click') 83 } 84 }, 85 onStateChange: (e) => { 86 console.info(JSON.stringify(e.isVisible)) 87 if (!e.isVisible) { 88 this.handlePopup = false 89 } 90 } 91 }) 92 .position({ x: 100, y: 50 }) 93 94 95 // CustomPopupOptions for setting the popup 96 Button('CustomPopupOptions') 97 .onClick(() => { 98 this.customPopup = !this.customPopup 99 }) 100 .bindPopup(this.customPopup, { 101 builder: this.popupBuilder, 102 placement: Placement.Top, 103 mask: {color:'0x33000000'}, 104 popupColor: Color.Yellow, 105 enableArrow: true, 106 showInSubWindow: false, 107 onStateChange: (e) => { 108 if (!e.isVisible) { 109 this.customPopup = false 110 } 111 } 112 }) 113 .position({ x: 80, y: 200 }) 114 }.width('100%').padding({ top: 5 }) 115 } 116} 117``` 118 119 120
