仓颉 ArkUI 警告弹窗(AlertDialog)开发指南:从按钮配置到交互式关闭拦截

原创2026-10-15 18:17:191,337 阅读
文章标签:文档知识库

仓颉 ArkUI 警告弹窗(AlertDialog)开发指南:从按钮配置到交互式关闭拦截

本文以开源语料库 CangjieCorpus 中 ArkUI 警告弹窗组件的 API 参考文档为核心,系统讲解仓颉语言下 AlertDialog 的完整用法:三类按钮配置类、弹窗参数类 AlertDialogParam 及其三个变体、关键枚举与回调机制,并通过两个可运行的完整示例演示"单按钮/双按钮/多按钮弹窗"与"主窗口外弹窗"的落地写法。读完本文,你将掌握通过 getUIContext().showAlertDialog() 快速构建符合业务需求的警告弹窗,并能够利用 onWillDismiss 实现按关闭原因精细化拦截的交互控制。

一、AlertDialog 概览与模块导入

警告弹窗(AlertDialog)是 ArkUI 中用于展示提示信息、并要求用户做出确认或取消决策的对话框组件。它支持设置标题、副标题、文本内容(message)以及一个或多个响应按钮,按钮点击后可以触发对应的回调逻辑。

在仓颉工程中,使用警告弹窗前需要导入 ArkUI 基础模块:

import kit.ArkUI.*

AlertDialog 相关能力对应的系统能力声明为 SystemCapability.ArkUI.ArkUI.Full,起始版本为 22。

弹窗本身并不直接以组件形式写在 build() 中,而是通过 UIContext 的 showAlertDialog 方法弹出。该方法在 cj-apis-uicontext-uicontext.md 中有三个重载,分别对应三种弹窗参数类型:

public func showAlertDialog(options: AlertDialogParamWithConfirm): Unit
public func showAlertDialog(options: AlertDialogParamWithButtons): Unit
public func showAlertDialog(options: AlertDialogParamWithOptions): Unit

即:单确认按钮弹窗、双按钮弹窗、多按钮弹窗。三种重载的参数对象均继承自 AlertDialogParam,本文后续将逐一展开。

二、按钮配置:AlertDialogButtonBaseOptions 与 AlertDialogButtonOptions

弹窗中的按钮通过配置类定义。基础按钮配置类 AlertDialogButtonBaseOptions 位于本仓库的 cj-dialog-alertdialog.md,声明如下:

public open class AlertDialogButtonBaseOptions {
    public var enabled: ?Bool
    public var defaultFocus: ?Bool
    public var style: ?DialogButtonStyle
    public var value: ?ResourceStr
    public var fontColor: ?ResourceColor
    public var backgroundColor: ?ResourceColor
    public var action: ?VoidCallback
    public init(
        enabled!: ?Bool = None,
        defaultFocus!: ?Bool = None,
        style!: ?DialogButtonStyle = None,
        value!: ?ResourceStr,
        fontColor!: ?ResourceColor = None,
        backgroundColor!: ?ResourceColor = None,
        action!: ?VoidCallback
    )
}

AlertDialogButtonBaseOptions 中所有字段均可读写,其含义如下:

字段 类型 功能说明
action ?VoidCallback Button 选中时的回调
backgroundColor ?ResourceColor Button 背景颜色
defaultFocus ?Bool 设置 Button 是否是默认焦点
enabled ?Bool 点击 Button 是否响应
fontColor ?ResourceColor Button 的文本颜色
style ?DialogButtonStyle 设置 Button 的风格样式
value ?ResourceStr Button 的文本内容

构造函数各命名参数的默认值如下:enabled 初始值为 true(可点击)、defaultFocus 初始值为 false、style 初始值为 DialogButtonStyle.Default、action 初始值为 {=>}(空回调);value 与 action 为必填命名参数,其余可选。

AlertDialogButtonOptions:追加 primary 主按钮语义

实际构造按钮时通常使用 AlertDialogButtonOptions,它在基类之上增加了 primary 字段:

