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.<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. | 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 is less than twice the arrow width (64 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 43## Example 44```ts 45// xxx.ets 46@Entry 47@Component 48struct PopupExample { 49 @State handlePopup: boolean = false 50 @State customPopup: boolean = false 51 52 // Popup builder 53 @Builder popupBuilder() { 54 Row({ space: 2 }) { 55 Image($r("app.media.image")).width(24).height(24).margin({ left: -5 }) 56 Text('Custom Popup').fontSize(10) 57 }.width(100).height(50).padding(5) 58 } 59 60 build() { 61 Flex({ direction: FlexDirection.Column }) { 62 // PopupOptions for setting the popup 63 Button('PopupOptions') 64 .onClick(() => { 65 this.handlePopup = !this.handlePopup 66 }) 67 .bindPopup(this.handlePopup, { 68 message: 'This is a popup with PopupOptions', 69 placementOnTop: true, 70 showInSubWindow:false, 71 primaryButton: { 72 value: 'confirm', 73 action: () => { 74 this.handlePopup = !this.handlePopup 75 console.info('confirm Button click') 76 } 77 }, 78 // Secondary button 79 secondaryButton: { 80 value: 'cancel', 81 action: () => { 82 this.handlePopup = !this.handlePopup 83 console.info('cancel Button click') 84 } 85 }, 86 onStateChange: (e) => { 87 console.info(JSON.stringify(e.isVisible)) 88 if (!e.isVisible) { 89 this.handlePopup = false 90 } 91 } 92 }) 93 .position({ x: 100, y: 50 }) 94 95 96 // CustomPopupOptions for setting the popup 97 Button('CustomPopupOptions') 98 .onClick(() => { 99 this.customPopup = !this.customPopup 100 }) 101 .bindPopup(this.customPopup, { 102 builder: this.popupBuilder, 103 placement: Placement.Top, 104 mask: {color: 0x33000000}, 105 popupColor: Color.Yellow, 106 enableArrow: true, 107 showInSubWindow: false, 108 onStateChange: (e) => { 109 if (!e.isVisible) { 110 this.customPopup = false 111 } 112 } 113 }) 114 .position({ x: 80, y: 200 }) 115 }.width('100%').padding({ top: 5 }) 116 } 117} 118``` 119 120 121
