警告弹窗（AlertDialog）使用文档

一、概述

警告弹窗（AlertDialog）用于向用户显示重要信息或获取用户的确认反馈。它从 API Version 7 开始支持，在元服务中从 API version 11 开始支持，其功能依赖 UI 的执行上下文，不可在 UI 上下文不明确的地方使用（从 API version 10 开始，可通过 UIContext 中的 showAlertDialog 明确 UI 执行上下文）。

二、使用步骤

（一）获取 UIContext 实例（推荐）

为避免实例不明确的问题，建议使用getUIContext获取 UIContext 实例，并使用showAlertDialog调用绑定实例的AlertDialog.show()。例如：

this.getUIContext().showAlertDialog(/*AlertDialog参数*/);

（二）定义弹窗参数

1. 基本参数

2. title（可选，ResourceStr 类型）：弹窗标题。

3. subtitle（可选，从 API version 10 开始支持，ResourceStr 类型）：弹窗副标题。

4. message（必填，ResourceStr 类型）：弹窗内容。

5. autoCancel（可选，boolean 类型，默认值为 true）：点击遮障层时是否关闭弹窗。

6. alignment（可选，DialogAlignment 枚举类型，默认值为 DialogAlignment.Default）：弹窗在竖直方向上的对齐方式。

7. offset（可选，默认值为 {dx: 0, dy: 0}）：弹窗相对 alignment 所在位置的偏移量。

8. gridCount（可选，number 类型，默认值为 4）：弹窗容器宽度所占用栅格数。

9. maskRect（可选，从 API version 10 开始支持，Rectangle 类型，默认值为 {x: 0, y: 0, width: '100%', height: '100%'}）：弹窗遮蔽层区域，在遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传（showInSubWindow 为 true 时，maskRect 不生效）。

10. showInSubWindow（可选，从 API version 11 开始支持，boolean 类型，默认值为 false）：某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。

11. isModal（可选，从 API version 11 开始支持，boolean 类型，默认值为 true）：弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。

12. backgroundColor（可选，从 API version 12 开始支持，ResourceColor 类型，默认值为 Color.Transparent）：弹窗背板颜色（设置了非透明色时，backgroundBlurStyle 需设为 BlurStyle.NONE）。

13. backgroundBlurStyle（可选，从 API version 12 开始支持，BlurStyle 类型，默认值为 BlurStyle.COMPONENT_ULTRA_THICK）：弹窗背板模糊材质（设置为 BlurStyle.NONE 可关闭背景虚化，设置了非 NONE 值时，不要设置 backgroundColor）。

14. onWillDismiss（可选，从 API version 12 开始支持，Callback 类型）：交互式关闭回调函数，可根据回调中的 reason 选择是否能关闭弹窗（当前不支持 CLOSE_BUTTON 枚举值，且在 onWillDismiss 回调中不能再做 onWillDismiss 拦截）。

15. cornerRadius（可选，从 API version 12 开始支持，可设置背板的圆角半径，默认值为 {topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp'}）：圆角大小受组件尺寸限制，最大值为组件宽或高的一半，若值为负，则按默认值处理，也支持百分比参数方式。

16. transition（可选，从 API version 12 开始支持，设置弹窗显示和退出的过渡效果）。

17. width（可选，从 API version 12 开始支持，设置弹窗背板的宽度，默认最大值为 400vp，支持百分比参数方式）。

18. height（可选，从 API version 12 开始支持，设置弹窗背板的高度，默认最大值为 0.9 *（窗口高度 - 安全区域），支持百分比参数方式）。

19. borderWidth（可选，从 API version 12 开始支持，可分别设置 4 个边框宽度，默认值为 0，支持百分比参数方式）。

20. borderColor（可选，从 API version 12 开始支持，设置弹窗背板的边框颜色，默认值为 Color.Black，需和 borderWidth 一起使用）。

21. borderStyle（可选，从 API version 12 开始支持，设置弹窗背板的边框样式，默认值为 BorderStyle.Solid，需和 borderWidth 一起使用）。

22. shadow（可选，从 API version 12 开始支持，设置弹窗背板的阴影）。

23. textStyle（可选，从 API version 12 开始支持，设置弹窗 message 内容的文本样式）。

24. 按钮相关参数

25. 可以使用AlertDialogParamWithConfirm、AlertDialogParamWithButtons或AlertDialogParamWithOptions（从 API version 10 开始支持）来定义按钮相关参数。

26. confirm（AlertDialogParamWithConfirm中）：包含确认 Button 的使能状态（enabled，默认值为 true）、默认焦点（defaultFocus，默认值为 false）、按钮风格（style，默认值为 DialogButtonStyle.DEFAULT）、文本内容（value）、文本色（fontColor）、按钮背景色（backgroundColor）和点击回调（action）。

27. primaryButton和secondaryButton（AlertDialogParamWithButtons中）：与confirm类似，分别用于定义主要按钮和次要按钮的相关属性。

28. buttons（AlertDialogParamWithOptions中）：是一个AlertDialogButtonOptions数组，用于定义弹窗容器中的多个按钮，每个按钮包含使能状态（enabled，默认值为 true）、默认焦点（defaultFocus，默认值为 false）、风格样式（style，默认值为 DialogButtonStyle.DEFAULT）、文本内容（value，若为 null 则按钮不显示）、文本颜色（fontColor）、背景颜色（backgroundColor）和点击回调（action）等属性。同时，还可以设置buttonDirection（可选，DialogButtonDirection 枚举类型，默认值为 DialogButtonDirection.AUTO，用于指定按钮排布方向）。

（三）显示弹窗

使用AlertDialog.show方法并传入定义好的参数来显示弹窗，例如：

AlertDialog.show({  title: 'title',  message: 'text',  autoCancel: true,  alignment: DialogAlignment.Bottom,  offset: { dx: 0, dy: -20 },  gridCount: 3,  confirm: {    value: 'button',    action: () => {      console.info('Button-clicking callback');    }  },  cancel: () => {    console.info('Closed callbacks');  },  onWillDismiss: (dismissDialogAction: DismissDialogAction) => {    console.info("reason=" + JSON.stringify(dismissDialogAction.reason));    console.log("dialog onWillDismiss");    if (dismissDialogAction.reason == DismissReason.PRESS_BACK) {      dismissDialogAction.dismiss();    }    if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) {      dismissDialogAction.dismiss();    }  }});

三、注意事项

1. 尽量按照推荐方式获取 UIContext 实例并显示弹窗，以确保功能正常。

2. 在设置按钮相关参数时，注意各属性的默认值和优先级，以及按钮响应的相关规则（如默认响应 Enter 键能力在 defaultFocus 为 true 时不生效等）。

3. 当设置背景相关属性（如 backgroundColor 和 backgroundBlurStyle）时，需遵循其相互制约的规则。

4. 对于弹窗的各种尺寸和位置相关参数（如 width、height、alignment、offset 等），根据实际需求合理设置，以达到理想的弹窗显示效果。