public class AlertDialogButtonOptions <: AlertDialogButtonBaseOptions {
    public var primary: ?Bool
    public init(
        enabled!: ?Bool = None,
        defaultFocus!: ?Bool = None,
        style!: ?DialogButtonStyle = None,
        value!: ?ResourceStr,
        fontColor!: ?ResourceColor = None,
        backgroundColor!: ?ResourceColor = None,
        action!: ?VoidCallback,
        primary!: ?Bool = None
    )
}

primary 的语义值得特别注意:在弹窗获焦且未进行 Tab 键走焦时,按钮是否默认响应 Enter 键。使用约束如下:

  • 多个按钮时,只允许一个 Button 的 primary 配置为 true,否则所有 Button 均不响应 Enter;
  • 多重弹窗可自动获焦连续响应;
  • 在 defaultFocus 为 true 时不生效;
  • 初始值为 false。

从源码结构看,该字段服务于键盘(Enter 键)交互场景,适合桌面端、外接键盘等需要键鼠并用的使用环境,与 defaultFocus(默认焦点)共同构成弹窗的焦点管理能力。

三、弹窗本体:AlertDialogParam 全参数解析

AlertDialogParam 是警告弹窗的参数基类,包含弹窗内容、布局、外观、关闭行为等全部公共配置:

public open class AlertDialogParam {
    public var title: ?ResourceStr
    public var subtitle: ?ResourceStr
    public var message: ?ResourceStr
    public var autoCancel: ?Bool
    public var cancel: ?VoidCallback
    public var alignment: ?DialogAlignment
    public var offset: ?Offset
    public var gridCount: ?UInt32
    public var maskRect: ?Rectangle
    public var showInSubWindow: ?Bool
    public var isModal: ?Bool
    public var backgroundColor: ?ResourceColor
    public var backgroundBlurStyle: ?BlurStyle
    public var onWillDismiss: ?Callback<DismissDialogAction, Unit>
    public var cornerRadius: ?BorderRadiuses
    public var transition: ?TransitionEffect
    public var width: ?Length
    public var height: ?Length
    public var borderWidth: ?Length
    public var borderColor: ?BorderColor
    public var borderStyle: ?EdgeStyles
    public var shadow: ?ShadowOptions
    public var textStyle: ?WordBreak
}

各字段的读写能力均为"可读写",构造函数的完整参数表如下(message 为唯一必填项,其余均为命名可选参数):

参数名 类型 默认值 说明
title ?ResourceStr "" 弹窗标题
subtitle ?ResourceStr "" 弹窗副标题
message ?ResourceStr -(必填) 弹窗内容
autoCancel ?Bool true 点击遮障层时是否关闭弹窗,true 关闭、false 不关闭
cancel ?VoidCallback {=>} 点击遮障层关闭 dialog 时的回调
alignment ?DialogAlignment DialogAlignment.Default 弹窗在竖直方向上的对齐方式
offset ?Offset Offset(0, 0) 弹窗相对 alignment 所在位置的偏移量
gridCount ?UInt32 4 弹窗容器宽度所占用栅格数
maskRect ?Rectangle Rectangle(x: 0, y: 0, width: 100.percent, height: 100.percent) 弹窗遮蔽层区域:区域内事件不透传,区域外事件透传。showInSubWindow 为 true 时 maskRect 不生效
showInSubWindow ?Bool false 是否在子窗口显示弹窗(用于需要显示在主窗口之外的场景)。注意:showInSubWindow 为 true 的弹窗无法触发显示另一个同为 true 的弹窗
isModal ?Bool true 弹窗是否为模态窗口,模态窗口有蒙层,非模态窗口无蒙层
backgroundColor ?ResourceColor Color.Transparent 弹窗背板颜色。若设置为非透明色,backgroundBlurStyle 需同时设置为 BlurStyle.NONE,否则颜色显示不符合预期
backgroundBlurStyle ?BlurStyle BlurStyle.ComponentUltraThick 弹窗背板模糊材质,设为 BlurStyle.NONE 可关闭背景虚化。设置为非 NONE 值时不要同时设置 backgroundColor
onWillDismiss ?Callback<DismissDialogAction, Unit> None 交互式关闭回调,详见本文第五节
transition ?TransitionEffect None 弹窗显示和退出的过渡效果,不设置则使用默认动效
cornerRadius ?BorderRadiuses BorderRadiuses(topLeft: 32.vp, topRight: 32.vp, bottomLeft: 32.vp, bottomRight: 32.vp) 背板圆角半径,可分别设置 4 个圆角;最大值为组件宽或高的一半,负值按默认值处理
width ?Length None 弹窗背板宽度;百分比方式参考所在窗口宽度
height ?Length None 弹窗背板高度;百分比方式参考(窗口高度 - 安全区域)
borderWidth ?Length 0 可分别设置 4 个边框宽度;左右边框大于弹窗宽度、上下边框大于弹窗高度时显示可能不符合预期
borderColor ?BorderColor BorderColor(color: Color.Black) 弹窗背板边框颜色,需与 borderWidth 一起使用才生效
borderStyle ?EdgeStyles EdgeStyles() 弹窗背板边框样式,需与 borderWidth 一起使用才生效
shadow ?ShadowOptions ShadowOptions(radius: 0.0) 弹窗背板的阴影
textStyle ?WordBreak WordBreak.BreakAll 弹窗 message 内容的文本断行样式

