# Popup控制 给组件绑定Popup弹窗，并设置弹窗内容，交互逻辑和显示状态。 > **说明：** > > - 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 > > - Popup弹窗的显示状态在onStateChange事件回调中反馈，其显隐与组件的创建或销毁无强对应关系。 ## bindPopup bindPopup(show: boolean, popup: PopupOptions | CustomPopupOptions) 给组件绑定Popup弹窗。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | show | boolean | 是 | 弹窗显示状态，默认值为false，隐藏弹窗。Popup弹窗必须等待页面全部构建完成才能展示，因此show不能在页面构建中设置为true，否则会导致Popup弹窗显示位置及形状错误。该参数从API version 13开始支持[!!语法](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。 | | popup | [PopupOptions](#popupoptions类型说明) \| [CustomPopupOptions](#custompopupoptions8类型说明)8+ | 是 | 配置弹出弹窗的参数。 | ## PopupOptions类型说明 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | message | string | 是 | 弹窗信息内容。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | placementOnTop(deprecated) | boolean | 否 | 是否在组件上方显示，默认值为false。
**说明：**
从 API version 10 开始废弃，建议使用`placement`替代。 | | primaryButton | {
value: string,
action: () => void
} | 否 | 第一个按钮。
value：弹窗里主按钮的文本。
action：点击主按钮的回调函数。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | secondaryButton | {
value: string,
action: () => void
} | 否 | 第二个按钮。
value：弹窗里辅助按钮的文本。
action：点击辅助按钮的回调函数。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | onStateChange | (event: { isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数isVisible为弹窗当前的显示状态。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | arrowOffset9+ | [Length](ts-types.md#length) | 否 | Popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | showInSubWindow9+ | boolean | 否 | 取值为true时，气泡会显示在创建的子窗里，取值为false时，气泡会显示在对应的主窗中。
默认值：false
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | mask10+ | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为Color，则为遮罩层的颜色。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | messageOptions10+ | [PopupMessageOptions](#popupmessageoptions10类型说明) | 否 | 设置弹窗信息文本参数。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | targetSpace10+ | [Length](ts-types.md#length) | 否 | 设置Popup与目标的间隙。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | placement10+ | [Placement](ts-appendix-enums.md#placement8) | 否 | 设置Popup组件相对于目标的显示位置，默认值为Placement.Bottom。
如果同时设置了`placementOnTop`和`placement`，则以`placement`的设置生效。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | offset10+ | [Position](ts-types.md#position) | 否 | 设置Popup组件相对于placement设置的显示位置的偏移。
**说明：**
不支持设置百分比。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | enableArrow10+ | boolean | 否 | 设置是否显示箭头。
默认值：true
**说明：**
当页面可用空间无法让气泡完全避让时，气泡会覆盖到组件上并且不显示箭头。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | popupColor11+ | [Color](ts-appendix-enums.md#color)  \| string \| number  \|  [Resource](ts-types.md#resource) | 否 | 提示气泡的颜色。如需去除模糊背景填充效果，需将backgroundBlurStyle设置为BlurStyle.NONE。
默认值：透明色[TRANSPARENT](ts-appendix-enums.md#color)加模糊背景填充效果[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | autoCancel11+ | boolean | 否 | 页面有操作时，是否自动关闭气泡。
默认值：true
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | width11+ | [Dimension](ts-types.md#dimension10) | 否 | 弹窗宽度。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | arrowPointPosition11+ | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | 否 | 气泡尖角相对于父组件显示位置，气泡尖角在垂直和水平方向上有 ”Start“、”Center“、”End“三个位置点可选。以上所有位置点均位于父组件区域的范围内，不会超出父组件的边界范围。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | arrowWidth11+ | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小，则不绘制气泡箭头。
默认值：16
单位：vp
**说明：**
不支持设置百分比。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | arrowHeight11+ | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头高度。
默认值：8
单位：vp
**说明：**
不支持设置百分比。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | radius11+ | [Dimension](ts-types.md#dimension10) | 否 | 设置气泡圆角半径。
默认值：20
单位：vp
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | shadow11+ | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置气泡阴影。
默认值：ShadowStyle.OUTER_DEFAULT_MD
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | backgroundBlurStyle11+ | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 设置气泡模糊背景参数。
默认值：BlurStyle.COMPONENT_ULTRA_THICK
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | transition12+ | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 自定义设置Popup弹窗显示和退出的动画效果。
**说明：**
1.如果不设置，则使用默认的显示/退出动效。
2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。
3.退出动效中按back键，不会打断退出动效，退出动效继续执行，back键不被响应。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| | onWillDismiss12+ | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12类型说明))> | 否 | 设置Popup交互式关闭拦截开关及拦截回调函数，默认值为true，Popup响应点击、左滑/右滑、三键back。
1.当为boolean类型时，如果设置为false，则不响应点击、左滑/右滑、三键back或键盘ESC退出事件，仅当设置“弹窗显示状态”参数show值为false时才退出；如果设置为true，则正常响应退出事件；
2.如果设置为函数类型，则拦截退出事件且执行回调函数。
**说明：**
在onWillDismiss回调中，不能再做onWillDismiss拦截。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| | followTransformOfTarget13+ | boolean | 否 | 气泡绑定的宿主组件或其宿主组件的父容器添加了旋转、缩放等变换时，气泡是否能显示在对应变化后的位置上。
默认值：false
**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | | keyboardAvoidMode15+ | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12枚举说明) | 否 | 气泡是否避让软键盘，默认不避让。设置为避让后，气泡显示空间不足时，由原先居中覆盖父组件的方式改为平移覆盖父组件，且气泡箭头不指向宿主时，不再显示箭头。
默认值：KeyboardAvoidMode.NONE
**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | | enableHoverMode18+| boolean | 否 | Popup组件是否响应悬停态变化。如果Popup的点击位置在悬停态折痕区域，Popup组件不会响应悬停态。默认值：false，Popup组件不响应悬停态变化。
**说明：**
enableHoverMode为 false，未设置或者值为非法值时，Popup组件不会响应悬停态，enableHoverMode为true时，响应悬停态。
**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | ## PopupMessageOptions10+类型说明 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 |说明 | | --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | | textColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置弹窗信息文本颜色。 | | font | [Font](ts-types.md#font) | 否 | 设置弹窗信息字体属性。
**说明：**
不支持设置family。 | ## DismissPopupAction12+类型说明 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------- | ---- | --------------------------------------------------------------- | | dismiss | function | 是 | Popup关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | | reason | [DismissReason](#dismissreason12枚举说明) | 是 | 关闭原因，返回本次拦截Popup消失的事件原因。 | ## DismissReason12+枚举说明 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 说明 | | ------------- | ------------------ | | PRESS_BACK | 点击Back键。 | | TOUCH_OUTSIDE | 点击组件外部区域。 | ## CustomPopupOptions8+类型说明 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | | builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 提示气泡内容的构造器。
**说明：**
Popup为通用属性，自定义Popup中不支持再次弹出Popup。对builder下的第一层容器组件不支持使用position属性，如果使用将导致气泡不显示。builder中若使用自定义组件，自定义组件的aboutToAppear和aboutToDisappear生命周期与Popup弹窗的显隐无关，不能使用其生命周期判断Popup弹窗的显隐。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | placement | [Placement](ts-appendix-enums.md#placement8) | 否 | 气泡组件优先显示的位置，当前位置显示不下时，会自动调整位置。
默认值：Placement.Bottom
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | popupColor | number \| [Color](ts-types.md#color) \| string \| [Resource](ts-types.md#resource) | 否 | 提示气泡的颜色。如需去除模糊背景填充效果，需将backgroundBlurStyle设置为BlurStyle.NONE。
API version 10，默认值：'#4d4d4d'
API version 11及以后，默认值：透明色[TRANSPARENT](ts-appendix-enums.md#color)加模糊背景填充效果[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | enableArrow | boolean | 否 | 是否显示箭头。
从API version 9开始，如果箭头所在方位侧的气泡长度不足以显示下箭头，则会默认不显示箭头。比如：placement设置为Left，此时如果气泡高度小于箭头的宽度（32vp）与气泡圆角两倍（48vp）之和（80vp），则实际不会显示箭头。
默认值：true
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | autoCancel | boolean | 否 | 页面有操作时，是否自动关闭气泡。
默认值：true
**说明：**
如果要实现点击气泡内消失需要在builder中先放一个布局组件，然后再将Popup高级组件放在布局组件里面，再在布局组件的onClick事件中修改的传入bindPopup的变量（show: boolean）值。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | onStateChange | (event: { isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数为弹窗当前的显示状态。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | arrowOffset9+ | [Length](ts-types.md#length) | 否 | Popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | showInSubWindow9+ | boolean | 否 | 取值为true时，气泡会显示在创建的子窗里，取值为false时，气泡会显示在对应的主窗中。
默认值：false
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | maskColor(deprecated) | [Resource](ts-types.md#resource) \| string \| number \|  [Color](ts-types.md#color) | 否 | 设置气泡遮罩层颜色。
**说明：**
从 API version 10 开始废弃，建议使用`mask`替代。 | | mask10+ | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为Color，则为遮罩层的颜色。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | targetSpace10+ | [Length](ts-types.md#length) | 否 | 设置Popup与目标的间隙。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | offset10+ | [Position](ts-types.md#position) | 否 | 设置Popup组件相对于placement设置的显示位置的偏移。
**说明：**
不支持设置百分比。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | width11+ | [Dimension](ts-types.md#dimension10) | 否 | 弹窗宽度。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | arrowPointPosition11+ | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | 否 | 气泡尖角相对于父组件显示位置，气泡尖角在垂直和水平方向上有 ”Start“、”Center“、”End“三个位置点可选。以上所有位置点均位于父组件区域的范围内，不会超出父组件的边界范围。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | arrowWidth11+ | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小，则不绘制气泡箭头。
默认值：16
单位：vp
**说明：**
不支持设置百分比。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | arrowHeight11+ | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头高度。
默认值：8
单位：vp
**说明：**
不支持设置百分比。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | radius11+ | [Dimension](ts-types.md#dimension10) | 否 | 设置气泡圆角半径。
默认值：20
单位：vp
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | shadow11+ | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置气泡阴影。
默认值：ShadowStyle.OUTER_DEFAULT_MD
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | | backgroundBlurStyle11+ | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 设置气泡模糊背景参数。
默认值：BlurStyle.COMPONENT_ULTRA_THICK
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| | focusable11+ | boolean | 否 | 设置气泡弹出后是否获焦。
默认值：false
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| | transition12+ | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 自定义设置Popup弹窗显示和退出的动画效果。
**说明：**
如果不设置，则使用默认的显示/退出动效。
2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。
3.退出动效中按back键，不会打断退出动效，退出动效继续执行，back键不被响应。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| | onWillDismiss12+ | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12类型说明))> | 否 | 设置Popup交互式关闭拦截开关及拦截回调函数，默认值为true，Popup响应点击、左滑/右滑、三键back。
1.当为boolean类型时，如果设置为false，则不响应点击、左滑/右滑、三键back或键盘ESC退出事件，仅当设置“弹窗显示状态”参数show值为false时才退出；如果设置为true，则正常响应退出事件；
2.如果设置为函数类型，则拦截退出事件且执行回调函数。
**说明：**
在onWillDismiss回调中，不能再做onWillDismiss拦截。
**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| | followTransformOfTarget13+ | boolean | 否 | 气泡绑定的宿主组件或其宿主组件的父容器添加了旋转、缩放等变换时，气泡是否能显示在对应变化后的位置上。
默认值：false
**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | | keyboardAvoidMode15+ | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12枚举说明) | 否 | 气泡是否避让软键盘，默认不避让。设置为避让后，气泡显示空间不足时，由原先居中覆盖父组件的方式改为平移覆盖父组件，且气泡箭头不指向宿主时，不再显示箭头。
默认值：KeyboardAvoidMode.NONE
**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | |enableHoverMode18+ | boolean | 否 | Popup组件是否响应悬停态变化。如果Popup的点击位置在悬停态折痕区域，Popup组件不会响应悬停态。默认值：false，Popup组件不响应悬停态变化。
**说明：**
enableHoverMode为false，未设置或者值为非法值时，Popup组件不会响应悬停态，enableHoverMode为true时，响应悬停态。
**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | ## PopupCommonOptions18+类型说明 配置弹出弹窗的参数。使用[UIContext](../js-apis-arkui-UIContext.md#uicontext)中的[getPromptAction()](../js-apis-arkui-UIContext.md#getpromptaction)方法获取到[PromptAction](../js-apis-arkui-UIContext.md#promptaction)对象，再通过该对象调用[openPopup](../js-apis-arkui-UIContext.md#openpopup18)和[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)时options的属性。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | | placement | [Placement](ts-appendix-enums.md#placement8) | 否 | 气泡组件优先显示的位置，当前位置显示不下时，会自动调整位置。
默认值：Placement.Bottom | | popupColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 提示气泡的颜色。如需去除模糊背景填充效果，需将backgroundBlurStyle设置为BlurStyle.NONE。默认值：透明色[TRANSPARENT](ts-appendix-enums.md#color)加模糊背景填充效果[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)。 | | enableArrow | boolean | 否 | 是否显示箭头。
如果箭头所在方位侧的气泡长度不足以显示下箭头，则会默认不显示箭头。比如：placement设置为Left，此时如果气泡高度小于箭头的宽度（32vp）与气泡圆角两倍（48vp）之和（80vp），则实际不会显示箭头。
默认值：true | | autoCancel | boolean | 否 | 页面有操作时，是否自动关闭气泡。
默认值：true | | onStateChange | [PopupStateChangeCallback](#popupstatechangecallback18类型说明) | 否 | 弹窗状态变化事件回调。
**说明：**
不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | | arrowOffset | [Length](ts-types.md#length) | 否 | Popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。 | | showInSubWindow | boolean | 否 | 取值为true时，气泡会显示在创建的子窗里，取值为false时，气泡会显示在对应的主窗中。
默认值：false
**说明：**
不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | | mask | boolean \| [PopupMaskType](#popupmasktype18类型说明) | 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为PopupMaskType，则为遮罩层的颜色。 | | targetSpace | [Length](ts-types.md#length) | 否 | 设置Popup与目标的间隙。 | | offset | [Position](ts-types.md#position) | 否 | 设置Popup组件相对于placement设置的显示位置的偏移。
**说明：**
不支持设置百分比。 | | width | [Dimension](ts-types.md#dimension10) | 否 | 弹窗宽度。 | | arrowPointPosition | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | 否 | 气泡尖角相对于父组件显示位置，气泡尖角在垂直和水平方向上有 ”Start“、”Center“、”End“三个位置点可选。以上所有位置点均位于父组件区域的范围内，不会超出父组件的边界范围。 | | arrowWidth | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小，则不绘制气泡箭头。
默认值：16
单位：vp
**说明：**
不支持设置百分比。 | | arrowHeight | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头高度。
默认值：8
单位：vp
**说明：**
不支持设置百分比。 | | radius | [Dimension](ts-types.md#dimension10) | 否 | 设置气泡圆角半径。
默认值：20
单位：vp | | shadow | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置气泡阴影。
默认值：ShadowStyle.OUTER_DEFAULT_MD | | backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 设置气泡模糊背景参数。
默认值：BlurStyle.COMPONENT_ULTRA_THICK | | focusable | boolean | 否 | 设置气泡弹出后是否获焦。
默认值：false
**说明：**
不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | | transition | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 自定义设置Popup弹窗显示和退出的动画效果。
**说明：**
1.如果不设置，则使用默认的显示/退出动效。
2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。
3.退出动效中按back键，不会打断退出动效，退出动效继续执行，back键不被响应。
4.不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | | onWillDismiss | boolean\|Callback<[DismissPopupAction](#dismisspopupaction12类型说明)> | 否 | 设置Popup交互式关闭拦截开关及拦截回调函数，默认值为true，Popup响应点击、左滑/右滑、三键back。
1.当为boolean类型时，如果设置为false，则不响应点击、左滑/右滑、三键back或键盘ESC退出事件，仅当设置“弹窗显示状态”参数show值为false时才退出；如果设置为true，则正常响应退出事件；
2.如果设置为函数类型，则拦截退出事件且执行回调函数。
**说明：**
1.在onWillDismiss回调中，不能再做onWillDismiss拦截。
2.不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | | followTransformOfTarget | boolean | 否 | 气泡绑定的宿主组件或其宿主组件的父容器添加了旋转、缩放等变换时，气泡是否能显示在对应变化后的位置上。
默认值：false | |enableHoverMode | boolean | 否 | Popup组件是否响应悬停态变化。如果Popup的点击位置在悬停态折痕区域，Popup组件不会响应悬停态。默认值：false，Popup组件不响应悬停态变化。
**说明：**
enableHoverMode为false，未设置或者值为非法值时，Popup组件不会响应悬停态，enableHoverMode为true时，响应悬停态。 | ## PopupStateChangeParam18+类型说明 弹窗当前的显示状态。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | | isVisible | boolean | 是 | 弹窗当前的显示状态。 | ## PopupStateChangeCallback18+类型说明 弹窗状态变化事件回调。 type PopupStateChangeCallback = (event: PopupStateChangeParam) => void; **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | | event | [PopupStateChangeParam](#popupstatechangeparam18类型说明) | 是 | 弹窗当前的显示状态。 | ## PopupMaskType18+类型说明 设置遮罩层颜色。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 必填 | 说明 | | --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | | color | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置遮罩层颜色。 | ## 示例 ### 示例1（弹出不同类型的气泡） 该示例为bindPopup通过配置Popup弹出PopupOptions、CustomPopupOptions类型的气泡。 ```ts // xxx.ets @Entry @Component struct PopupExample { @State handlePopup: boolean = false; @State customPopup: boolean = false; // Popup构造器定义弹框内容 @Builder popupBuilder() { Row({ space: 2 }) { Image($r("app.media.icon")).width(24).height(24).margin({ left: -5 }) Text('Custom Popup').fontSize(10) }.width(100).height(50).padding(5) } build() { Flex({ direction: FlexDirection.Column }) { // PopupOptions 类型设置弹框内容 Button('PopupOptions') .onClick(() => { this.handlePopup = !this.handlePopup; }) .bindPopup(this.handlePopup, { message: 'This is a popup with PopupOptions', placementOnTop: true, showInSubWindow:false, // 设置气泡避让软键盘 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, primaryButton: { value: 'confirm', action: () => { this.handlePopup = !this.handlePopup; console.info('confirm Button click'); } }, // 第二个按钮 secondaryButton: { value: 'cancel', action: () => { this.handlePopup = !this.handlePopup; console.info('cancel Button click'); } }, onStateChange: (e) => { console.info(JSON.stringify(e.isVisible)) if (!e.isVisible) { this.handlePopup = false; } } }) .position({ x: 100, y: 150 }) // CustomPopupOptions 类型设置弹框内容 Button('CustomPopupOptions') .onClick(() => { this.customPopup = !this.customPopup; }) .bindPopup(this.customPopup, { builder: this.popupBuilder, placement: Placement.Top, mask: {color:'#33000000'}, popupColor: Color.Yellow, enableArrow: true, // 设置气泡避让软键盘 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, showInSubWindow: false, onStateChange: (e) => { if (!e.isVisible) { this.customPopup = false; } } }) .position({ x: 80, y: 300 }) }.width('100%').padding({ top: 5 }) } } ``` ![](figures/popup.gif) ### 示例2（设置气泡的文本样式） 该示例为bindPopup通过配置messageOptions弹出自定义文本样式的气泡。 ```ts // xxx.ets @Entry @Component struct PopupExample { @State handlePopup: boolean = false; build() { Column({ space: 100 }) { Button('PopupOptions').margin(100) .onClick(() => { this.handlePopup = !this.handlePopup; }) .bindPopup(this.handlePopup, { // PopupOptions类型气泡的内容 message: 'This is a popup with PopupOptions', messageOptions: { // 气泡的文本样式 textColor: Color.Red, font: { size: '14vp', style: FontStyle.Italic, weight: FontWeight.Bolder } }, placement: Placement.Bottom, enableArrow: false, // 气泡弹出时不显示箭头 targetSpace: '15vp', onStateChange: (e) => { console.info(JSON.stringify(e.isVisible)); if (!e.isVisible) { this.handlePopup = false; } } }) }.margin(20) } } ``` ![popup_02](figures/popup_02.gif) ### 示例3（设置气泡的样式） 该示例为bindPopup通过配置arrowHeight、arrowWidth、radius、shadow、popupColor，实现气泡箭头以及气泡本身的样式。 ```ts // xxx.ets @Entry @Component struct PopupExample { @State customPopup: boolean = false; @State handlePopup: boolean = false; build() { Column({ space: 100 }) { Button("popup") .margin({ top: 50 }) .onClick(() => { this.customPopup = !this.customPopup; }) .bindPopup(this.customPopup, { message: "this is a popup", arrowHeight: 20, // 设置气泡箭头高度 arrowWidth: 20, // 设置气泡箭头宽度 radius: 20, // 设置气泡的圆角 shadow: ShadowStyle.OUTER_DEFAULT_XS, // 设置气泡的阴影 }) Button('PopupOptions') .onClick(() => { this.handlePopup = !this.handlePopup; }) .bindPopup(this.handlePopup, { width: 300, message: 'This is a popup with PopupOptions', arrowPointPosition: ArrowPointPosition.START, // 设置箭头的位置 backgroundBlurStyle: BlurStyle.NONE, // 关闭气泡的模糊背景 popupColor: Color.Red, // 设置气泡的背景色 autoCancel: true, }) } .width('100%') } } ``` ![](figures/popup_04.gif) ### 示例4（设置气泡的动效） 该示例为bindPopup通过配置transition，实现气泡的显示和退出动效。 ```ts // xxx.ets @Entry @Component struct PopupExample { @State handlePopup: boolean = false; @State customPopup: boolean = false; // Popup构造器定义弹框内容 @Builder popupBuilder() { Row() { Text('Custom Popup with transitionEffect').fontSize(10) }.height(50).padding(5) } build() { Flex({ direction: FlexDirection.Column }) { // PopupOptions 类型设置弹框内容 Button('PopupOptions') .onClick(() => { this.handlePopup = !this.handlePopup; }) .bindPopup(this.handlePopup, { message: 'This is a popup with transitionEffect', placementOnTop: true, showInSubWindow: false, onStateChange: (e) => { console.info(JSON.stringify(e.isVisible)) if (!e.isVisible) { this.handlePopup = false; } }, // 设置弹窗显示动效为透明度动效与平移动效的组合效果，无退出动效 transition:TransitionEffect.asymmetric( TransitionEffect.OPACITY.animation({ duration: 1000, curve: Curve.Ease }).combine( TransitionEffect.translate({ x: 50, y: 50 })), TransitionEffect.IDENTITY) }) .position({ x: 100, y: 150 }) // CustomPopupOptions 类型设置弹框内容 Button('CustomPopupOptions') .onClick(() => { this.customPopup = !this.customPopup; }) .bindPopup(this.customPopup, { builder: this.popupBuilder, placement: Placement.Top, showInSubWindow: false, onStateChange: (e) => { if (!e.isVisible) { this.customPopup = false; } }, // 设置弹窗显示动效与退出动效为缩放动效 transition:TransitionEffect.scale({ x: 1, y: 0 }).animation({ duration: 500, curve: Curve.Ease }) }) .position({ x: 80, y: 300 }) }.width('100%').padding({ top: 5 }) } } ``` ![](figures/popup_05.gif) ### 示例5（为气泡添加事件） 该示例为bindPopup通过配置onWillDismiss，实现当气泡退出时，拦截退出事件并执行回调函数。 ```ts // xxx.ets @Entry @Component struct PopupExample { @State handlePopup: boolean = false; build() { Column() { Button('PopupOptions') .onClick(() => { this.handlePopup = true; }) .bindPopup(this.handlePopup, { message: 'This is a popup with PopupOptions', messageOptions: { textColor: Color.Red, font: { size: '14vp', style: FontStyle.Italic, weight: FontWeight.Bolder } }, placement: Placement.Bottom, enableArrow: false, targetSpace: '15vp', onStateChange: (e) => { if (!e.isVisible) { this.handlePopup = false; } }, onWillDismiss: ( (dismissPopupAction: DismissPopupAction) => { console.info("dismissReason:" + JSON.stringify(dismissPopupAction.reason)); if (dismissPopupAction.reason === DismissReason.PRESS_BACK) { dismissPopupAction.dismiss(); } } ) }) }.margin(20) } } ``` ![](figures/popup_004.gif) ### 示例6（为气泡拦截退出事件） 该示例通过配置onWillDismiss的boolean类型为false时，拦截气泡的退出事件。 ```ts // xxx.ets @Entry @Component struct PopupExample { @State handlePopup: boolean = false; build() { Column() { Button('PopupOptions') .onClick(() => { this.handlePopup = true; }) .bindPopup(this.handlePopup, { message: 'This is a popup with PopupOptions', messageOptions: { textColor: Color.Red, font: { size: '14vp', style: FontStyle.Italic, weight: FontWeight.Bolder } }, placement: Placement.Bottom, enableArrow: false, targetSpace: '15vp', followTransformOfTarget: true, onStateChange: (e) => { let timer = setTimeout(() => { this.handlePopup = false; }, 6000); if (!e.isVisible) { this.handlePopup = false; clearTimeout(timer); } }, onWillDismiss: false }) }.margin(20) } } ``` ![](figures/popup_005.gif)