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