1# Popup控制 2 3给组件绑定Popup弹窗，并设置弹窗内容，交互逻辑和显示状态。 4 5> **说明：** 6> 7> - 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - Popup弹窗的显示状态在onStateChange事件回调中反馈，其显隐与组件的创建或销毁无强对应关系。 10 11## bindPopup 12 13bindPopup(show: boolean, popup: PopupOptions | CustomPopupOptions) 14 15给组件绑定Popup弹窗。 16 17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21**参数：** 22 23| 参数名 | 类型 | 必填 | 说明 | 24| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 25| show | boolean | 是 | 弹窗显示状态，默认值为false，隐藏弹窗。Popup弹窗必须等待页面全部构建完成才能展示，因此show不能在页面构建中设置为true，否则会导致Popup弹窗显示位置及形状错误。该参数从API version 13开始支持[!!语法](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。 | 26| popup | [PopupOptions](#popupoptions类型说明) \| [CustomPopupOptions](#custompopupoptions8类型说明)<sup>8+</sup> | 是 | 配置弹出弹窗的参数。 | 27 28## PopupOptions类型说明 29 30**系统能力：** SystemCapability.ArkUI.ArkUI.Full 31 32| 名称 | 类型 | 必填 | 说明 | 33| ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 34| message | string | 是 | 弹窗信息内容。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 35| placementOnTop<sup>(deprecated)</sup> | boolean | 否 | 是否在组件上方显示，默认值为false。<br />**说明：**<br />从 API version 10 开始废弃，建议使用`placement`替代。 | 36| primaryButton | {<br/>value: string,<br/>action: () => void<br/>} | 否 | 第一个按钮。<br/>value：弹窗里主按钮的文本。<br/>action：点击主按钮的回调函数。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 37| secondaryButton | {<br/>value: string,<br/>action: () => void<br/>} | 否 | 第二个按钮。<br/>value：弹窗里辅助按钮的文本。<br/>action：点击辅助按钮的回调函数。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 38| onStateChange | (event: { isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数isVisible为弹窗当前的显示状态。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 39| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | 否 | Popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 40| showInSubWindow<sup>9+</sup> | boolean | 否 | 取值为true时，气泡会显示在创建的子窗里，取值为false时，气泡会显示在对应的主窗中。<br />默认值：false<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 41| mask<sup>10+</sup> | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为Color，则为遮罩层的颜色。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 42| messageOptions<sup>10+</sup> | [PopupMessageOptions](#popupmessageoptions10类型说明) | 否 | 设置弹窗信息文本参数。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | 否 | 设置Popup与目标的间隙。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 44| placement<sup>10+</sup> | [Placement](ts-appendix-enums.md#placement8) | 否 | 设置Popup组件相对于目标的显示位置，默认值为Placement.Bottom。<br />如果同时设置了`placementOnTop`和`placement`，则以`placement`的设置生效。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 45| offset<sup>10+</sup> | [Position](ts-types.md#position) | 否 | 设置Popup组件相对于placement设置的显示位置的偏移。<br />**说明：**<br />不支持设置百分比。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 46| enableArrow<sup>10+</sup> | boolean | 否 | 设置是否显示箭头。<br/>默认值：true<br/>**说明：** <br/>当页面可用空间无法让气泡完全避让时，气泡会覆盖到组件上并且不显示箭头。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 47| popupColor<sup>11+</sup> | [Color](ts-appendix-enums.md#color) \| string \| number \| [Resource](ts-types.md#resource) | 否 | 提示气泡的颜色。如需去除模糊背景填充效果，需将backgroundBlurStyle设置为BlurStyle.NONE。<br/>默认值：透明色[TRANSPARENT](ts-appendix-enums.md#color)加模糊背景填充效果[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 48| autoCancel<sup>11+</sup> | boolean | 否 | 页面有操作时，是否自动关闭气泡。<br/>默认值：true <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 49| width<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 弹窗宽度。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 50| arrowPointPosition<sup>11+</sup> | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | 否 | 气泡尖角相对于父组件显示位置，气泡尖角在垂直和水平方向上有 ”Start“、”Center“、”End“三个位置点可选。以上所有位置点均位于父组件区域的范围内，不会超出父组件的边界范围。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 51| arrowWidth<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小，则不绘制气泡箭头。<br/>默认值：16<br/>单位：vp<br/>**说明：**<br />不支持设置百分比。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 52| arrowHeight<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头高度。<br/>默认值：8<br/>单位：vp<br/>**说明：**<br />不支持设置百分比。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 53| radius<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置气泡圆角半径。<br/>默认值：20<br/>单位：vp<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 54| shadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置气泡阴影。<br/>默认值：ShadowStyle.OUTER_DEFAULT_MD <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 55| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 设置气泡模糊背景参数。<br />默认值：BlurStyle.COMPONENT_ULTRA_THICK<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 56| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 自定义设置Popup弹窗显示和退出的动画效果。<br/>**说明：**<br/>1.如果不设置，则使用默认的显示/退出动效。<br/>2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。<br/>3.退出动效中按back键，不会打断退出动效，退出动效继续执行，back键不被响应。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 57| onWillDismiss<sup>12+</sup> | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12类型说明))> | 否 | 设置Popup交互式关闭拦截开关及拦截回调函数，默认值为true，Popup响应点击、左滑/右滑、三键back。<br />1.当为boolean类型时，如果设置为false，则不响应点击、左滑/右滑、三键back或键盘ESC退出事件，仅当设置“弹窗显示状态”参数show值为false时才退出；如果设置为true，则正常响应退出事件；<br />2.如果设置为函数类型，则拦截退出事件且执行回调函数。<br />**说明：**<br />在onWillDismiss回调中，不能再做onWillDismiss拦截。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 58| followTransformOfTarget<sup>13+</sup> | boolean | 否 | 气泡绑定的宿主组件或其宿主组件的父容器添加了旋转、缩放等变换时，气泡是否能显示在对应变化后的位置上。<br/>默认值：false <br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 59| keyboardAvoidMode<sup>15+</sup> | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12枚举说明) | 否 | 气泡是否避让软键盘，默认不避让。设置为避让后，气泡显示空间不足时，由原先居中覆盖父组件的方式改为平移覆盖父组件，且气泡箭头不指向宿主时，不再显示箭头。<br/>默认值：KeyboardAvoidMode.NONE <br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 60| enableHoverMode<sup>18+</sup>| boolean | 否 | Popup组件是否响应悬停态变化。如果Popup的点击位置在悬停态折痕区域，Popup组件不会响应悬停态。默认值：false，Popup组件不响应悬停态变化。<br />**说明：** <br />enableHoverMode为 false，未设置或者值为非法值时，Popup组件不会响应悬停态，enableHoverMode为true时，响应悬停态。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 61 62## PopupMessageOptions<sup>10+</sup>类型说明 63 64**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 65 66**系统能力：** SystemCapability.ArkUI.ArkUI.Full 67 68| 名称 | 类型 | 必填 |说明 | 69| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 70| textColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置弹窗信息文本颜色。 | 71| font | [Font](ts-types.md#font) | 否 | 设置弹窗信息字体属性。<br/>**说明：** <br/>不支持设置family。 | 72 73## DismissPopupAction<sup>12+</sup>类型说明 74 75**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79| 名称 | 类型 | 必填 | 说明 | 80| ------- | ----------------------------------------- | ---- | --------------------------------------------------------------- | 81| dismiss | function | 是 | Popup关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 82| reason | [DismissReason](#dismissreason12枚举说明) | 是 | 关闭原因，返回本次拦截Popup消失的事件原因。 | 83 84## DismissReason<sup>12+</sup>枚举说明 85 86**系统能力：** SystemCapability.ArkUI.ArkUI.Full 87 88| 名称 | 说明 | 89| ------------- | ------------------ | 90| PRESS_BACK | 点击Back键。 | 91| TOUCH_OUTSIDE | 点击组件外部区域。 | 92 93## CustomPopupOptions<sup>8+</sup>类型说明 94 95**系统能力：** SystemCapability.ArkUI.ArkUI.Full 96 97| 名称 | 类型 | 必填 | 说明 | 98| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 99| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 提示气泡内容的构造器。<br />**说明：**<br />Popup为通用属性，自定义Popup中不支持再次弹出Popup。对builder下的第一层容器组件不支持使用position属性，如果使用将导致气泡不显示。builder中若使用自定义组件，自定义组件的aboutToAppear和aboutToDisappear生命周期与Popup弹窗的显隐无关，不能使用其生命周期判断Popup弹窗的显隐。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 100| placement | [Placement](ts-appendix-enums.md#placement8) | 否 | 气泡组件优先显示的位置，当前位置显示不下时，会自动调整位置。<br/>默认值：Placement.Bottom<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 101| popupColor | number \| [Color](ts-types.md#color) \| string \| [Resource](ts-types.md#resource) | 否 | 提示气泡的颜色。如需去除模糊背景填充效果，需将backgroundBlurStyle设置为BlurStyle.NONE。<br/>API version 10，默认值：'#4d4d4d'<br />API version 11及以后，默认值：透明色[TRANSPARENT](ts-appendix-enums.md#color)加模糊背景填充效果[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 102| enableArrow | boolean | 否 | 是否显示箭头。<br/>从API version 9开始，如果箭头所在方位侧的气泡长度不足以显示下箭头，则会默认不显示箭头。比如：placement设置为Left，此时如果气泡高度小于箭头的宽度（32vp）与气泡圆角两倍（48vp）之和（80vp），则实际不会显示箭头。<br/>默认值：true<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 103| autoCancel | boolean | 否 | 页面有操作时，是否自动关闭气泡。<br/>默认值：true<br />**说明：**<br />如果要实现点击气泡内消失需要在builder中先放一个布局组件，然后再将Popup高级组件放在布局组件里面，再在布局组件的onClick事件中修改的传入bindPopup的变量（show: boolean）值。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 104| onStateChange | (event: { isVisible: boolean }) => void | 否 | 弹窗状态变化事件回调，参数为弹窗当前的显示状态。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 105| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | 否 | Popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 106| showInSubWindow<sup>9+</sup> | boolean | 否 | 取值为true时，气泡会显示在创建的子窗里，取值为false时，气泡会显示在对应的主窗中。<br />默认值：false<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 107| maskColor<sup>(deprecated)</sup> | [Resource](ts-types.md#resource) \| string \| number \| [Color](ts-types.md#color) | 否 | 设置气泡遮罩层颜色。<br />**说明：**<br />从 API version 10 开始废弃，建议使用`mask`替代。 | 108| mask<sup>10+</sup> | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为Color，则为遮罩层的颜色。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 109| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | 否 | 设置Popup与目标的间隙。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 110| offset<sup>10+</sup> | [Position](ts-types.md#position) | 否 | 设置Popup组件相对于placement设置的显示位置的偏移。<br />**说明：**<br />不支持设置百分比。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 111| width<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 弹窗宽度。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 112| arrowPointPosition<sup>11+</sup> | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | 否 | 气泡尖角相对于父组件显示位置，气泡尖角在垂直和水平方向上有 ”Start“、”Center“、”End“三个位置点可选。以上所有位置点均位于父组件区域的范围内，不会超出父组件的边界范围。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 113| arrowWidth<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小，则不绘制气泡箭头。<br/>默认值：16<br/>单位：vp<br />**说明：**<br />不支持设置百分比。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 114| arrowHeight<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头高度。<br/>默认值：8<br/>单位：vp<br />**说明：**<br />不支持设置百分比。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 115| radius<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 设置气泡圆角半径。<br/>默认值：20<br/>单位：vp<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 116| shadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置气泡阴影。<br/>默认值：ShadowStyle.OUTER_DEFAULT_MD <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 117| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 设置气泡模糊背景参数。<br />默认值：BlurStyle.COMPONENT_ULTRA_THICK <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 118| focusable<sup>11+</sup> | boolean | 否 | 设置气泡弹出后是否获焦。<br />默认值：false <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 119| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 自定义设置Popup弹窗显示和退出的动画效果。<br/>**说明：**<br/>如果不设置，则使用默认的显示/退出动效。<br/>2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。<br/>3.退出动效中按back键，不会打断退出动效，退出动效继续执行，back键不被响应。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 120| onWillDismiss<sup>12+</sup> | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12类型说明))> | 否 | 设置Popup交互式关闭拦截开关及拦截回调函数，默认值为true，Popup响应点击、左滑/右滑、三键back。<br />1.当为boolean类型时，如果设置为false，则不响应点击、左滑/右滑、三键back或键盘ESC退出事件，仅当设置“弹窗显示状态”参数show值为false时才退出；如果设置为true，则正常响应退出事件；<br />2.如果设置为函数类型，则拦截退出事件且执行回调函数。<br />**说明：**<br />在onWillDismiss回调中，不能再做onWillDismiss拦截。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 121| followTransformOfTarget<sup>13+</sup> | boolean | 否 | 气泡绑定的宿主组件或其宿主组件的父容器添加了旋转、缩放等变换时，气泡是否能显示在对应变化后的位置上。<br/>默认值：false <br/>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 122| keyboardAvoidMode<sup>15+</sup> | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12枚举说明) | 否 | 气泡是否避让软键盘，默认不避让。设置为避让后，气泡显示空间不足时，由原先居中覆盖父组件的方式改为平移覆盖父组件，且气泡箭头不指向宿主时，不再显示箭头。<br/>默认值：KeyboardAvoidMode.NONE <br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 123|enableHoverMode<sup>18+</sup> | boolean | 否 | Popup组件是否响应悬停态变化。如果Popup的点击位置在悬停态折痕区域，Popup组件不会响应悬停态。默认值：false，Popup组件不响应悬停态变化。<br />**说明：** <br />enableHoverMode为false，未设置或者值为非法值时，Popup组件不会响应悬停态，enableHoverMode为true时，响应悬停态。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 124 125## PopupCommonOptions<sup>18+</sup>类型说明 126 127配置弹出弹窗的参数。使用[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的属性。 128 129**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 130 131**系统能力：** SystemCapability.ArkUI.ArkUI.Full 132 133| 名称 | 类型 | 必填 | 说明 | 134| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 135| placement | [Placement](ts-appendix-enums.md#placement8) | 否 | 气泡组件优先显示的位置，当前位置显示不下时，会自动调整位置。<br/>默认值：Placement.Bottom | 136| popupColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 提示气泡的颜色。如需去除模糊背景填充效果，需将backgroundBlurStyle设置为BlurStyle.NONE。默认值：透明色[TRANSPARENT](ts-appendix-enums.md#color)加模糊背景填充效果[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)。 | 137| enableArrow | boolean | 否 | 是否显示箭头。<br/>如果箭头所在方位侧的气泡长度不足以显示下箭头，则会默认不显示箭头。比如：placement设置为Left，此时如果气泡高度小于箭头的宽度（32vp）与气泡圆角两倍（48vp）之和（80vp），则实际不会显示箭头。<br/>默认值：true | 138| autoCancel | boolean | 否 | 页面有操作时，是否自动关闭气泡。<br/>默认值：true | 139| onStateChange | [PopupStateChangeCallback](#popupstatechangecallback18类型说明) | 否 | 弹窗状态变化事件回调。<br />**说明：**<br />不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | 140| arrowOffset | [Length](ts-types.md#length) | 否 | Popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。 | 141| showInSubWindow | boolean | 否 | 取值为true时，气泡会显示在创建的子窗里，取值为false时，气泡会显示在对应的主窗中。<br />默认值：false<br />**说明：**<br />不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | 142| mask | boolean \| [PopupMaskType](#popupmasktype18类型说明) | 否 | 设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为PopupMaskType，则为遮罩层的颜色。 | 143| targetSpace | [Length](ts-types.md#length) | 否 | 设置Popup与目标的间隙。 | 144| offset | [Position](ts-types.md#position) | 否 | 设置Popup组件相对于placement设置的显示位置的偏移。<br />**说明：**<br />不支持设置百分比。 | 145| width | [Dimension](ts-types.md#dimension10) | 否 | 弹窗宽度。 | 146| arrowPointPosition | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | 否 | 气泡尖角相对于父组件显示位置，气泡尖角在垂直和水平方向上有 ”Start“、”Center“、”End“三个位置点可选。以上所有位置点均位于父组件区域的范围内，不会超出父组件的边界范围。 | 147| arrowWidth | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小，则不绘制气泡箭头。<br/>默认值：16<br/>单位：vp<br />**说明：**<br />不支持设置百分比。 | 148| arrowHeight | [Dimension](ts-types.md#dimension10) | 否 | 设置箭头高度。<br/>默认值：8<br/>单位：vp<br />**说明：**<br />不支持设置百分比。 | 149| radius | [Dimension](ts-types.md#dimension10) | 否 | 设置气泡圆角半径。<br/>默认值：20<br/>单位：vp | 150| shadow | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 设置气泡阴影。<br/>默认值：ShadowStyle.OUTER_DEFAULT_MD | 151| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 设置气泡模糊背景参数。<br />默认值：BlurStyle.COMPONENT_ULTRA_THICK | 152| focusable | boolean | 否 | 设置气泡弹出后是否获焦。<br />默认值：false<br />**说明：**<br />不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | 153| transition | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 自定义设置Popup弹窗显示和退出的动画效果。<br/>**说明：**<br/>1.如果不设置，则使用默认的显示/退出动效。<br/>2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。<br/>3.退出动效中按back键，不会打断退出动效，退出动效继续执行，back键不被响应。<br/>4.不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | 154| onWillDismiss | boolean\|Callback<[DismissPopupAction](#dismisspopupaction12类型说明)> | 否 | 设置Popup交互式关闭拦截开关及拦截回调函数，默认值为true，Popup响应点击、左滑/右滑、三键back。<br />1.当为boolean类型时，如果设置为false，则不响应点击、左滑/右滑、三键back或键盘ESC退出事件，仅当设置“弹窗显示状态”参数show值为false时才退出；如果设置为true，则正常响应退出事件；<br />2.如果设置为函数类型，则拦截退出事件且执行回调函数。<br />**说明：**<br />1.在onWillDismiss回调中，不能再做onWillDismiss拦截。<br />2.不支持通过[updatePopup](../js-apis-arkui-UIContext.md#updatepopup18)进行更新。 | 155| followTransformOfTarget | boolean | 否 | 气泡绑定的宿主组件或其宿主组件的父容器添加了旋转、缩放等变换时，气泡是否能显示在对应变化后的位置上。<br/>默认值：false | 156|enableHoverMode | boolean | 否 | Popup组件是否响应悬停态变化。如果Popup的点击位置在悬停态折痕区域，Popup组件不会响应悬停态。默认值：false，Popup组件不响应悬停态变化。<br />**说明：** <br />enableHoverMode为false，未设置或者值为非法值时，Popup组件不会响应悬停态，enableHoverMode为true时，响应悬停态。 | 157 158## PopupStateChangeParam<sup>18+</sup>类型说明 159 160弹窗当前的显示状态。 161 162**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166| 名称 | 类型 | 必填 | 说明 | 167| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 168| isVisible | boolean | 是 | 弹窗当前的显示状态。 | 169 170## PopupStateChangeCallback<sup>18+</sup>类型说明 171 172弹窗状态变化事件回调。 173 174type PopupStateChangeCallback = (event: PopupStateChangeParam) => void; 175 176**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 177 178**系统能力：** SystemCapability.ArkUI.ArkUI.Full 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 184| event | [PopupStateChangeParam](#popupstatechangeparam18类型说明) | 是 | 弹窗当前的显示状态。 | 185 186## PopupMaskType<sup>18+</sup>类型说明 187 188设置遮罩层颜色。 189 190**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.ArkUI.ArkUI.Full 193 194| 名称 | 类型 | 必填 | 说明 | 195| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 196| color | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置遮罩层颜色。 | 197 198## 示例 199 200### 示例1（弹出不同类型的气泡） 201 202该示例为bindPopup通过配置Popup弹出PopupOptions、CustomPopupOptions类型的气泡。 203 204```ts 205// xxx.ets 206@Entry 207@Component 208struct PopupExample { 209 @State handlePopup: boolean = false; 210 @State customPopup: boolean = false; 211 212 // Popup构造器定义弹框内容 213 @Builder popupBuilder() { 214 Row({ space: 2 }) { 215 Image($r("app.media.icon")).width(24).height(24).margin({ left: -5 }) 216 Text('Custom Popup').fontSize(10) 217 }.width(100).height(50).padding(5) 218 } 219 220 build() { 221 Flex({ direction: FlexDirection.Column }) { 222 // PopupOptions 类型设置弹框内容 223 Button('PopupOptions') 224 .onClick(() => { 225 this.handlePopup = !this.handlePopup; 226 }) 227 .bindPopup(this.handlePopup, { 228 message: 'This is a popup with PopupOptions', 229 placementOnTop: true, 230 showInSubWindow:false, 231 // 设置气泡避让软键盘 232 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, 233 primaryButton: { 234 value: 'confirm', 235 action: () => { 236 this.handlePopup = !this.handlePopup; 237 console.info('confirm Button click'); 238 } 239 }, 240 // 第二个按钮 241 secondaryButton: { 242 value: 'cancel', 243 action: () => { 244 this.handlePopup = !this.handlePopup; 245 console.info('cancel Button click'); 246 } 247 }, 248 onStateChange: (e) => { 249 console.info(JSON.stringify(e.isVisible)) 250 if (!e.isVisible) { 251 this.handlePopup = false; 252 } 253 } 254 }) 255 .position({ x: 100, y: 150 }) 256 257 258 // CustomPopupOptions 类型设置弹框内容 259 Button('CustomPopupOptions') 260 .onClick(() => { 261 this.customPopup = !this.customPopup; 262 }) 263 .bindPopup(this.customPopup, { 264 builder: this.popupBuilder, 265 placement: Placement.Top, 266 mask: {color:'#33000000'}, 267 popupColor: Color.Yellow, 268 enableArrow: true, 269 // 设置气泡避让软键盘 270 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, 271 showInSubWindow: false, 272 onStateChange: (e) => { 273 if (!e.isVisible) { 274 this.customPopup = false; 275 } 276 } 277 }) 278 .position({ x: 80, y: 300 }) 279 }.width('100%').padding({ top: 5 }) 280 } 281} 282``` 283 284 285 286### 示例2（设置气泡的文本样式） 287 288该示例为bindPopup通过配置messageOptions弹出自定义文本样式的气泡。 289 290```ts 291// xxx.ets 292 293@Entry 294@Component 295struct PopupExample { 296 @State handlePopup: boolean = false; 297 298 build() { 299 Column({ space: 100 }) { 300 Button('PopupOptions').margin(100) 301 .onClick(() => { 302 this.handlePopup = !this.handlePopup; 303 }) 304 .bindPopup(this.handlePopup, { 305 // PopupOptions类型气泡的内容 306 message: 'This is a popup with PopupOptions', 307 messageOptions: { 308 // 气泡的文本样式 309 textColor: Color.Red, 310 font: { 311 size: '14vp', 312 style: FontStyle.Italic, 313 weight: FontWeight.Bolder 314 } 315 }, 316 placement: Placement.Bottom, 317 enableArrow: false, // 气泡弹出时不显示箭头 318 targetSpace: '15vp', 319 onStateChange: (e) => { 320 console.info(JSON.stringify(e.isVisible)); 321 if (!e.isVisible) { 322 this.handlePopup = false; 323 } 324 } 325 }) 326 }.margin(20) 327 } 328} 329``` 330 331 332 333### 示例3（设置气泡的样式） 334 335该示例为bindPopup通过配置arrowHeight、arrowWidth、radius、shadow、popupColor，实现气泡箭头以及气泡本身的样式。 336 337```ts 338// xxx.ets 339 340@Entry 341@Component 342struct PopupExample { 343 @State customPopup: boolean = false; 344 @State handlePopup: boolean = false; 345 346 build() { 347 Column({ space: 100 }) { 348 Button("popup") 349 .margin({ top: 50 }) 350 .onClick(() => { 351 this.customPopup = !this.customPopup; 352 }) 353 .bindPopup(this.customPopup, { 354 message: "this is a popup", 355 arrowHeight: 20, // 设置气泡箭头高度 356 arrowWidth: 20, // 设置气泡箭头宽度 357 radius: 20, // 设置气泡的圆角 358 shadow: ShadowStyle.OUTER_DEFAULT_XS, // 设置气泡的阴影 359 }) 360 361 Button('PopupOptions') 362 .onClick(() => { 363 this.handlePopup = !this.handlePopup; 364 }) 365 .bindPopup(this.handlePopup, { 366 width: 300, 367 message: 'This is a popup with PopupOptions', 368 arrowPointPosition: ArrowPointPosition.START, // 设置箭头的位置 369 backgroundBlurStyle: BlurStyle.NONE, // 关闭气泡的模糊背景 370 popupColor: Color.Red, // 设置气泡的背景色 371 autoCancel: true, 372 }) 373 } 374 .width('100%') 375 } 376} 377``` 378 379 380 381### 示例4（设置气泡的动效） 382 383该示例为bindPopup通过配置transition，实现气泡的显示和退出动效。 384 385```ts 386// xxx.ets 387@Entry 388@Component 389struct PopupExample { 390 @State handlePopup: boolean = false; 391 @State customPopup: boolean = false; 392 393 // Popup构造器定义弹框内容 394 @Builder popupBuilder() { 395 Row() { 396 Text('Custom Popup with transitionEffect').fontSize(10) 397 }.height(50).padding(5) 398 } 399 400 build() { 401 Flex({ direction: FlexDirection.Column }) { 402 // PopupOptions 类型设置弹框内容 403 Button('PopupOptions') 404 .onClick(() => { 405 this.handlePopup = !this.handlePopup; 406 }) 407 .bindPopup(this.handlePopup, { 408 message: 'This is a popup with transitionEffect', 409 placementOnTop: true, 410 showInSubWindow: false, 411 onStateChange: (e) => { 412 console.info(JSON.stringify(e.isVisible)) 413 if (!e.isVisible) { 414 this.handlePopup = false; 415 } 416 }, 417 // 设置弹窗显示动效为透明度动效与平移动效的组合效果，无退出动效 418 transition:TransitionEffect.asymmetric( 419 TransitionEffect.OPACITY.animation({ duration: 1000, curve: Curve.Ease }).combine( 420 TransitionEffect.translate({ x: 50, y: 50 })), 421 TransitionEffect.IDENTITY) 422 }) 423 .position({ x: 100, y: 150 }) 424 425 // CustomPopupOptions 类型设置弹框内容 426 Button('CustomPopupOptions') 427 .onClick(() => { 428 this.customPopup = !this.customPopup; 429 }) 430 .bindPopup(this.customPopup, { 431 builder: this.popupBuilder, 432 placement: Placement.Top, 433 showInSubWindow: false, 434 onStateChange: (e) => { 435 if (!e.isVisible) { 436 this.customPopup = false; 437 } 438 }, 439 // 设置弹窗显示动效与退出动效为缩放动效 440 transition:TransitionEffect.scale({ x: 1, y: 0 }).animation({ duration: 500, curve: Curve.Ease }) 441 }) 442 .position({ x: 80, y: 300 }) 443 }.width('100%').padding({ top: 5 }) 444 } 445} 446``` 447 448 449 450### 示例5（为气泡添加事件） 451 452该示例为bindPopup通过配置onWillDismiss，实现当气泡退出时，拦截退出事件并执行回调函数。 453 454```ts 455// xxx.ets 456 457@Entry 458@Component 459struct PopupExample { 460 @State handlePopup: boolean = false; 461 build() { 462 Column() { 463 Button('PopupOptions') 464 .onClick(() => { 465 this.handlePopup = true; 466 }) 467 .bindPopup(this.handlePopup, { 468 message: 'This is a popup with PopupOptions', 469 messageOptions: { 470 textColor: Color.Red, 471 font: { 472 size: '14vp', 473 style: FontStyle.Italic, 474 weight: FontWeight.Bolder 475 } 476 }, 477 placement: Placement.Bottom, 478 enableArrow: false, 479 targetSpace: '15vp', 480 onStateChange: (e) => { 481 if (!e.isVisible) { 482 this.handlePopup = false; 483 } 484 }, 485 onWillDismiss: ( 486 (dismissPopupAction: DismissPopupAction) => { 487 console.info("dismissReason:" + JSON.stringify(dismissPopupAction.reason)); 488 if (dismissPopupAction.reason === DismissReason.PRESS_BACK) { 489 dismissPopupAction.dismiss(); 490 } 491 } 492 ) 493 }) 494 }.margin(20) 495 } 496} 497``` 498 499 500 501### 示例6（为气泡拦截退出事件） 502 503该示例通过配置onWillDismiss的boolean类型为false时，拦截气泡的退出事件。 504 505```ts 506// xxx.ets 507 508@Entry 509@Component 510struct PopupExample { 511 @State handlePopup: boolean = false; 512 513 build() { 514 Column() { 515 Button('PopupOptions') 516 .onClick(() => { 517 this.handlePopup = true; 518 }) 519 .bindPopup(this.handlePopup, { 520 message: 'This is a popup with PopupOptions', 521 messageOptions: { 522 textColor: Color.Red, 523 font: { 524 size: '14vp', 525 style: FontStyle.Italic, 526 weight: FontWeight.Bolder 527 } 528 }, 529 placement: Placement.Bottom, 530 enableArrow: false, 531 targetSpace: '15vp', 532 followTransformOfTarget: true, 533 onStateChange: (e) => { 534 let timer = setTimeout(() => { 535 this.handlePopup = false; 536 }, 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
