1# Popup Control 2 3You can bind a popup to a component, specifying its content, interaction logic, and visibility. 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> - The visibility of the popup is returned through the **onStateChange** event callback. There is no strong mapping between the visibility and the creation or destruction of the component. 10 11## bindPopup 12 13bindPopup(show: boolean, popup: PopupOptions | CustomPopupOptions) 14 15Binds a popup to the component. 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| show | boolean | Yes | Whether to show the popup. The default value is **false**, indicating that the popup is hidden. The popup can be displayed only after the entire page is fully constructed. Therefore, to avoid incorrect display positions and shapes, do not set this parameter to **true** while the page is still being constructed. Since API version 13, this parameter supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).| 26| popup | [PopupOptions](#popupoptions) \| [CustomPopupOptions](#custompopupoptions8)<sup>8+</sup> | Yes | Parameters of the popup. | 27 28## PopupOptions 29 30| Name | Type | Mandatory| Description | 31| ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 32| message | string | Yes | Content of the popup message.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 33| placementOnTop<sup>(deprecated)</sup> | boolean | No | Whether to display the popup above the component. The default value is **false**.<br>**NOTE**<br>This API is deprecated since API version 10. You are advised to use **placement** instead.| 34| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 35| 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.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 36| onStateChange | (event: { isVisible: boolean }) => void | No | Callback for the popup status change event. The parameter **isVisible** indicates whether the popup is visible.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 37| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup. 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. 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. 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.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| showInSubWindow<sup>9+</sup> | boolean | No | Whether to show the popup in the subwindow. The **value** true means to show the popup in the subwindow, and **false** means to show the popup in the main window.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 39| mask<sup>10+</sup> | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| No | Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a color value means to apply a mask in the corresponding color to the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 40| messageOptions<sup>10+</sup> | [PopupMessageOptions](#popupmessageoptions10) | No | Parameters of the popup message.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 41| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | No | Space between the popup and the target.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 42| placement<sup>10+</sup> | [Placement](ts-appendix-enums.md#placement8) | No | Position of the popup relative to the target. The default value is **Placement.Bottom**.<br>If both **placementOnTop** and **placement** are set, the latter prevails.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 43| offset<sup>10+</sup> | [Position](ts-types.md#position) | No | Offset of the popup relative to the display position specified by **placement**.<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 44| enableArrow<sup>10+</sup> | boolean | No | Whether to display the arrow.<br>Default value: **true**<br>**NOTE**<br>If the available space on the screen is insufficient, the popup will cover part of the component and the arrow will not be displayed.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 45| popupColor<sup>11+</sup> | [Color](ts-appendix-enums.md#color) \| string \| number \| [Resource](ts-types.md#resource) | No | Color of the popup. To remove the background blur, set **backgroundBlurStyle** to **BlurStyle.NONE**.<br>Default value: [TRANSPARENT](ts-appendix-enums.md#color) plus[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 46| autoCancel<sup>11+</sup> | boolean | No | Whether to automatically dismiss the popup when an operation is performed on the page.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 47| width<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Width of the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 48| arrowPointPosition<sup>11+</sup> | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No | Position of the popup arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. All these positions are within the parent component area.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 49| arrowWidth<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow thickness. If the arrow thickness exceeds the length of the edge minus twice the size of the popup rounded corner, the arrow is not drawn.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 50| arrowHeight<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow height.<br>Default value: **8**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 51| radius<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Rounded corner radius of the popup.<br>Default value: **20**<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 52| shadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | Popup shadow.<br>Default value: **ShadowStyle.OUTER_DEFAULT_MD**<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 53| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the popup.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 54| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the popup.<br>**NOTE**<br>1. If this parameter is not set, the default effect is used.<br>2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.<br>3. Touching the Back button during the exit animation does not affect the animation playback. The Back button does not respond.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 55| onWillDismiss<sup>12+</sup> | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12))> | No | Whether to perform dismissal event interception and interception callback. The default value is **true**.<br>1. If this parameter is set to **false**, the system does not respond to the dismissal event initiated by touching the Back button, swiping left or right on the screen, or pressing the Esc key; and the system dismisses the popup only when **show** is set to **false**. If this parameter is set to **true**, the system responds to the dismissal event as expected.<br>2. If this parameter is set to a function, the dismissal event is intercepted and the callback function is executed.<br>**NOTE**<br>No more **onWillDismiss** callback is allowed in an **onWillDismiss** callback.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| followTransformOfTarget<sup>13+</sup> | boolean | No | Whether the popup adjusts its position to follow transformations (like rotation or scaling) applied to its host component or the host component's parent container.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 57| keyboardAvoidMode<sup>15+</sup> | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12) | No | Whether to avoid the soft keyboard. By default, the popup does not avoid the soft keyboard. When configured to avoid the soft keyboard, if the popup display space is insufficient, the display mode of the popup changes from being centered over the parent component to being translated and covering the parent component.. In addition, if the popup arrow does not point to the host, the arrow will not be displayed.<br>Default value: **KeyboardAvoidMode.NONE**<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 58| enableHoverMode<sup>18+</sup>| boolean | No | Whether to enable the hover mode. If the click position of the popup component is in the crease area in the hover state, the popup component does not respond to the hover state. Default value: **false**, indicating that the popup does not respond in hover mode<br>**NOTE**<br>The menu responds in hover mode when **enableHoverMode** is set to **true** and does not when **enableHoverMode** is set to **false** or an invalid value or is not set at all.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 59 60## PopupMessageOptions<sup>10+</sup> 61 62**Atomic service API**: This API can be used in atomic services since API version 11. 63 64**System capability**: SystemCapability.ArkUI.ArkUI.Full 65 66| Name | Type | Mandatory|Description | 67| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 68| textColor | [ResourceColor](ts-types.md#resourcecolor) | No | Text color of the popup message. | 69| font | [Font](ts-types.md#font) | No | Font settings of the popup message.<br>**NOTE**<br>Setting **family** is not supported.| 70 71## DismissPopupAction<sup>12+</sup> 72 73**Atomic service API**: This API can be used in atomic services since API version 12. 74 75**System capability**: SystemCapability.ArkUI.ArkUI.Full 76 77| Name | Type | Mandatory| Description | 78| ------- | ----------------------------------------- | ---- | --------------------------------------------------------------- | 79| dismiss | function | Yes | Callback for dismissing the popup. This API is called only when the popup needs to be exited.| 80| reason | [DismissReason](#dismissreason12)| Yes | Reason why the popup cannot be dismissed. | 81 82## DismissReason<sup>12+</sup> 83 84**System capability**: SystemCapability.ArkUI.ArkUI.Full 85 86| Name | Description | 87| ------------- | ------------------ | 88| PRESS_BACK | Touching the Back button. | 89| TOUCH_OUTSIDE | Touching anywhere outside of the popup.| 90 91## CustomPopupOptions<sup>8+</sup> 92 93**System capability**: SystemCapability.ArkUI.ArkUI.Full 94 95| Name | Type | Mandatory | Description | 96| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 97| 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 in the builder. If the **position** attribute is used, the popup will not be displayed. If a custom component is used in the builder, the **aboutToAppear** and **aboutToDisappear** lifecycle callbacks of the custom component are irrelevant to the visibility of the popup. As such, the lifecycle of the custom component cannot be used to determine whether the popup is displayed or not.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 98| 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**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 99| popupColor | number \| [Color](ts-types.md#color) \| string \| [Resource](ts-types.md#resource) | No | Color of the popup. To remove the background blur, set **backgroundBlurStyle** to **BlurStyle.NONE**.<br>The default value varies by API version.<br>API version 10: **'#4d4d4d'**<br>API version 11 and later: [TRANSPARENT](ts-appendix-enums.md#color) plus [COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 100| 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**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 101| autoCancel | boolean | No | Whether to automatically dismiss the popup when an operation is performed on the page.<br>Default value: **true**<br>**NOTE**<br>To enable the popup to disappear upon a click on it, place a layout component in the builder, place the **\<Popup>** component in the layout component, and modify the value of the **bindPopup** variable (show: boolean) in the **onClick** event of the layout component.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 102| onStateChange | (event: { isVisible: boolean }) => void | No | Callback for the popup status change event. The parameter **isVisible** indicates whether the popup is visible.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 103| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup. 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. 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. 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.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 104| showInSubWindow<sup>9+</sup> | boolean | No | Whether to show the popup in the subwindow. The value **true** means to show the popup in the subwindow, and **false** means to show the popup in the main window.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 105| maskColor<sup>(deprecated)</sup> | [Resource](ts-types.md#resource) \| string \| number \| [Color](ts-types.md#color) | No | Color of the popup mask.<br>**NOTE**<br>This parameter is deprecated since API version 10. You are advised to use **mask** instead.| 106| mask<sup>10+</sup> | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| No | Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a color value means to apply a mask in the corresponding color to the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 107| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | No | Space between the popup and the target.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 108| offset<sup>10+</sup> | [Position](ts-types.md#position) | No | Offset of the popup relative to the display position specified by **placement**.<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 109| width<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No| Width of the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 110| arrowPointPosition<sup>11+</sup> | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No| Position of the popup arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. All these positions are within the parent component area.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 111| arrowWidth<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow thickness. If the arrow thickness exceeds the length of the edge minus twice the size of the popup rounded corner, the arrow is not drawn.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 112| arrowHeight<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow height.<br>Default value: **8**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 113| radius<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Rounded corner radius of the popup.<br>Default value: **20**<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 114| shadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | Popup shadow.<br>Default value: **ShadowStyle.OUTER_DEFAULT_MD**<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 115| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the popup.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 116| focusable<sup>11+</sup> | boolean | No| Whether the popup obtains focus when displayed.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 117| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the popup.<br>**NOTE**<br>1. If this parameter is not set, the default effect is used.<br>2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.<br>3. Touching the Back button during the exit animation does not affect the animation playback. The Back button does not respond.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 118| onWillDismiss<sup>12+</sup> | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12))> | No | Whether to perform dismissal event interception and interception callback. The default value is **true**.<br>1. If this parameter is set to **false**, the system does not respond to the dismissal event initiated by touching the Back button, swiping left or right on the screen, or pressing the Esc key; and the system dismisses the popup only when **show** is set to **false**. If this parameter is set to **true**, the system responds to the dismissal event as expected.<br>2. If this parameter is set to a function, the dismissal event is intercepted and the callback function is executed.<br>**NOTE**<br>No more **onWillDismiss** callback is allowed in an **onWillDismiss** callback.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 119| followTransformOfTarget<sup>13+</sup> | boolean | No | Whether the popup adjusts its position to follow transformations (like rotation or scaling) applied to its host component or the host component's parent container.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 120| keyboardAvoidMode<sup>15+</sup> | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12) | No | Whether to avoid the soft keyboard. By default, the popup does not avoid the soft keyboard. When configured to avoid the soft keyboard, if the popup display space is insufficient, the display mode of the popup changes from being centered over the parent component to being translated and covering the parent component.. In addition, if the popup arrow does not point to the host, the arrow will not be displayed.<br>Default value: **KeyboardAvoidMode.NONE**<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 121|enableHoverMode<sup>18+</sup> | boolean | No | Whether to enable the hover mode. If the click position of the popup component is in the crease area in the hover state, the popup component does not respond to the hover state. Default value: **false**, indicating that the popup does not respond in hover mode<br>**NOTE**<br>The popup responds in hover mode when **enableHoverMode** is set to **true** and does not when **enableHoverMode** is set to **false** or an invalid value or is not set at all.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 122 123## PopupCommonOptions<sup>18+</sup> 124 125Parameters of the popup. Use the [getPromptAction()](../js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext) to obtain a [PromptAction](../js-apis-arkui-UIContext.md#promptaction) object. Then, use this object to call [openPopup](../js-apis-arkui-UIContext.md#openpopup18) and [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18), where the properties of the **options** parameter are defined as follows. 126 127**Atomic service API**: This API can be used in atomic services since API version 18. 128 129**System capability**: SystemCapability.ArkUI.ArkUI.Full 130 131| Name | Type | Mandatory | Description | 132| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 133| 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**| 134| popupColor | number \| [Color](ts-types.md#color) \| string \| [Resource](ts-types.md#resource) | No | Color of the popup. To remove the background blur, set **backgroundBlurStyle** to **BlurStyle.NONE**. Default value: [TRANSPARENT](ts-appendix-enums.md#color) plus[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)| 135| enableArrow | boolean | No | Whether to display an arrow.<br>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**| 136| autoCancel | boolean | No | Whether to automatically dismiss the popup when an operation is performed on the page.<br>Default value: **true**| 137| onStateChange | [PopupStateChangeCallback](#popupstatechangecallback18) | No | Callback invoked when the popup state changes.<br>**NOTE**<br>The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 138| arrowOffset | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup. 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. 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. 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.| 139| showInSubWindow | boolean | No | Whether to show the popup in the subwindow. The value true means to show the popup in the subwindow, and false means to show the popup in the main window.<br>Default value: **false**<br>**NOTE**<br>The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 140| mask | boolean \| [PopupMaskType](#popupmasktype18) | No | Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a color value means to apply a mask in the corresponding color to the popup.| 141| targetSpace | [Length](ts-types.md#length) | No | Space between the popup and the target.| 142| offset | [Position](ts-types.md#position) | No | Offset of the popup relative to the display position specified by **placement**.<br>**NOTE**<br>This parameter cannot be set in percentage.| 143| width | [Dimension](ts-types.md#dimension10) | No| Width of the popup.| 144| arrowPointPosition | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No| Position of the popup arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. All these positions are within the parent component area.| 145| arrowWidth | [Dimension](ts-types.md#dimension10) | No | Arrow thickness. If the arrow thickness exceeds the length of the edge minus twice the size of the popup rounded corner, the arrow is not drawn.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.| 146| arrowHeight | [Dimension](ts-types.md#dimension10) | No | Arrow height.<br>Default value: **8**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.| 147| radius | [Dimension](ts-types.md#dimension10) | No | Rounded corner radius of the popup.<br>Default value: **20**<br>Unit: vp| 148| shadow | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | Popup shadow.<br>Default value: **ShadowStyle.OUTER_DEFAULT_MD**| 149| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the popup.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**| 150| focusable | boolean | No| Whether the popup obtains focus when displayed.<br>Default value: **false**<br>**NOTE**<br>The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 151| transition | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the popup.<br>**NOTE**<br>1. If this parameter is not set, the default effect is used.<br>2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.<br>3. Touching the Back button during the exit animation does not affect the animation playback. The Back button does not respond.<br>4. The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 152| onWillDismiss | boolean\|Callback<[DismissPopupAction](#dismisspopupaction12)> | No | Whether to perform dismissal event interception and interception callback. The default value is **true**.<br>1. If this parameter is set to **false**, the system does not respond to the dismissal event initiated by touching the Back button, swiping left or right on the screen, or pressing the Esc key; and the system dismisses the popup only when **show** is set to **false**. If this parameter is set to **true**, the system responds to the dismissal event as expected.<br>2. If this parameter is set to a function, the dismissal event is intercepted and the callback function is executed.<br>**NOTE**<br>1. Nesting **onWillDismiss** callbacks is not allowed.<br>2. The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 153| followTransformOfTarget | boolean | No | Whether the popup adjusts its position to follow transformations (like rotation or scaling) applied to its host component or the host component's parent container.<br>Default value: **false**| 154 155## PopupStateChangeParam<sup>18+</sup> 156 157Describes the display state of a popup. 158 159**Atomic service API**: This API can be used in atomic services since API version 18. 160 161**System capability**: SystemCapability.ArkUI.ArkUI.Full 162 163| Name | Type | Mandatory| Description | 164| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 165| isVisible | boolean | Yes | Display state of the popup. | 166 167## PopupStateChangeCallback<sup>18+</sup> 168 169Represents the callback invoked when the popup state changes. 170 171type PopupStateChangeCallback = (event: PopupStateChangeParam) => void; 172 173**Atomic service API**: This API can be used in atomic services since API version 18. 174 175**System capability**: SystemCapability.ArkUI.ArkUI.Full 176 177**Parameters** 178 179| Name | Type | Mandatory| Description | 180| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 181| event | [PopupStateChangeParam](#popupstatechangeparam18) | Yes | Display state of the popup. | 182 183**Return value** 184 185| Type | Description | 186| ---------------------------------------- | ------- | 187| void | Callback invoked when the popup state changes.| 188 189## PopupMaskType<sup>18+</sup> 190 191Describes the color of the mask. 192 193**Atomic service API**: This API can be used in atomic services since API version 18. 194 195**System capability**: SystemCapability.ArkUI.ArkUI.Full 196 197| Name | Type | Mandatory| Description | 198| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 199| color | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the mask. | 200 201## Example 202 203### Example 1: Displaying Different Types of Popups 204 205This example showcases how to use the **bindPopup** API to configure and display popups of PopupOptions and CustomPopupOptions types. 206 207```ts 208// xxx.ets 209@Entry 210@Component 211struct PopupExample { 212 @State handlePopup: boolean = false 213 @State customPopup: boolean = false 214 215 // Popup builder 216 @Builder popupBuilder() { 217 Row({ space: 2 }) { 218 Image($r("app.media.icon")).width(24).height(24).margin({ left: -5 }) 219 Text('Custom Popup').fontSize(10) 220 }.width(100).height(50).padding(5) 221 } 222 223 build() { 224 Flex({ direction: FlexDirection.Column }) { 225 // PopupOptions for setting the popup 226 Button('PopupOptions') 227 .onClick(() => { 228 this.handlePopup = !this.handlePopup 229 }) 230 .bindPopup(this.handlePopup, { 231 message: 'This is a popup with PopupOptions', 232 placementOnTop: true, 233 showInSubWindow:false, 234 // Set the popup to avoid the soft keyboard. 235 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, 236 primaryButton: { 237 value: 'confirm', 238 action: () => { 239 this.handlePopup = !this.handlePopup 240 console.info('confirm Button click') 241 } 242 }, 243 // Secondary button 244 secondaryButton: { 245 value: 'cancel', 246 action: () => { 247 this.handlePopup = !this.handlePopup 248 console.info('cancel Button click') 249 } 250 }, 251 onStateChange: (e) => { 252 console.info(JSON.stringify(e.isVisible)) 253 if (!e.isVisible) { 254 this.handlePopup = false 255 } 256 } 257 }) 258 .position({ x: 100, y: 150 }) 259 260 261 // CustomPopupOptions for setting the popup 262 Button('CustomPopupOptions') 263 .onClick(() => { 264 this.customPopup = !this.customPopup 265 }) 266 .bindPopup(this.customPopup, { 267 builder: this.popupBuilder, 268 placement: Placement.Top, 269 mask: {color:'#33000000'}, 270 popupColor: Color.Yellow, 271 enableArrow: true, 272 // Set the popup to avoid the soft keyboard. 273 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, 274 showInSubWindow: false, 275 onStateChange: (e) => { 276 if (!e.isVisible) { 277 this.customPopup = false 278 } 279 } 280 }) 281 .position({ x: 80, y: 300 }) 282 }.width('100%').padding({ top: 5 }) 283 } 284} 285``` 286 287 288 289### Example 2: Setting the Popup Text Style 290 291This example shows how to use the **bindPopup** API to display a popup with custom **messageOptions** settings. 292 293```ts 294// xxx.ets 295 296@Entry 297@Component 298struct PopupExample { 299 @State handlePopup: boolean = false 300 301 build() { 302 Column({ space: 100 }) { 303 Button('PopupOptions').margin(100) 304 .onClick(() => { 305 this.handlePopup = !this.handlePopup 306 }) 307 .bindPopup(this.handlePopup, { 308 // Popup of the PopupOptions type 309 message: 'This is a popup with PopupOptions', 310 messageOptions: { 311 // Text style of the popup 312 textColor: Color.Red, 313 font: { 314 size: '14vp', 315 style: FontStyle.Italic, 316 weight: FontWeight.Bolder 317 } 318 }, 319 placement: Placement.Bottom, 320 enableArrow: false, // Set the arrow not to display. 321 targetSpace: '15vp', 322 onStateChange: (e) => { 323 console.info(JSON.stringify(e.isVisible)) 324 if (!e.isVisible) { 325 this.handlePopup = false 326 } 327 } 328 }) 329 }.margin(20) 330 } 331} 332``` 333 334 335 336### Example 3: Setting the Popup Style 337 338This example demonstrates how to use the **bindPopup** API with properties like **arrowHeight**, **arrowWidth**, **radius**, **shadow**, and **popupColor** to set the styles for both the popup's arrow and the popup itself. 339 340```ts 341// xxx.ets 342 343@Entry 344@Component 345struct PopupExample { 346 @State customPopup: boolean = false 347 @State handlePopup: boolean = false 348 349 build() { 350 Column({ space: 100 }) { 351 Button("popup") 352 .margin({ top: 50 }) 353 .onClick(() => { 354 this.customPopup = !this.customPopup 355 }) 356 .bindPopup(this.customPopup, { 357 message: "this is a popup", 358 arrowHeight: 20, // Set the height for the popup arrow. 359 arrowWidth: 20, // Set the width for the popup arrow. 360 radius: 20, // Set the corner radius of the popup. 361 shadow: ShadowStyle.OUTER_DEFAULT_XS, // Set the shadow for the popup. 362 }) 363 364 Button('PopupOptions') 365 .onClick(() => { 366 this.handlePopup = !this.handlePopup 367 }) 368 .bindPopup(this.handlePopup, { 369 width: 300, 370 message: 'This is a popup with PopupOptions', 371 arrowPointPosition: ArrowPointPosition.START, // Set the position for the popup arrow. 372 backgroundBlurStyle: BlurStyle.NONE, // Disable the background blur for the popup. 373 popupColor: Color.Red, // Set the background color for the popup. 374 autoCancel: true, 375 }) 376 } 377 .width('100%') 378 } 379} 380``` 381 382 383 384### Example 4: Setting the Popup Animation 385 386In this example, the **bindPopup** API is used with the **transition** property to implement animations for displaying and dismissing popups. 387 388```ts 389// xxx.ets 390@Entry 391@Component 392struct PopupExample { 393 @State handlePopup: boolean = false 394 @State customPopup: boolean = false 395 396 // Popup builder 397 @Builder popupBuilder() { 398 Row() { 399 Text('Custom Popup with transitionEffect').fontSize(10) 400 }.height(50).padding(5) 401 } 402 403 build() { 404 Flex({ direction: FlexDirection.Column }) { 405 // PopupOptions for setting the popup 406 Button('PopupOptions') 407 .onClick(() => { 408 this.handlePopup = !this.handlePopup 409 }) 410 .bindPopup(this.handlePopup, { 411 message: 'This is a popup with transitionEffect', 412 placementOnTop: true, 413 showInSubWindow: false, 414 onStateChange: (e) => { 415 console.info(JSON.stringify(e.isVisible)) 416 if (!e.isVisible) { 417 this.handlePopup = false 418 } 419 }, 420 // Set the popup animation to a combination of opacity and translation effects, with no exit animation. 421 transition:TransitionEffect.asymmetric( 422 TransitionEffect.OPACITY.animation({ duration: 1000, curve: Curve.Ease }).combine( 423 TransitionEffect.translate({ x: 50, y: 50 })), 424 TransitionEffect.IDENTITY) 425 }) 426 .position({ x: 100, y: 150 }) 427 428 // CustomPopupOptions for setting the popup 429 Button('CustomPopupOptions') 430 .onClick(() => { 431 this.customPopup = !this.customPopup 432 }) 433 .bindPopup(this.customPopup, { 434 builder: this.popupBuilder, 435 placement: Placement.Top, 436 showInSubWindow: false, 437 onStateChange: (e) => { 438 if (!e.isVisible) { 439 this.customPopup = false 440 } 441 }, 442 // Set the popup entrance and exit animations to be a scaling effect. 443 transition:TransitionEffect.scale({ x: 1, y: 0 }).animation({ duration: 500, curve: Curve.Ease }) 444 }) 445 .position({ x: 80, y: 300 }) 446 }.width('100%').padding({ top: 5 }) 447 } 448} 449``` 450 451 452 453### Example 5: Adding an Event to a Popup 454 455This example uses the **bindPopup** API with the **onWillDismiss** property to intercept the dismissal event when a popup is about to be dismissed and execute a callback function. 456 457```ts 458// xxx.ets 459 460@Entry 461@Component 462struct PopupExample { 463 @State handlePopup: boolean = false 464 build() { 465 Column() { 466 Button('PopupOptions') 467 .onClick(() => { 468 this.handlePopup = true 469 }) 470 .bindPopup(this.handlePopup, { 471 message: 'This is a popup with PopupOptions', 472 messageOptions: { 473 textColor: Color.Red, 474 font: { 475 size: '14vp', 476 style: FontStyle.Italic, 477 weight: FontWeight.Bolder 478 } 479 }, 480 placement: Placement.Bottom, 481 enableArrow: false, 482 targetSpace: '15vp', 483 onStateChange: (e) => { 484 if (!e.isVisible) { 485 this.handlePopup = false 486 } 487 }, 488 onWillDismiss: ( 489 (dismissPopupAction: DismissPopupAction) => { 490 console.info("dismissReason:" + JSON.stringify(dismissPopupAction.reason)) 491 if (dismissPopupAction.reason == DismissReason.PRESS_BACK) { 492 dismissPopupAction.dismiss() 493 } 494 } 495 ) 496 }) 497 }.margin(20) 498 } 499} 500``` 501 502 503 504### Example 6: Intercepting the Popup Dismissal Event 505 506In this example, the **onWillDismiss** property is set to **false** to intercept the dismissal event of the popup. 507 508```ts 509// xxx.ets 510 511@Entry 512@Component 513struct PopupExample { 514 @State handlePopup: boolean = false 515 build() { 516 Column() { 517 Button('PopupOptions') 518 .onClick(() => { 519 this.handlePopup = true 520 }) 521 .bindPopup(this.handlePopup, { 522 message: 'This is a popup with PopupOptions', 523 messageOptions: { 524 textColor: Color.Red, 525 font: { 526 size: '14vp', 527 style: FontStyle.Italic, 528 weight: FontWeight.Bolder 529 } 530 }, 531 placement: Placement.Bottom, 532 enableArrow: false, 533 targetSpace: '15vp', 534 followTransformOfTarget: true, 535 onStateChange: (e) => { 536 let timer = setTimeout(()=>{this.handlePopup = false},6000) 537 if (!e.isVisible) { 538 this.handlePopup = false 539 clearTimeout(timer) 540 } 541 }, 542 onWillDismiss: false 543 }) 544 }.margin(20) 545 } 546} 547``` 548 549 550