关键参数的联动约束

从参数表的说明可以看出,以下几个组合需要开发者特别注意:

  • backgroundColor 与 backgroundBlurStyle 互斥:背板颜色与模糊材质只能二选一主导视觉效果,同时设置会导致颜色显示不符合预期;
  • borderColor / borderStyle 依赖 borderWidth:只设置颜色或样式而不设置宽度,边框不会正常显示;
  • maskRect 与 showInSubWindow 互斥:弹窗显示在子窗口时,遮蔽层区域配置失效;
  • isModal 决定蒙层:模态窗口(默认 true)自带蒙层,非模态窗口无蒙层,这一开关直接影响 autoCancel(点击遮障层关闭)与 maskRect(遮蔽层区域)的实际表现。

四、三个弹窗变体:单确认 / 双按钮 / 多按钮

AlertDialogParam 本身只定义弹窗内容与外观,实际弹出时必须使用它的三个子类之一,分别对应 showAlertDialog 的三个重载。

4.1 AlertDialogParamWithConfirm:单确认按钮弹窗

public class AlertDialogParamWithConfirm <: AlertDialogParam {
    public var confirm: ?AlertDialogButtonBaseOptions
}

confirm 字段用于配置确认 Button 的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调,类型为 ?AlertDialogButtonBaseOptions。其构造函数的默认值为 AlertDialogButtonOptions(value: "", action: {=>}),即:不传 confirm 时仍会有一个文本为空、回调为空的确认为按钮,因此实际使用时务必传入 value 与 action。

4.2 AlertDialogParamWithButtons:双按钮弹窗

public class AlertDialogParamWithButtons <: AlertDialogParam {
    public var primaryButton: ?AlertDialogButtonBaseOptions
    public var secondaryButton: ?AlertDialogButtonBaseOptions
}
  • primaryButton:第一个按钮,必填;
  • secondaryButton:第二个按钮,必填。

典型的"取消 / 确定"双按钮弹窗即由这两个字段组合实现,配合 style: DialogButtonStyle.Highlight 可让主操作按钮更醒目(见示例 1 的第二个按钮)。

4.3 AlertDialogParamWithOptions:多按钮弹窗

public class AlertDialogParamWithOptions <: AlertDialogParam {
    public var buttons: ?Array<AlertDialogButtonOptions>
    public var buttonDirection: ?DialogButtonDirection
}
  • buttons:弹窗容器中的多个按钮(类型为 ?Array<AlertDialogButtonOptions>),必填;
  • buttonDirection:按钮排布方向,默认值为 DialogButtonDirection.Auto,建议 3 个以上按钮使用 Auto 模式——两个以上按钮会自动切换为纵向模式,通常能显示更多按钮;非 Auto 模式下,3 个以上按钮可能显示不全,超出显示范围的按钮会被截断。

五、关闭拦截机制:onWillDismiss 与 DismissDialogAction

onWillDismiss 是警告弹窗实现"交互式关闭"的关键回调。当用户执行以下交互操作时,如果注册了该回调,弹窗不会立刻关闭:

  • 点击遮障层关闭;
  • 左滑 / 右滑;
  • 三键 back;
  • 键盘 ESC 关闭。

