仓颉语言 ArkUI Popup 弹窗控制:bindPopup 通用属性详解与实战
仓颉语言 ArkUI Popup 弹窗控制:bindPopup 通用属性详解与实战
bindPopup 是仓颉语言 ArkUI 声明式 UI 框架中给任意组件绑定气泡弹窗(Popup)的通用属性接口,通过它可以在组件上显示带箭头指示的气泡提示、交互按钮或自定义内容,并精细控制弹窗的显示状态、位置、样式与关闭行为。本文以 cj-universal-attribute-popup.md 为主体,结合 cj-common-types.md 中 PopupOptions、CustomPopupOptions 等完整类型定义,系统讲解两种 bindPopup 重载的签名、全部配置参数的默认值与取值含义、状态回调与交互式关闭拦截,并逐段剖析官方示例代码,帮助开发者掌握在 OpenHarmony 应用中用仓颉语言实现高质量 Popup 弹窗的完整方案。
功能概述与适用场景
bindPopup 用于给组件绑定 Popup 弹窗,并设置弹窗内容、交互逻辑和显示状态。它属于通用属性(universal attribute),可链式作用于 Button、Text、Image 等任意组件实例,返回值为调用该接口的组件实例本身(类型 T),因此可以继续追加其他属性修饰。
典型适用场景包括:
- 表单控件上的校验提示气泡(如输入框聚焦时的错误/帮助文案);
- 按钮旁的操作菜单气泡(带主/次两个操作按钮);
- 需要跟随组件位置、带箭头指示的富文本或自定义 UI 气泡;
- 需要拦截"返回键退出""点击遮罩退出"等关闭行为,做二次确认或日志记录。
弹窗的显示状态在 onStateChange 事件回调中反馈,其显隐与组件的创建或销毁无强对应关系。特别注意:Popup 弹窗必须等待页面全部构建完成才能展示,因此 show 不能在页面构建中设置为 true,否则会导致弹窗显示位置及形状错误,初始值为 false。
导入模块与系统能力
在使用 bindPopup 前,需要在源文件中导入 ArkUI 能力包:
import kit.ArkUI.*
相关接口的系统能力为 SystemCapability.ArkUI.ArkUI.Full,起始版本为 22。即该能力需要设备/系统具备完整的 ArkUI 能力,且基于 API 22 及以上版本构建应用。
bindPopup 两种重载签名
形式一:绑定文本型气泡 bindPopup(?Bool, ?PopupOptions)
func bindPopup(show: ?Bool, popup: ?PopupOptions): T
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| show | ?Bool | 是 | - | 弹窗显示状态。popup 弹窗必须等待页面全部构建完成才能展示,因此 show 不能在页面构建中设置为 true,否则会导致 popup 弹窗显示位置及形状错误。 初始值:false。 |
| popup | ?PopupOptions | 是 | - | 配置当前弹窗提示的参数。 |
返回值:T,返回调用此接口的组件实例本身。
该形式适合纯文本提示场景:弹窗内容主要由 message 字段提供,可搭配主/次按钮、箭头、遮罩、动画等外观与行为配置。
形式二:绑定自定义内容气泡 bindPopup(?Bool, ?CustomPopupOptions)
func bindPopup(show: ?Bool, popup: ?CustomPopupOptions): T
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| show | ?Bool | 是 | - | 弹窗显示状态,约束同形式一。 |
| popup | ?CustomPopupOptions | 是 | - | 配置当前弹窗提示的参数。 |
返回值:T,返回调用此接口的组件实例本身。
该形式通过 builder 指定自定义内容构造器(@Builder 函数),适合在气泡内渲染任意组合的组件树,如带图标的富信息卡片、表单、列表等。
PopupOptions:文本型气泡的完整配置
PopupOptions 定义于 cj-common-types.md,构造函数签名如下(所有参数均为命名参数,未设置时使用默认值):
public init(
message!: ?String,
placement!: ?Placement = Option.None,
primaryButton!: ?PopupButton = None,
secondaryButton!: ?PopupButton = None,
onStateChange!: Option<(PopupStateChangeParam) -> Unit> = Option.None,
arrowOffset!: ?Length = None,
showInSubWindow!: ?Bool = None,
mask!: ?Color = None,
messageOptions!: ?PopupMessageOptions = None,
targetSpace!: ?Length = None,
enableArrow!: ?Bool = None,
offset!: ?Position = None,
popupColor!: ?Color = None,
autoCancel!: ?Bool = None,
width!: ?Length = None,
arrowPointPosition!: ?ArrowPointPosition = None,
arrowWidth!: ?Length = None,
arrowHeight!: ?Length = None,
radius!: ?Length = None,
shadow!: ?ShadowStyle = None,
backgroundBlurStyle!: ?BlurStyle = Option.None,
transition!: ?TransitionEffect = Option.None,
onWillDismiss!: Option<(DismissPopupAction) -> Unit> = None,
followTransformOfTarget!: ?Bool = None
)
参数说明与默认值速查表
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| message | ?String | -(必填) | 设置弹窗信息内容。 |
| placement | ?Placement | Option.None(即 Placement.Bottom) | 设置 popup 组件相对于目标的显示位置。 |
| primaryButton | ?PopupButton | None(即 PopupButton(value: "", action: {=>})) |
设置第一个按钮(主按钮)的文本与点击回调。 |
| secondaryButton | ?PopupButton | None(即 PopupButton(value: "", action: {=>})) |
设置第二个按钮(辅助按钮)的文本与点击回调。 |
| onStateChange | Option<(PopupStateChangeParam) -> Unit> | Option.None | 弹窗状态变化事件回调,参数为弹窗当前的显示状态。 |
| arrowOffset | ?Length | 0.vp | popup 箭头在弹窗处的偏移。箭头在气泡上下方时,数值为 0 表示箭头居最左侧,偏移量为箭头至最左侧的距离,默认居中;箭头在气泡左右侧时,偏移量为箭头至最上侧的距离,默认居中。如果显示在屏幕边缘,气泡会自动左右偏移,数值为 0 时箭头始终指向绑定组件。 |
| showInSubWindow | ?Bool | false | 是否在子窗口显示气泡。 |
| mask | ?Color | Color(0x1000000) | 设置遮罩层的颜色。 |
| messageOptions | ?PopupMessageOptions | PopupMessageOptions() | 设置弹窗信息文本参数(文本颜色与字体)。 |
| targetSpace | ?Length | 0.vp | 设置 popup 与目标的间隙。 |
| enableArrow | ?Bool | true | 是否显示箭头。当页面可用空间无法让气泡完全避让时,气泡会覆盖到组件上并且不显示箭头。 |
| offset | ?Position | Position(x: 0.0, y: 0.0) | 设置 popup 组件相对于 placement 设置的显示位置的偏移,不支持设置百分比。 |
| popupColor | ?Color | Color(0x1000000) | 设置提示气泡的颜色。如需去除模糊背景填充效果,需将 backgroundBlurStyle 设置为 BlurStyle.NONE。 |
| autoCancel | ?Bool | true | 页面有操作时,是否自动关闭气泡。 |
| width | ?Length | 0.vp | 设置弹出窗口的宽度。 |
| arrowPointPosition | ?ArrowPointPosition | None | 设置气泡尖角相对于父组件的显示位置,气泡尖角在垂直和水平方向上有 Start、Center、End 三个位置点可选,所有位置点均位于父组件区域范围内,不会超出父组件边界。 |
| arrowWidth | ?Length | 16.vp | 箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小,则不绘制气泡箭头。 |
| arrowHeight | ?Length | 8.vp | 箭头的高度。 |
| radius | ?Length | 20.vp | 弹出窗口的圆角。 |
| shadow | ?ShadowStyle | ShadowStyle.OuterDefaultMD | 设置气泡阴影样式。 |
| backgroundBlurStyle | ?BlurStyle | BlurStyle.ComponentUltraThick | 设置气泡模糊背景参数。 |
| transition | ?TransitionEffect | Option.None | 自定义 popup 弹窗显示和退出的动画效果。 |
| onWillDismiss | Option<(DismissPopupAction) -> Unit> | None | 设置拦截退出事件并执行回调函数,用于二次确认场景。 |
| followTransformOfTarget | ?Bool | None(false) | 气泡绑定的宿主组件或其父容器添加了旋转、缩放等变换时,设置气泡是否能显示在对应变化后的位置上。 |
关于 transition 的说明
transition 用于自定义弹窗的显示与退出动画。若不设置,则使用默认的显示/退出动效。需要注意两种按键交互:
- 显示动效中按 back 键,会打断显示动效并执行退出动效,动画效果为显示动效与退出动效的曲线叠加后的结果;
- 退出动效中按 back 键,不会打断退出动效,退出动效继续执行,back 键不被响应。
PopupButton:弹窗按钮
public class PopupButton {
public init(value!: ?String, action!: () -> Unit)
}
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | ?String | 是(命名参数) | 按钮的文本内容。 |
| action | () -> Unit | 是(命名参数) | 按钮的点击事件。 |
PopupMessageOptions:弹窗信息文本参数
public class PopupMessageOptions {
public var textColor: ?ResourceColor
public var font: ?Font
public init(textColor!: ?ResourceColor = None, font!: ?Font = None)
}
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| textColor | ?ResourceColor | Color(0x000000) | 弹窗信息文本颜色。 |
| font | ?Font | Font() | 弹窗信息字体属性,不支持设置 family。 |
CustomPopupOptions:自定义内容气泡的完整配置
CustomPopupOptions 定义于 cj-common-types.md,构造函数签名如下:
public init(
builder!: () -> Unit,
placement!: ?Placement = Option.None,
popupColor!: ?Color = None,
enableArrow!: ?Bool = None,
autoCancel!: ?Bool = None,
onStateChange!: Option<(PopupStateChangeParam) -> Unit> = Option.None,
showInSubWindow!: ?Bool = None,
backgroundColor!: ?Color = None,
arrowOffset!: ?Length = None,
mask!: ?Color = None,
targetSpace!: ?Length = None,
offset!: ?Position = None,
width!: ?Length = None,
arrowPointPosition!: ?ArrowPointPosition = None,
arrowWidth!: ?Length = None,
arrowHeight!: ?Length = None,
radius!: ?Length = None,
shadow!: ?ShadowStyle = None,
backgroundBlurStyle!: ?BlurStyle = Option.None,
focusable!: ?Bool = None,
transition!: Option<TransitionEffect> = Option.None,
onWillDismiss!: Option<(DismissPopupAction) -> Unit> = None,
followTransformOfTarget!: ?Bool = None
)
参数说明
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| builder | () -> Unit | -(必填,命名参数) | 提示气泡内容的构造器(@Builder 函数)。 |
| placement | ?Placement | Option.None(即 Placement.Bottom) | 气泡组件优先显示的位置,当前位置显示不下时,会自动调整位置。 |
| popupColor | ?Color | Color(0x1000000) | 提示气泡的背景颜色。 |
| enableArrow | ?Bool | true | 是否显示箭头。如果箭头所在方位侧的气泡长度不足以显示下箭头,则默认不显示箭头。例如 placement 设置为 Left,此时如果气泡高度小于箭头的宽度(32.vp)与气泡圆角两倍(48.vp)之和(80.vp),则实际不会显示箭头。 |
| autoCancel | ?Bool | true | 页面有操作时,是否自动关闭气泡。 |
| onStateChange | Option<(PopupStateChangeParam) -> Unit> | Option.None | 弹窗状态变化事件回调,参数为弹窗当前的显示状态。 |
| showInSubWindow | ?Bool | false | 是否在子窗口显示气泡。 |
| backgroundColor | ?Color | Color(0x1000000) | 提示气泡的背景颜色。 |
| arrowOffset | ?Length | 0.vp | popup 箭头在弹窗处的偏移,语义与 PopupOptions 中一致。 |
| mask | ?Color | None | 提示气泡遮罩层的颜色。 |
| targetSpace | ?Length | 0.vp | 设置 popup 与目标的间隙。 |
| offset | ?Position | None | popup 组件相对于 placement 设置位置的偏移,不支持设置百分比。 |
| width | ?Length | 0.vp | 弹窗宽度。showInSubWindow=true 时最大高度为设备屏幕高度,showInSubWindow=false 时最大高度为应用窗口高度;高度限定逻辑 = 最大高度 - 状态栏高度(没有时为 0) - dock 栏高度(没有时为 0) - 40VP - 40VP。 |
| arrowPointPosition | ?ArrowPointPosition | None | 气泡尖角相对于父组件的显示位置,同 PopupOptions。 |
| arrowWidth | ?Length | 16.vp | 箭头宽度。若所设置的箭头宽度超过所在边的长度减去两倍的气泡圆角大小,则不绘制气泡箭头。 |
| arrowHeight | ?Length | 16.vp | 箭头高度(注意与 PopupOptions 中默认 8.vp 的差异),不支持设置百分比。 |
| radius | ?Length | None | 弹出窗口的圆角。 |
| shadow | ?ShadowStyle | None | 弹出窗口阴影的样式。 |
| backgroundBlurStyle | ?BlurStyle | Option.None | 弹出窗口的背景模糊样式。 |
| focusable | ?Bool | None | 设置气泡弹出后是否获焦。 |
| transition | Option<TransitionEffect> | Option.None | 自定义 popup 弹窗显示和退出的动画效果。 |
| onWillDismiss | Option<(DismissPopupAction) -> Unit> | None | 设置拦截退出事件并执行回调函数。 |
| followTransformOfTarget | ?Bool | None | 气泡绑定的宿主组件或其父容器添加了旋转、缩放等变换时,气泡是否能显示在对应变化后的位置上。 |
builder 的约束与注意点
builder 是自定义气泡的核心,相关约束包括:
- Popup 为通用属性,自定义 Popup 中不支持再次弹出 Popup;
- 对 builder 下的第一层容器组件不支持使用 position 属性,如果使用将导致气泡不显示;
- builder 中若使用自定义组件,自定义组件的
aboutToAppear和aboutToDisappear生命周期与 popup 弹窗的显隐无关,不能使用其生命周期判断 popup 弹窗的显隐(弹窗显隐请依赖onStateChange回调)。
关键枚举与辅助类型
以下枚举与类型均定义于 cj-common-types.md,在配置 placement、arrowPointPosition、shadow、backgroundBlurStyle 及关闭拦截时会频繁使用。
Placement:气泡显示位置
public enum Placement <: Equatable<Placement> {
| Left
| Right
| Top
| Bottom
| TopLeft
| TopRight
| BottomLeft
| BottomRight
| LeftTop
| LeftBottom
| RightTop
| RightBottom
| None
| ...
}
各取值含义:
| 取值 | 含义 |
|---|---|
| Left / Right | 气泡位于组件左侧/右侧,与组件对应侧中心对齐 |
| Top / Bottom | 气泡位于组件上侧/下侧,与组件对应侧中心对齐 |
| TopLeft / TopRight | 气泡位于组件上侧,与组件左侧/右侧边缘对齐 |
| BottomLeft / BottomRight | 气泡位于组件下侧,与组件左侧/右侧边缘对齐 |
| LeftTop / LeftBottom | 气泡位于组件左侧,与组件上侧/下侧边缘对齐 |
| RightTop / RightBottom | 气泡位于组件右侧,与组件上侧/下侧边缘对齐 |
| None | 气泡提示位置无变化 |
ArrowPointPosition:箭头指向位置
public enum ArrowPointPosition <: Equatable<ArrowPointPosition> {
| Start
| Center
| End
| ...
}
| 取值 | 含义 |
|---|---|
| Start | 水平方向:位于父组件最左侧;垂直方向:位于父组件最上侧 |
| Center | 位于父组件居中位置 |
| End | 水平方向:位于父组件最右侧;垂直方向:位于父组件最下侧 |
DismissPopupAction 与 DismissReason:交互式关闭拦截
public class DismissPopupAction {
public let reason: DismissReason
public func dismiss(): Unit
}
DismissPopupAction 是 onWillDismiss 回调的入参:
reason(只读):返回本次拦截 popup 消失的事件原因,类型为DismissReason;dismiss():开发者确认需要退出页面时调用,主动关闭弹窗。
DismissReason 枚举定义:
| 取值 | 触发场景 |
|---|---|
| PressBack | 点击三键 back、左滑/右滑、键盘 ESC |
| TouchOutside | 点击遮罩层 |
| CloseButton | 点击了关闭按钮 |
| SlideDown | 下拉关闭 |
注意:在 onWillDismiss 回调中,不能再做 onWillDismiss 拦截,避免递归拦截导致行为异常。
阴影与模糊背景样式
shadow使用ShadowStyle枚举,PopupOptions 的默认值为ShadowStyle.OuterDefaultMD,示例中使用ShadowStyle.OuterDefaultSM等系统预置阴影档位;backgroundBlurStyle使用BlurStyle枚举,默认值为BlurStyle.ComponentUltraThick。当需要纯色气泡、去除模糊背景填充效果时,应显式设置为BlurStyle.NONE。
完整示例代码与逐段解析
官方示例(见 cj-universal-attribute-popup.md)完整演示了两种 bindPopup 用法,下面给出完整代码并逐段说明。
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_management.*
import ohos.arkui.state_macro_manage.*
import ohos.base.*
import ohos.arkui.component.common.Font as CommonFont
@Builder
func popupBuilder() {
Column {
Text("Custom Popup")
}
}
@Entry
@Component
class EntryView {
@State var msg: String = "State Change Wait"
@State var dismiss: String = "Dismiss Wait"
@State var custom: String = "Custom Wait"
@State var handlePopup: Bool = false
@State var customPopup: Bool = false
public func build() {
Flex(direction: FlexDirection.Column) {
Text(msg)
Text(dismiss)
Text(custom)
Button('PopupOptions')
.margin(top: 200)
.onClick({ e =>
this.handlePopup = !this.handlePopup
})
.bindPopup(
this.handlePopup,
PopupOptions(
message: 'This is a popup with PopupOptions',
primaryButton: PopupButton(
value: 'confirm',
action: {
=> this.handlePopup = !this.handlePopup
}
),
secondaryButton: PopupButton(
value: 'cancel',
action: {
=> this.handlePopup = !this.handlePopup
}
),
onStateChange: {
e =>
this.msg = "PopUp"
if (!e.isVisible) {
this.msg = "Wait"
this.handlePopup = false
}
},
showInSubWindow: false,
arrowOffset: 60.0.vp,
targetSpace: 20.0.vp,
enableArrow: true,
arrowHeight: 30.0.vp,
arrowWidth: 30.0.vp,
radius: 25.0.vp,
autoCancel: true,
backgroundBlurStyle: BlurStyle.Thick,
shadow: ShadowStyle.OuterDefaultSM,
offset: Position(x: 50.0, y: 50.0),
placement: Placement.Top,
arrowPointPosition: ArrowPointPosition.Center,
mask: Color(0x33000000),
popupColor: Color.Green,
messageOptions: PopupMessageOptions(textColor: Color.Blue, font: CommonFont(size: 20.vp)),
transition: TransitionEffect.SLIDE_SWITCH,
onWillDismiss: {
dismissPopupAction: DismissPopupAction =>
dismissPopupAction.dismiss()
match (dismissPopupAction.reason) {
case PRESS_BACK => this.dismiss = "dismissReason: PRESS_BACK"
case TOUCH_OUTSIDE => this.dismiss = "dismissReason: TOUCH_OUTSIDE"
case _ => this.dismiss = "dismissReason: unknown"
}
},
followTransformOfTarget: true
)
)
Button("CustomPopupOptions")
.onClick({ e => customPopup = !customPopup})
.bindPopup(
customPopup,
CustomPopupOptions(
builder: bind(popupBuilder, this),
enableArrow: true,
placement: Placement.BottomLeft,
popupColor: Color.Red,
arrowHeight: 24.0.vp,
arrowWidth: 24.0.vp,
radius: 10.vp,
offset: Position(x: 5.0, y: 5.0),
width: 300.vp,
autoCancel: true,
targetSpace: 10.vp,
arrowOffset: 5.vp,
focusable: true,
arrowPointPosition: ArrowPointPosition.Center,
transition: TransitionEffect.SLIDE_SWITCH,
onStateChange: {
evt =>
custom = "stateChange: ${evt.isVisible}"
if (!evt.isVisible) {
customPopup = true
}
}
)
)
}
}
}
代码要点解析
-
状态驱动显隐:
handlePopup与customPopup两个@State变量作为show参数传入bindPopup,按钮的onClick中对其取反,即可实现点击弹出/再次点击关闭的双向切换。 -
onStateChange 同步 UI 状态:
PopupOptions分支中,弹窗可见时msg置为"PopUp";当e.isVisible变为false(如点击遮罩、back 键等导致关闭)时,将msg恢复为"Wait"并同步把handlePopup置回false,保证状态变量的值与弹窗实际显隐一致。这是文档强调"popup 弹窗的显示状态在 onStateChange 事件回调中反馈"的直接体现。 -
onWillDismiss 交互式关闭拦截:注册回调后,弹窗不会立刻关闭,而是由开发者根据
dismissPopupAction.reason判断关闭原因(PRESS_BACK、TOUCH_OUTSIDE或其他),记录到dismiss文本后调用dismissPopupAction.dismiss()完成关闭。这正是DismissReason枚举在实际业务中的典型用法,适合在关闭前做统计埋点或二次确认。 -
外观参数全覆盖:示例同时设置了
arrowOffset、targetSpace、enableArrow、arrowHeight/arrowWidth、radius、autoCancel、backgroundBlurStyle(BlurStyle.Thick)、shadow(ShadowStyle.OuterDefaultSM)、offset、placement(Placement.Top)、arrowPointPosition(ArrowPointPosition.Center)、mask、popupColor、messageOptions(自定义文本颜色与字号)、transition(TransitionEffect.SLIDE_SWITCH)与followTransformOfTarget,基本覆盖了 PopupOptions 参数速查表 中的全部可调项。 -
自定义气泡构建:
@Builder func popupBuilder()定义气泡内容,CustomPopupOptions(builder: bind(popupBuilder, this), ...)通过bind将 builder 绑定到当前组件实例,并在气泡内弹出后通过onStateChange将custom文本更新为"stateChange: true/false",展示自定义 Popup 的状态联动方式。 -
注意 CustomPopupOptions 与 PopupOptions 的差异:自定义形式没有
message/primaryButton/secondaryButton/messageOptions,取而代之的是builder与backgroundColor、focusable;在CustomPopupOptions中arrowHeight默认值为 16.vp(而PopupOptions为 8.vp),配置箭头尺寸时需留意。
实战避坑清单
综合文档说明与 cj-common-types.md 的类型约束,使用 bindPopup 时需重点注意:
- 不要在页面构建期置 show 为 true:popup 必须等待页面全部构建完成才能展示,构建期直接置
true会导致弹窗显示位置及形状错误; - 显隐状态回写:通过
onStateChange的e.isVisible及时同步show状态变量,避免状态与弹窗实际显隐脱节; - onWillDismiss 内部不可再拦截:回调中不要再注册
onWillDismiss拦截;确认关闭后务必调用dismissPopupAction.dismiss(),否则弹窗不会消失; - 箭头显示的条件限制:气泡空间不足以容纳箭头(如
placement为Left时气泡高度小于箭头宽与两倍圆角之和)时,箭头不会显示,属预期行为; - 自定义 Popup 的布局约束:builder 第一层容器组件不可使用
position属性,且自定义 Popup 内不能再嵌套弹出 Popup; - 模糊背景与纯色的取舍:需要纯色气泡时,将
backgroundBlurStyle显式设为BlurStyle.NONE,否则默认的BlurStyle.ComponentUltraThick等模糊样式会影响popupColor的呈现效果; - 弹窗显隐不等同于组件生命周期:自定义组件在 builder 中的
aboutToAppear/aboutToDisappear与弹窗显隐无关,判断显隐应统一依赖onStateChange。
通过本文覆盖的两种 bindPopup 重载、PopupOptions/CustomPopupOptions 全部参数、Placement/ArrowPointPosition/DismissReason 等关键枚举以及官方完整示例,开发者即可在仓颉语言 ArkUI 应用中灵活实现从简单文本提示到复杂自定义交互气泡的各类 Popup 场景。