仓颉 ArkUI 警告弹窗(AlertDialog)开发指南:从按钮配置到交互式关闭拦截
仓颉 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)
}
}
}
逐段要点解读:
- 单按钮弹窗(one button dialog):使用
AlertDialogParamWithConfirm,confirm按钮文本为"button",点击后通过Hilog.info打印日志。注意title/subtitle均非必填,此处用于展示完整标题结构;backgroundColor: Color.White指定了非透明背板色——按照第三节的约束,若要同时使用模糊材质需把backgroundBlurStyle显式设为BlurStyle.NONE; - 双按钮弹窗(two button dialog):使用
AlertDialogParamWithButtons,primaryButton为取消按钮"Cancel",secondaryButton为确认按钮"OK"。确认按钮显式设置了enabled: true、defaultFocus: true与style: DialogButtonStyle.Highlight,使其成为默认焦点的高亮主操作按钮——这正是第四节所述焦点与风格配置的典型组合; - 多按钮弹窗(three button dialog):使用
AlertDialogParamWithOptions,通过buttons数组传入 3 个按钮,未显式指定buttonDirection,因此按默认值Auto自动排布为纵向。注意此例未设置gridCount(使用默认值 4)且没有showInSubWindow,是应用内常规弹窗; - 关闭拦截:三个弹窗均注册了
onWillDismiss,统一采用PRESS_BACK/TOUCH_OUTSIDE放行、其余忽略的策略; - 偏移定位:
alignment: DialogAlignment.Center配合offset: CommonOffset(0, -20),将弹窗垂直居中后整体上移 20vp,说明offset是以alignment位置为参考系的相对位移; - 日志观测:所有回调均通过
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的弹窗"这一限制。
八、开发注意事项汇总
综合原文档参数说明与示例实践,整理出以下高频注意事项,供实际开发时逐项核对:
- 必填项检查:
message、按钮的value与action是必填项;AlertDialogParamWithButtons的primaryButton/secondaryButton、AlertDialogParamWithOptions的buttons同样必填; - 视觉参数互斥:
backgroundColor(非透明)与backgroundBlurStyle(非 NONE)不要同时设置;borderColor/borderStyle必须配合borderWidth; - 焦点与键盘:
primary只能有一个按钮为true;primary在defaultFocus为true时不生效;多按钮弹窗建议使用DialogButtonDirection.Auto; - 子窗口限制:
showInSubWindow为true时maskRect失效,且无法再弹出同为子窗口模式的弹窗; - 拦截回调限制:
onWillDismiss回调中不能再做onWillDismiss拦截;当前 AlertDialog 的reason不支持CLOSE_BUTTON枚举值; - 过渡动效:不设置
transition时使用默认显示 / 退出动效;显示动效中按 back 会打断并叠加曲线执行退出动效,退出动效中按 back 不会打断退出动效,继续按 back 才退出应用; - 尺寸边界:圆角最大值为组件宽或高的一半,负值按默认值处理;边框过宽可能超出弹窗显示范围。
九、延伸阅读
- 警告弹窗 API 参考:本文所述全部类、枚举与示例的原始出处;
- 操作表(ActionSheet)与 DismissDialogAction:
DismissDialogAction的完整定义; - 通用类型定义(cj-common-types):
DialogButtonStyle、DialogAlignment、WordBreak、BlurStyle、DismissReason、VoidCallback、Offset、Rectangle、Length、ResourceStr、ResourceColor等类型说明; - 过渡动画 TransitionEffect:
transition参数的取法与用法; - UIContext API:
showAlertDialog三个重载及其他弹窗入口(如showActionSheet、showToast); - 自定义弹窗 CustomDialog:需要完全自定义内容时的替代方案;
- ArkUI 开发总览:仓颉 ArkUI 组件的完整索引。