此时回调参数 DismissDialogAction 会携带关闭原因,开发者可以根据原因决定是否放行关闭。DismissDialogAction 定义在 cj-dialog-actionsheet.md:

public class DismissDialogAction {
    public var reason: DismissReason
    public func dismiss(): Unit
}
  • reason:Dialog 无法关闭的原因,类型为 DismissReason,枚举值包括:
    • PressBack:点击三键 back、左滑 / 右滑、键盘 ESC;
    • TouchOutside:点击遮障层时;
    • CloseButton:点击关闭按钮(注意:当前 AlertDialog 组件返回的 reason 中暂不支持 CLOSE_BUTTON 枚举值);
    • SlideDown:下拉关闭。
  • dismiss():Dialog 关闭回调函数。开发者需要推出时调用,不需要退出时无需调用。

使用约束提醒:在 onWillDismiss 回调中,不能再做 onWillDismiss 拦截,避免回调递归嵌套导致行为异常。

一个基于 match 的拦截写法

在弹窗参数中配合仓颉的 match 表达式,可以精确区分关闭来源,例如:

onWillDismiss: {
    dismissDialogAction: DismissDialogAction => match (dismissDialogAction.reason) {
        case PRESS_BACK => dismissDialogAction.dismiss()
        case TOUCH_OUTSIDE => dismissDialogAction.dismiss()
        case _ => ()
    }
}

这段代码的效果是:按下返回键或点击遮障层时放行关闭,其他关闭请求一律忽略。match 分支直接对应上文示例代码中的写法,是拦截式关闭的标准范式。

六、配套类型深析:BorderColor 与 DialogButtonDirection

6.1 BorderColor:弹窗边框颜色

public class BorderColor {
    public var resourceColor: ResourceColor
    public init(color!: ?ResourceColor = Color.Black)
}

BorderColor 用于定义对话框组件的边框颜色,字段 resourceColor 为边框的颜色资源(可读写),构造函数默认值为 Color.Black。它通常与 borderWidth 搭配使用,参见第三节的参数约束。

6.2 DialogButtonDirection:按钮排布方向

public enum DialogButtonDirection <: Equatable<DialogButtonDirection> {
    | Auto
    | Horizontal
    | Vertical
    | ...
}
枚举值 功能
Auto 两个及以下按钮水平排布,两个以上为竖直排布(默认值,推荐)
Horizontal 按钮水平布局
Vertical 按钮竖直布局

该枚举实现了 Equatable<DialogButtonDirection>,并提供 == 与 != 运算符用于比较两个枚举值是否相等 / 不相等。

七、完整实战示例

原文档提供了两个标注为 <!-- run --> 的可运行示例,下文完整保留并补充逐步解读。两个示例均以 @Entry @Component 页面为载体,在按钮点击事件中通过 getUIContext().showAlertDialog(...) 弹出弹窗。

示例 1:单按钮、双按钮与多按钮弹窗

package ohos_app_cangjie_entry

import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
import ohos.hilog.*
import ohos.arkui.component.common.Offset as CommonOffset

