仓颉语言 ArkUI Popup 弹窗控制:bindPopup 通用属性详解与实战

原创2026-10-15 21:26:141,337 阅读
文章标签:文档知识库

仓颉语言 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
                            }
                        }
                    )
                )
        }
    }
}

代码要点解析

  1. 状态驱动显隐:handlePopup 与 customPopup 两个 @State 变量作为 show 参数传入 bindPopup,按钮的 onClick 中对其取反,即可实现点击弹出/再次点击关闭的双向切换。

  2. onStateChange 同步 UI 状态:PopupOptions 分支中,弹窗可见时 msg 置为 "PopUp";当 e.isVisible 变为 false(如点击遮罩、back 键等导致关闭)时,将 msg 恢复为 "Wait" 并同步把 handlePopup 置回 false,保证状态变量的值与弹窗实际显隐一致。这是文档强调"popup 弹窗的显示状态在 onStateChange 事件回调中反馈"的直接体现。

  3. onWillDismiss 交互式关闭拦截:注册回调后,弹窗不会立刻关闭,而是由开发者根据 dismissPopupAction.reason 判断关闭原因(PRESS_BACK、TOUCH_OUTSIDE 或其他),记录到 dismiss 文本后调用 dismissPopupAction.dismiss() 完成关闭。这正是 DismissReason 枚举在实际业务中的典型用法,适合在关闭前做统计埋点或二次确认。

  4. 外观参数全覆盖:示例同时设置了 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 参数速查表 中的全部可调项。

  5. 自定义气泡构建:@Builder func popupBuilder() 定义气泡内容,CustomPopupOptions(builder: bind(popupBuilder, this), ...) 通过 bind 将 builder 绑定到当前组件实例,并在气泡内弹出后通过 onStateChange 将 custom 文本更新为 "stateChange: true/false",展示自定义 Popup 的状态联动方式。

  6. 注意 CustomPopupOptions 与 PopupOptions 的差异:自定义形式没有 message/primaryButton/secondaryButton/messageOptions,取而代之的是 builder 与 backgroundColor、focusable;在 CustomPopupOptions 中 arrowHeight 默认值为 16.vp(而 PopupOptions 为 8.vp),配置箭头尺寸时需留意。

实战避坑清单

综合文档说明与 cj-common-types.md 的类型约束,使用 bindPopup 时需重点注意:

  1. 不要在页面构建期置 show 为 true:popup 必须等待页面全部构建完成才能展示,构建期直接置 true 会导致弹窗显示位置及形状错误;
  2. 显隐状态回写:通过 onStateChange 的 e.isVisible 及时同步 show 状态变量,避免状态与弹窗实际显隐脱节;
  3. onWillDismiss 内部不可再拦截:回调中不要再注册 onWillDismiss 拦截;确认关闭后务必调用 dismissPopupAction.dismiss(),否则弹窗不会消失;
  4. 箭头显示的条件限制:气泡空间不足以容纳箭头(如 placement 为 Left 时气泡高度小于箭头宽与两倍圆角之和)时,箭头不会显示,属预期行为;
  5. 自定义 Popup 的布局约束:builder 第一层容器组件不可使用 position 属性,且自定义 Popup 内不能再嵌套弹出 Popup;
  6. 模糊背景与纯色的取舍:需要纯色气泡时,将 backgroundBlurStyle 显式设为 BlurStyle.NONE,否则默认的 BlurStyle.ComponentUltraThick 等模糊样式会影响 popupColor 的呈现效果;
  7. 弹窗显隐不等同于组件生命周期:自定义组件在 builder 中的 aboutToAppear/aboutToDisappear 与弹窗显隐无关,判断显隐应统一依赖 onStateChange。

通过本文覆盖的两种 bindPopup 重载、PopupOptions/CustomPopupOptions 全部参数、Placement/ArrowPointPosition/DismissReason 等关键枚举以及官方完整示例,开发者即可在仓颉语言 ArkUI 应用中灵活实现从简单文本提示到复杂自定义交互气泡的各类 Popup 场景。

登录后查看全文
CangjieCorpus