鸿蒙5.0版开发：ArkTS组件通用属性-Popup控制

最新推荐文章于 2025-07-30 10:34:50 发布

原创

最新推荐文章于 2025-07-30 10:34:50 发布 · 726 阅读

27 ·

CC 4.0 BY-SA版权

文章标签：

#1024程序员节 #harmonyos #华为 #android #ArkTS #鸿蒙 #前端

往期鸿蒙全套实战文章必看：

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弹窗显示位置及形状错误。
popup	PopupOptions \| CustomPopupOptions8+	是	配置弹出弹窗的参数。

PopupOptions类型说明

名称	类型	必填	描述
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	否	popup箭头在弹窗处的偏移。箭头在气泡上下方时，数值为0表示箭头居最左侧，偏移量为箭头至最左侧的距离，默认居中。箭头在气泡左右侧时，偏移量为箭头至最上侧的距离，默认居中。如果显示在屏幕边缘，气泡会自动左右偏移，数值为0时箭头始终指向绑定组件。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
showInSubWindow9+	boolean	否	是否在子窗口显示气泡，默认值为false。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
mask10+	boolean \| { color : ResourceColor }	否	设置气泡是否有遮罩层及遮罩颜色。如果设置为false，则没有遮罩层；如果设置为true，则设置有遮罩层并且颜色为透明色；如果设置为Color，则为遮罩层的颜色。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
messageOptions10+	PopupMessageOptions	否	设置弹窗信息文本参数。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
targetSpace10+	Length	否	设置popup与目标的间隙。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
placement10+	Placement	否	设置popup组件相对于目标的显示位置，默认值为Placement.Bottom。如果同时设置了`placementOnTop`和`placement`，则以`placement`的设置生效。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
offset10+	Position	否	设置popup组件相对于placement设置的显示位置的偏移。说明：不支持设置百分比。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
enableArrow10+	boolean	否	设置是否显示箭头。默认值：true 说明：当页面可用空间无法让气泡完全避让时，气泡会覆盖到组件上并且不显示箭头。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
popupColor11+