@Entry
@Component
class EntryView {
    func build() {
        Column(space:5.vp) {
            Button("one button dialog")
                .onClick({ evt =>
                    getUIContext().showAlertDialog(
                        AlertDialogParamWithConfirm(message:"text",
                            title: "title",
                            subtitle: "subtitle",
                            autoCancel: true,
                            cancel: {=> Hilog.info(0, "AppLogCj", "Closed callbacks")}, alignment: DialogAlignment.Center,
                            offset: CommonOffset(0, -20),
                            gridCount: 4,
                            backgroundColor: Color.White,
                            onWillDismiss: {
                                dismissDialogAction: DismissDialogAction => match (dismissDialogAction.reason) {
                                    case PRESS_BACK => dismissDialogAction.dismiss()
                                    case TOUCH_OUTSIDE => dismissDialogAction.dismiss()
                                    case _ => ()
                                }
                            },
                            confirm: AlertDialogButtonOptions(value: "button",
                                action: {=> Hilog.info(0, "AppLogCj", "Button-clicking callback")}
                            )
                        )
                    )
                })
            .backgroundColor(0x317aff)
            Button("two button dialog")
                .onClick({ evt =>
                    getUIContext().showAlertDialog(
                        AlertDialogParamWithButtons(message: "text",
                            title: "title",
                            subtitle: "subtitle",
                            autoCancel: true,
                            cancel: {=> Hilog.info(0, "AppLogCj", "Closed callbacks")},
                            alignment: DialogAlignment.Center,
                            offset: CommonOffset(0, -20),
                            gridCount: 4,
                            backgroundColor: Color.White,
                            onWillDismiss: {
                                dismissDialogAction: DismissDialogAction => match (dismissDialogAction.reason) {
                                    case PRESS_BACK => dismissDialogAction.dismiss()
                                    case TOUCH_OUTSIDE => dismissDialogAction.dismiss()
                                    case _ => ()
                                }
                            },
                            primaryButton: AlertDialogButtonOptions(value: "Cancel",
                                action: {=> Hilog.info(0, "AppLogCj", "Callback when second button is clicked")}),
                            secondaryButton: AlertDialogButtonOptions(enabled: true, defaultFocus: true,
                                style: DialogButtonStyle.Highlight, value: "OK",
                                action: {=> Hilog.info(0, "AppLogCj", "Callback when second button is clicked")}
                            )
                        )
                    )
                })
            .backgroundColor(0x317aff)
            Button("three button dialog")
                .onClick({ evt =>
                    getUIContext().showAlertDialog(
                        AlertDialogParamWithOptions(
                            message: "text",
                            title: "title",
                            subtitle: "subtitle",
                            autoCancel: true,
                            cancel: {=> Hilog.info(0, "AppLogCj", "Callback when third button is clicked")},
                            alignment: DialogAlignment.Center,
                            offset: CommonOffset(0, -20),
                            backgroundColor: Color.White,
                            gridCount: 4,
                            onWillDismiss: {
                                dismissDialogAction: DismissDialogAction => match (dismissDialogAction.reason) {
                                    case PRESS_BACK => dismissDialogAction.dismiss()
                                    case TOUCH_OUTSIDE => dismissDialogAction.dismiss()
                                    case _ => ()
                                }
                            },
                            buttons: [
                                AlertDialogButtonOptions(value: "按钮",
                                    action: {=> Hilog.info(0, "AppLogCj", "Callback when button1 is clicked")}),
                                AlertDialogButtonOptions(value: "按钮",
                                    action: {=> Hilog.info(0, "AppLogCj", "Callback when button1 is clicked")}),
                                AlertDialogButtonOptions(value: "按钮",
                                    action: {=> Hilog.info(0, "AppLogCj", "Callback when button1 is clicked")})
                            ]
                        )
                    )
                })
                .backgroundColor(0x317aff)
        }
    }
}

逐段要点解读:

  1. 单按钮弹窗(one button dialog):使用 AlertDialogParamWithConfirm,confirm 按钮文本为 "button",点击后通过 Hilog.info 打印日志。注意 title / subtitle 均非必填,此处用于展示完整标题结构;backgroundColor: Color.White 指定了非透明背板色——按照第三节的约束,若要同时使用模糊材质需把 backgroundBlurStyle 显式设为 BlurStyle.NONE;
  2. 双按钮弹窗(two button dialog):使用 AlertDialogParamWithButtons,primaryButton 为取消按钮 "Cancel",secondaryButton 为确认按钮 "OK"。确认按钮显式设置了 enabled: true、defaultFocus: true 与 style: DialogButtonStyle.Highlight,使其成为默认焦点的高亮主操作按钮——这正是第四节所述焦点与风格配置的典型组合;
  3. 多按钮弹窗(three button dialog):使用 AlertDialogParamWithOptions,通过 buttons 数组传入 3 个按钮,未显式指定 buttonDirection,因此按默认值 Auto 自动排布为纵向。注意此例未设置 gridCount(使用默认值 4)且没有 showInSubWindow,是应用内常规弹窗;
  4. 关闭拦截:三个弹窗均注册了 onWillDismiss,统一采用 PRESS_BACK / TOUCH_OUTSIDE 放行、其余忽略的策略;
  5. 偏移定位:alignment: DialogAlignment.Center 配合 offset: CommonOffset(0, -20),将弹窗垂直居中后整体上移 20vp,说明 offset 是以 alignment 位置为参考系的相对位移;
  6. 日志观测:所有回调均通过 ohos.hilog 的 Hilog.info(0, "AppLogCj", "...") 输出,便于在 DevEco 的 HiLog 窗口中验证按钮点击、遮障层关闭等事件的触发顺序。

