文章目录核心特性一、核心 API 速览1.1 bindPopup 方法1.2 PopupOptions基础文本气泡1.3 CustomPopupOptions自定义内容气泡二、完整代码示例与详解示例详解1. 基础文本气泡2. 自定义样式气泡3. 自定义内容气泡4. 自定义动效气泡5. 退出事件拦截气泡6. 渐变描边气泡API 20总结Popup 是 ArkUI 提供的通用属性用于为组件绑定弹出式气泡支持文本提示、自定义内容、样式定制、动效配置等能力从 API version 7 开始支持是实现用户引导、操作提示、详情展示等场景的核心组件。核心特性双模式支持基础文本气泡PopupOptions与自定义内容气泡CustomPopupOptions。丰富样式定制支持箭头、圆角、阴影、背景色、描边渐变等全方位样式配置。交互与动效支持显隐动效、退出事件拦截、状态监听等交互能力。版本兼容高版本 API如 API 12 动效、API 20 渐变描边均有兼容说明。一、核心 API 速览1.1bindPopup方法为组件绑定 Popup 气泡是使用 Popup 的核心入口。bindPopup(show:boolean,popup:PopupOptions|CustomPopupOptions):T参数名类型必填说明showboolean是气泡显隐状态true显示false隐藏。注意不能在页面构建中直接设为true需等待页面构建完成。popupPopupOptions|CustomPopupOptions是气泡配置参数区分基础文本模式和自定义内容模式。1.2PopupOptions基础文本气泡用于配置仅展示文本和按钮的基础气泡核心参数如下参数名类型说明最低 API 版本messagestring气泡文本内容必填。7placementPlacement气泡显示位置默认Placement.Bottom。10primaryButton{value: string, action: () void}主按钮配置。7secondaryButton{value: string, action: () void}辅助按钮配置。7messageOptionsPopupMessageOptions文本样式配置颜色、字体等。10enableArrowboolean是否显示箭头默认true。10arrowWidth/arrowHeightDimension箭头宽度/高度。11popupColorResourceColor气泡背景色。11radiusDimension气泡圆角半径。11shadowShadowOptions|ShadowStyle气泡阴影。11transitionTransitionEffect显隐动效配置。12onWillDismissboolean|CallbackDismissPopupAction退出事件拦截。12outlineLinearGradient/borderLinearGradientPopupBorderLinearGradient内外描边渐变。201.3CustomPopupOptions自定义内容气泡用于通过Builder自定义气泡内容核心参数如下参数名类型说明最低 API 版本builderCustomBuilder自定义内容构造器必填用Builder装饰。8placementPlacement气泡显示位置默认Placement.Bottom。8popupColorResourceColor气泡背景色。8enableArrowboolean是否显示箭头默认true。8autoCancelboolean点击外部是否自动关闭默认true。8maskboolean|{color: ResourceColor}遮罩层配置。10二、完整代码示例与详解以下代码基于官方文档扩展覆盖 6 大核心场景可直接复制运行。EntryComponentstruct PopupFullExample{// ************************* 气泡显隐状态变量 *************************StatebasePopupShow:booleanfalse;// 基础文本气泡StatestylePopupShow:booleanfalse;// 自定义样式气泡StatecustomPopupShow:booleanfalse;// 自定义内容气泡StatetransitionPopupShow:booleanfalse;// 自定义动效气泡StateinterceptPopupShow:booleanfalse;// 退出事件拦截气泡StategradientPopupShow:booleanfalse;// 渐变描边气泡(API20)// ************************* 自定义气泡内容构造器 *************************BuildercustomPopupBuilder(){Column({space:12}){Row({space:8}){// 示例图标使用系统公共图标也可替换为 $r(app.media.xxx)Image($r(sys.media.ohos_ic_public_albums)).width(24).height(24).objectFit(ImageFit.Contain)Text(自定义气泡标题).fontSize(16).fontWeight(FontWeight.Medium).fontColor(#181818)}.width(100%).justifyContent(FlexAlign.Start)Text(这是通过CustomPopupOptions实现的自定义内容气泡支持任意布局组件可自由定制宽高、样式、交互).fontSize(14).fontColor(#666666).maxLines(2).width(100%)Row({space:10}){Button(取消).width(80).height(32).fontSize(14).backgroundColor(#F5F5F5).fontColor(#333333).onClick((){this.customPopupShowfalse;})Button(确认).width(80).height(32).fontSize(14).backgroundColor(#007DFF).fontColor(Color.White).onClick((){this.customPopupShowfalse;console.info(自定义气泡确认按钮点击);})}.width(100%).justifyContent(FlexAlign.End)}.width(280).padding(16)}build(){Scroll(){Column({space:20}){// ************************* 示例1基础文本气泡 *************************Button(基础文本气泡).width(90%).height(48).fontSize(16).onClick((){this.basePopupShow!this.basePopupShow;}).bindPopup(this.basePopupShow,{message:这是基础Popup气泡支持主副按钮、状态监听、位置定制,placement:Placement.Top,targetSpace:12,enableArrow:true,mask:false,autoCancel:true,keyboardAvoidMode:KeyboardAvoidMode.DEFAULT,primaryButton:{value:确认,action:(){this.basePopupShowfalse;}},secondaryButton:{value:取消,action:(){this.basePopupShowfalse;}},onStateChange:(event){if(!event.isVisible){this.basePopupShowfalse;}}})// ************************* 示例2自定义样式气泡 *************************Button(自定义样式气泡).width(90%).height(48).fontSize(16).onClick((){this.stylePopupShow!this.stylePopupShow;}).bindPopup(this.stylePopupShow,{message:自定义样式气泡可定制箭头、圆角、阴影、背景、文本样式,placement:Placement.Bottom,messageOptions:{textColor:Color.White,font:{size:14,weight:FontWeight.Medium}},enableArrow:true,arrowWidth:20,arrowHeight:10,arrowPointPosition:ArrowPointPosition.CENTER,width:260,radius:16,popupColor:#007DFF,backgroundBlurStyle:BlurStyle.NONE,shadow:ShadowStyle.OUTER_DEFAULT_LG,onStateChange:(event){if(!event.isVisible){this.stylePopupShowfalse;}}})// ************************* 示例3自定义内容气泡 *************************Button(自定义内容气泡).width(90%).height(48).fontSize(16).onClick((){this.customPopupShow!this.customPopupShow;}).bindPopup(this.customPopupShow,{builder:this.customPopupBuilder,placement:Placement.Right,enableArrow:true,mask:{color:#33000000},popupColor:Color.White,autoCancel:false,targetSpace:10,onStateChange:(event){if(!event.isVisible){this.customPopupShowfalse;}}})// ************************* 示例4自定义动效气泡 *************************Button(自定义动效气泡).width(90%).height(48).fontSize(16).onClick((){this.transitionPopupShow!this.transitionPopupShow;}).bindPopup(this.transitionPopupShow,{message:自定义显隐动效气泡支持透明度、平移、缩放等组合动效,placement:Placement.Top,width:240,transition:TransitionEffect.asymmetric(TransitionEffect.OPACITY.animation({duration:600,curve:Curve.EaseInOut}).combine(TransitionEffect.translate({x:0,y:-20})),TransitionEffect.scale({x:0.5,y:0.5}).animation({duration:400,curve:Curve.EaseIn}).combine(TransitionEffect.OPACITY)),onStateChange:(event){if(!event.isVisible){this.transitionPopupShowfalse;}}})// ************************* 示例5退出事件拦截气泡 *************************Button(退出事件拦截气泡).width(90%).height(48).fontSize(16).onClick((){this.interceptPopupShowtrue;}).bindPopup(this.interceptPopupShow,{message:拦截退出事件气泡仅允许back键关闭点击遮罩/外部无法关闭,placement:Placement.Bottom,width:260,enableArrow:true,mask:true,onWillDismiss:(dismissPopupAction){console.info(气泡关闭原因Code${dismissPopupAction.reason});// 0 对应 DismissReason.PRESS_BACK (Back键/侧滑)// 1 对应 TOUCH_OUTSIDE (点击遮罩)if(dismissPopupAction.reason0){dismissPopupAction.dismiss();this.interceptPopupShowfalse;}},onStateChange:(event){if(!event.isVisible){this.interceptPopupShowfalse;}}})// ************************* 示例6渐变描边气泡 *************************Button(渐变描边气泡(API20)).width(90%).height(48).fontSize(16).onClick((){this.gradientPopupShow!this.gradientPopupShow;}).bindPopup(this.gradientPopupShow,{message:API20 新增特性气泡内外描边线性渐变效果,placement:Placement.Top,width:260,radius:12,outlineWidth:2,outlineLinearGradient:{direction:GradientDirection.Right,colors:[[Color.Yellow,0.0],[Color.Green,1.0]]},borderWidth:2,borderLinearGradient:{direction:GradientDirection.Left,colors:[[Color.Red,0.0],[Color.Blue,1.0]]},onStateChange:(event){if(!event.isVisible){this.gradientPopupShowfalse;}}})}.width(100%).padding({top:50,bottom:50}).alignItems(HorizontalAlign.Center)}.width(100%).height(100%).backgroundColor(#F8F8F8)}}运行结果如图示例详解1. 基础文本气泡展示最基础的文本提示气泡包含主副按钮、位置配置、状态监听。核心配置message文本内容、primaryButton/secondaryButton按钮、onStateChange显隐监听。关键逻辑通过onStateChange同步状态变量避免变量与气泡显隐不一致。2. 自定义样式气泡全方位定制气泡外观包括文本样式、箭头、圆角、背景色、阴影。核心配置messageOptions文本样式、arrowWidth/arrowHeight箭头尺寸、popupColor背景色、shadow阴影。适配说明backgroundBlurStyle: BlurStyle.NONE用于关闭默认模糊背景突出自定义背景色。3. 自定义内容气泡通过Builder构造器完全自定义气泡内容支持图片、文本、按钮等任意布局。核心配置builder自定义构造器、autoCancel: false禁止点击外部关闭。避坑说明builder下的第一层容器组件不支持使用position属性否则会导致气泡不显示。4. 自定义动效气泡通过TransitionEffect定制气泡的显示和退出动效支持不对称动效。核心配置transition动效配置使用asymmetric分别定义显示和退出动效。动效组合通过combine组合透明度、平移、缩放等动效实现丰富的视觉效果。5. 退出事件拦截气泡通过onWillDismiss拦截气泡退出事件仅允许特定方式如 Back 键关闭气泡。核心配置onWillDismiss拦截回调通过reason判断关闭原因0为 Back 键1为点击遮罩。关键逻辑仅在reason 0时调用dismiss()否则拦截退出。6. 渐变描边气泡API 20利用 API 20 新特性为气泡添加内外描边的线性渐变效果。核心配置outlineWidth/borderWidth描边宽度、outlineLinearGradient/borderLinearGradient渐变配置。版本兼容需在 HarmonyOS 5.0.0.200 版本设备上运行低版本可注释对应代码。总结Popup 气泡组件是 HarmonyOS ArkUI 中实现用户交互提示的核心工具通过PopupOptions和CustomPopupOptions可覆盖从简单文本到复杂自定义内容的全场景需求。本文结合官方文档与完整代码详细讲解了其核心 API、样式定制、动效配置、事件拦截等能力并提供了实用的避坑指南帮助开发者快速上手并高效使用 Popup 组件。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力
HarmonyOS6 ArkTS Popup 气泡组件指南
文章目录核心特性一、核心 API 速览1.1 bindPopup 方法1.2 PopupOptions基础文本气泡1.3 CustomPopupOptions自定义内容气泡二、完整代码示例与详解示例详解1. 基础文本气泡2. 自定义样式气泡3. 自定义内容气泡4. 自定义动效气泡5. 退出事件拦截气泡6. 渐变描边气泡API 20总结Popup 是 ArkUI 提供的通用属性用于为组件绑定弹出式气泡支持文本提示、自定义内容、样式定制、动效配置等能力从 API version 7 开始支持是实现用户引导、操作提示、详情展示等场景的核心组件。核心特性双模式支持基础文本气泡PopupOptions与自定义内容气泡CustomPopupOptions。丰富样式定制支持箭头、圆角、阴影、背景色、描边渐变等全方位样式配置。交互与动效支持显隐动效、退出事件拦截、状态监听等交互能力。版本兼容高版本 API如 API 12 动效、API 20 渐变描边均有兼容说明。一、核心 API 速览1.1bindPopup方法为组件绑定 Popup 气泡是使用 Popup 的核心入口。bindPopup(show:boolean,popup:PopupOptions|CustomPopupOptions):T参数名类型必填说明showboolean是气泡显隐状态true显示false隐藏。注意不能在页面构建中直接设为true需等待页面构建完成。popupPopupOptions|CustomPopupOptions是气泡配置参数区分基础文本模式和自定义内容模式。1.2PopupOptions基础文本气泡用于配置仅展示文本和按钮的基础气泡核心参数如下参数名类型说明最低 API 版本messagestring气泡文本内容必填。7placementPlacement气泡显示位置默认Placement.Bottom。10primaryButton{value: string, action: () void}主按钮配置。7secondaryButton{value: string, action: () void}辅助按钮配置。7messageOptionsPopupMessageOptions文本样式配置颜色、字体等。10enableArrowboolean是否显示箭头默认true。10arrowWidth/arrowHeightDimension箭头宽度/高度。11popupColorResourceColor气泡背景色。11radiusDimension气泡圆角半径。11shadowShadowOptions|ShadowStyle气泡阴影。11transitionTransitionEffect显隐动效配置。12onWillDismissboolean|CallbackDismissPopupAction退出事件拦截。12outlineLinearGradient/borderLinearGradientPopupBorderLinearGradient内外描边渐变。201.3CustomPopupOptions自定义内容气泡用于通过Builder自定义气泡内容核心参数如下参数名类型说明最低 API 版本builderCustomBuilder自定义内容构造器必填用Builder装饰。8placementPlacement气泡显示位置默认Placement.Bottom。8popupColorResourceColor气泡背景色。8enableArrowboolean是否显示箭头默认true。8autoCancelboolean点击外部是否自动关闭默认true。8maskboolean|{color: ResourceColor}遮罩层配置。10二、完整代码示例与详解以下代码基于官方文档扩展覆盖 6 大核心场景可直接复制运行。EntryComponentstruct PopupFullExample{// ************************* 气泡显隐状态变量 *************************StatebasePopupShow:booleanfalse;// 基础文本气泡StatestylePopupShow:booleanfalse;// 自定义样式气泡StatecustomPopupShow:booleanfalse;// 自定义内容气泡StatetransitionPopupShow:booleanfalse;// 自定义动效气泡StateinterceptPopupShow:booleanfalse;// 退出事件拦截气泡StategradientPopupShow:booleanfalse;// 渐变描边气泡(API20)// ************************* 自定义气泡内容构造器 *************************BuildercustomPopupBuilder(){Column({space:12}){Row({space:8}){// 示例图标使用系统公共图标也可替换为 $r(app.media.xxx)Image($r(sys.media.ohos_ic_public_albums)).width(24).height(24).objectFit(ImageFit.Contain)Text(自定义气泡标题).fontSize(16).fontWeight(FontWeight.Medium).fontColor(#181818)}.width(100%).justifyContent(FlexAlign.Start)Text(这是通过CustomPopupOptions实现的自定义内容气泡支持任意布局组件可自由定制宽高、样式、交互).fontSize(14).fontColor(#666666).maxLines(2).width(100%)Row({space:10}){Button(取消).width(80).height(32).fontSize(14).backgroundColor(#F5F5F5).fontColor(#333333).onClick((){this.customPopupShowfalse;})Button(确认).width(80).height(32).fontSize(14).backgroundColor(#007DFF).fontColor(Color.White).onClick((){this.customPopupShowfalse;console.info(自定义气泡确认按钮点击);})}.width(100%).justifyContent(FlexAlign.End)}.width(280).padding(16)}build(){Scroll(){Column({space:20}){// ************************* 示例1基础文本气泡 *************************Button(基础文本气泡).width(90%).height(48).fontSize(16).onClick((){this.basePopupShow!this.basePopupShow;}).bindPopup(this.basePopupShow,{message:这是基础Popup气泡支持主副按钮、状态监听、位置定制,placement:Placement.Top,targetSpace:12,enableArrow:true,mask:false,autoCancel:true,keyboardAvoidMode:KeyboardAvoidMode.DEFAULT,primaryButton:{value:确认,action:(){this.basePopupShowfalse;}},secondaryButton:{value:取消,action:(){this.basePopupShowfalse;}},onStateChange:(event){if(!event.isVisible){this.basePopupShowfalse;}}})// ************************* 示例2自定义样式气泡 *************************Button(自定义样式气泡).width(90%).height(48).fontSize(16).onClick((){this.stylePopupShow!this.stylePopupShow;}).bindPopup(this.stylePopupShow,{message:自定义样式气泡可定制箭头、圆角、阴影、背景、文本样式,placement:Placement.Bottom,messageOptions:{textColor:Color.White,font:{size:14,weight:FontWeight.Medium}},enableArrow:true,arrowWidth:20,arrowHeight:10,arrowPointPosition:ArrowPointPosition.CENTER,width:260,radius:16,popupColor:#007DFF,backgroundBlurStyle:BlurStyle.NONE,shadow:ShadowStyle.OUTER_DEFAULT_LG,onStateChange:(event){if(!event.isVisible){this.stylePopupShowfalse;}}})// ************************* 示例3自定义内容气泡 *************************Button(自定义内容气泡).width(90%).height(48).fontSize(16).onClick((){this.customPopupShow!this.customPopupShow;}).bindPopup(this.customPopupShow,{builder:this.customPopupBuilder,placement:Placement.Right,enableArrow:true,mask:{color:#33000000},popupColor:Color.White,autoCancel:false,targetSpace:10,onStateChange:(event){if(!event.isVisible){this.customPopupShowfalse;}}})// ************************* 示例4自定义动效气泡 *************************Button(自定义动效气泡).width(90%).height(48).fontSize(16).onClick((){this.transitionPopupShow!this.transitionPopupShow;}).bindPopup(this.transitionPopupShow,{message:自定义显隐动效气泡支持透明度、平移、缩放等组合动效,placement:Placement.Top,width:240,transition:TransitionEffect.asymmetric(TransitionEffect.OPACITY.animation({duration:600,curve:Curve.EaseInOut}).combine(TransitionEffect.translate({x:0,y:-20})),TransitionEffect.scale({x:0.5,y:0.5}).animation({duration:400,curve:Curve.EaseIn}).combine(TransitionEffect.OPACITY)),onStateChange:(event){if(!event.isVisible){this.transitionPopupShowfalse;}}})// ************************* 示例5退出事件拦截气泡 *************************Button(退出事件拦截气泡).width(90%).height(48).fontSize(16).onClick((){this.interceptPopupShowtrue;}).bindPopup(this.interceptPopupShow,{message:拦截退出事件气泡仅允许back键关闭点击遮罩/外部无法关闭,placement:Placement.Bottom,width:260,enableArrow:true,mask:true,onWillDismiss:(dismissPopupAction){console.info(气泡关闭原因Code${dismissPopupAction.reason});// 0 对应 DismissReason.PRESS_BACK (Back键/侧滑)// 1 对应 TOUCH_OUTSIDE (点击遮罩)if(dismissPopupAction.reason0){dismissPopupAction.dismiss();this.interceptPopupShowfalse;}},onStateChange:(event){if(!event.isVisible){this.interceptPopupShowfalse;}}})// ************************* 示例6渐变描边气泡 *************************Button(渐变描边气泡(API20)).width(90%).height(48).fontSize(16).onClick((){this.gradientPopupShow!this.gradientPopupShow;}).bindPopup(this.gradientPopupShow,{message:API20 新增特性气泡内外描边线性渐变效果,placement:Placement.Top,width:260,radius:12,outlineWidth:2,outlineLinearGradient:{direction:GradientDirection.Right,colors:[[Color.Yellow,0.0],[Color.Green,1.0]]},borderWidth:2,borderLinearGradient:{direction:GradientDirection.Left,colors:[[Color.Red,0.0],[Color.Blue,1.0]]},onStateChange:(event){if(!event.isVisible){this.gradientPopupShowfalse;}}})}.width(100%).padding({top:50,bottom:50}).alignItems(HorizontalAlign.Center)}.width(100%).height(100%).backgroundColor(#F8F8F8)}}运行结果如图示例详解1. 基础文本气泡展示最基础的文本提示气泡包含主副按钮、位置配置、状态监听。核心配置message文本内容、primaryButton/secondaryButton按钮、onStateChange显隐监听。关键逻辑通过onStateChange同步状态变量避免变量与气泡显隐不一致。2. 自定义样式气泡全方位定制气泡外观包括文本样式、箭头、圆角、背景色、阴影。核心配置messageOptions文本样式、arrowWidth/arrowHeight箭头尺寸、popupColor背景色、shadow阴影。适配说明backgroundBlurStyle: BlurStyle.NONE用于关闭默认模糊背景突出自定义背景色。3. 自定义内容气泡通过Builder构造器完全自定义气泡内容支持图片、文本、按钮等任意布局。核心配置builder自定义构造器、autoCancel: false禁止点击外部关闭。避坑说明builder下的第一层容器组件不支持使用position属性否则会导致气泡不显示。4. 自定义动效气泡通过TransitionEffect定制气泡的显示和退出动效支持不对称动效。核心配置transition动效配置使用asymmetric分别定义显示和退出动效。动效组合通过combine组合透明度、平移、缩放等动效实现丰富的视觉效果。5. 退出事件拦截气泡通过onWillDismiss拦截气泡退出事件仅允许特定方式如 Back 键关闭气泡。核心配置onWillDismiss拦截回调通过reason判断关闭原因0为 Back 键1为点击遮罩。关键逻辑仅在reason 0时调用dismiss()否则拦截退出。6. 渐变描边气泡API 20利用 API 20 新特性为气泡添加内外描边的线性渐变效果。核心配置outlineWidth/borderWidth描边宽度、outlineLinearGradient/borderLinearGradient渐变配置。版本兼容需在 HarmonyOS 5.0.0.200 版本设备上运行低版本可注释对应代码。总结Popup 气泡组件是 HarmonyOS ArkUI 中实现用户交互提示的核心工具通过PopupOptions和CustomPopupOptions可覆盖从简单文本到复杂自定义内容的全场景需求。本文结合官方文档与完整代码详细讲解了其核心 API、样式定制、动效配置、事件拦截等能力并提供了实用的避坑指南帮助开发者快速上手并高效使用 Popup 组件。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力