示例 2:显示在主窗口之外的弹窗

package ohos_app_cangjie_entry

import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
import ohos.hilog.*
import ohos.arkui.component.common.Offset as CommonOffset

@Entry
@Component
class EntryView {
    func build() {
        Column(space: 5.vp) {
            Button("button dialog")
                .onClick({ evt =>
                        AlertDialogParamWithOptions(
                            message: "text",
                            title: "title",
                            subtitle: "subtitle",
                            autoCancel: true,
                            cancel: {=> Hilog.info(0, "AppLogCj", "Closed callbacks")},
                            alignment: DialogAlignment.Center,
                            offset: CommonOffset(0, -20),
                            showInSubWindow: true,
                            buttonDirection: DialogButtonDirection.Horizontal,
                            gridCount: 4,
                            onWillDismiss: {
                                dismissDialogAction: DismissDialogAction => match (dismissDialogAction.reason) {
                                    case PRESS_BACK => dismissDialogAction.dismiss()
                                    case TOUCH_OUTSIDE => dismissDialogAction.dismiss()
                                    case _ => ()
                                }
                            },
                            buttons: [
                                AlertDialogButtonOptions(value: "按钮",
                                    action: {=> Hilog.info(0, "AppLogCj", "Callback when button1 is clicked")}),
                                AlertDialogButtonOptions(value: "按钮",
                                    action: {=> Hilog.info(0, "AppLogCj", "Callback when button1 is clicked")}),
                                AlertDialogButtonOptions(value: "按钮",
                                    action: {=> Hilog.info(0, "AppLogCj", "Callback when button1 is clicked")})
                            ]
                        )
                })
                .backgroundColor(0x317aff)
        }
    }
}

与示例 1 的关键差异:

  • showInSubWindow: true:弹窗显示在独立的子窗口中,适用于"某弹框需要显示在主窗口之外"的诉求(如跨窗口浮层、悬浮提示类场景);
  • buttonDirection: DialogButtonDirection.Horizontal:强制按钮水平排布。3 个按钮在水平模式下可能显示不全,超出显示范围的按钮会被截断——示例用于演示 Horizontal 的显式用法,生产环境若按钮较多,建议按默认 Auto 模式以自动切换纵向排布;
  • 由于 showInSubWindow 为 true,第三节中的 maskRect 配置在此场景下不生效;同时需要注意"showInSubWindow 为 true 的弹窗无法触发显示另一个 showInSubWindow 为 true 的弹窗"这一限制。

八、开发注意事项汇总

综合原文档参数说明与示例实践,整理出以下高频注意事项,供实际开发时逐项核对:

  1. 必填项检查:message、按钮的 value 与 action 是必填项;AlertDialogParamWithButtons 的 primaryButton / secondaryButton、AlertDialogParamWithOptions 的 buttons 同样必填;
  2. 视觉参数互斥:backgroundColor(非透明)与 backgroundBlurStyle(非 NONE)不要同时设置;borderColor / borderStyle 必须配合 borderWidth;
  3. 焦点与键盘:primary 只能有一个按钮为 true;primary 在 defaultFocus 为 true 时不生效;多按钮弹窗建议使用 DialogButtonDirection.Auto;
  4. 子窗口限制:showInSubWindow 为 true 时 maskRect 失效,且无法再弹出同为子窗口模式的弹窗;
  5. 拦截回调限制:onWillDismiss 回调中不能再做 onWillDismiss 拦截;当前 AlertDialog 的 reason 不支持 CLOSE_BUTTON 枚举值;
  6. 过渡动效:不设置 transition 时使用默认显示 / 退出动效;显示动效中按 back 会打断并叠加曲线执行退出动效,退出动效中按 back 不会打断退出动效,继续按 back 才退出应用;
  7. 尺寸边界:圆角最大值为组件宽或高的一半,负值按默认值处理;边框过宽可能超出弹窗显示范围。

九、延伸阅读

登录后查看全文
CangjieCorpus