1# 警告弹窗 (AlertDialog) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @houguobiao--> 5<!--Designer: @houguobiao--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9显示警告弹窗组件，可设置文本内容与响应回调。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 本模块功能依赖UI的执行上下文，不可在[UI上下文不明确](../../../ui/arkts-global-interface.md)的地方使用，参见[UIContext](../arkts-apis-uicontext-uicontext.md)说明。 16 17## AlertDialogParam对象说明 18 19警告弹窗的样式。 20 21**系统能力：** SystemCapability.ArkUI.ArkUI.Full 22 23| 名称 | 类型 | 只读 | 可选 | 说明 | 24| --------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 25| title | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 弹窗标题。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 26| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 弹窗副标题。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 27| message | [ResourceStr](ts-types.md#resourcestr) | 否 | 否 | 弹窗内容。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 28| autoCancel | boolean | 否 | 是 | 点击遮障层时，是否关闭弹窗，true表示关闭弹窗。false表示不关闭弹窗。<br/>默认值：true<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 29| cancel | [VoidCallback](ts-types.md#voidcallback12) | 否 | 是 | 点击遮障层关闭dialog时的回调。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 30| alignment | [DialogAlignment](#dialogalignment枚举说明) | 否 | 是 | 弹窗在竖直方向上的对齐方式。<br/>默认值：DialogAlignment.Default <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**说明**：<br/>若在UIExtension中设置showInSubWindow为true，弹窗将基于UIExtension的宿主窗口对齐。 | 31| offset | [Offset](ts-types.md#offset) | 否 | 是 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 }<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 32| gridCount | number | 否 | 是 | 弹窗容器宽度所占用栅格数。<br/>默认值：4 <br>取值范围：大于等于0的整数。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 33| maskRect<sup>10+</sup> | [Rectangle](#rectangle8类型说明) | 否 | 是 | 弹窗遮蔽层区域，在遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传。<br/>默认值：{ x: 0, y: 0, width: '100%', height: '100%' } <br/>**说明：**<br/>showInSubWindow为true时，maskRect不生效。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 34| showInSubWindow<sup>11+</sup> | boolean | 否 | 是 | 某弹窗需要显示在主窗口之外时，是否在子窗口显示此弹窗。值为true表示在子窗口显示弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。<br/>**说明**：showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 35| isModal<sup>11+</sup> | boolean | 否 | 是 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。值为false时，弹窗为非模态窗口，无蒙层。<br/>默认值：true，此时弹窗有蒙层。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 36| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 弹窗背板颜色。<br/>默认值：Color.Transparent<br/>**说明：** <br/>backgroundColor会与模糊属性backgroundBlurStyle叠加产生效果，如果不符合预期，可将backgroundBlurStyle设置为BlurStyle.NONE，即可取消模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 37| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | 否 | 是 | 弹窗背板模糊材质。<br/>默认值：BlurStyle.COMPONENT_ULTRA_THICK<br/>**说明：** <br/>设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时，则不要设置backgroundColor，否则颜色显示将不符合预期效果。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 38| backgroundBlurStyleOptions<sup>19+</sup> | [BackgroundBlurStyleOptions](ts-universal-attributes-background.md#backgroundblurstyleoptions10对象说明) | 否 | 是 | 背景模糊效果。默认值请参考BackgroundBlurStyleOptions类型说明。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 39| backgroundEffect<sup>19+</sup> | [BackgroundEffectOptions](ts-universal-attributes-background.md#backgroundeffectoptions11) | 否 | 是 | 背景效果参数。默认值请参考BackgroundEffectOptions类型说明。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 40| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | 否 | 是 | 交互式关闭回调函数。<br/>**说明：**<br/>1.当用户执行点击遮障层关闭、侧滑（左滑/右滑）、三键back、键盘ESC关闭交互操作时，如果注册该回调函数，则不会立刻关闭弹窗。在回调函数中可以通过reason得到阻拦关闭弹窗的操作类型，从而根据原因选择是否能关闭弹窗。当前组件返回的reason中，暂不支持CLOSE_BUTTON的枚举值。<br/>2.在onWillDismiss回调中，不能再做onWillDismiss拦截。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 41| cornerRadius<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-types.md#borderradiuses9) \| [LocalizedBorderRadiuses](ts-types.md#localizedborderradiuses12) | 否 | 是 | 设置背板的圆角半径。<br />可分别设置4个圆角的半径。<br />默认值：{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }<br /> 圆角大小受组件尺寸限制，最大值为组件宽或高的一半，若值为负，则按照默认值处理。 <br /> 百分比参数方式：以父元素弹窗宽和高的百分比来设置弹窗的圆角。<br/>**说明：**<br/>当cornerRadius属性类型为LocalizedBorderRadiuses时，支持随语言习惯改变布局顺序。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 42| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 是 | 设置弹窗显示和退出的过渡效果。<br/>**说明：**<br/> 1.如果不设置，则使用默认的显示/退出动效。<br/> 2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。<br/> 3.退出动效中按back键，不会打断退出动效，退出动效继续执行，继续按back键退出应用。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 43| width<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 是 | 设置弹窗背板的宽度。<br />**说明：**<br>- 弹窗宽度默认最大值：400vp。<br />- 百分比参数方式：弹窗参考宽度为所在窗口的宽度，在此基础上调小或调大。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 44| height<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 是 | 设置弹窗背板的高度。<br />**说明：**<br />- 弹窗高度默认最大值：0.9 *（窗口高度 - 安全区域）。<br />- 百分比参数方式：弹窗参考高度为（窗口高度 - 安全区域），在此基础上调小或调大。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 45| borderWidth<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#localizededgewidths12) | 否 | 是 |可分别设置4个边框宽度。<br />默认值：0<br /> 百分比参数方式：以父元素弹窗宽的百分比来设置弹窗的边框宽度。<br />当弹窗左边框和右边框大于弹窗宽度，弹窗上边框和下边框大于弹窗高度，显示可能不符合预期。<br/>**说明：**<br/>当borderWidth属性类型为LocalizedEdgeWidths时，支持随语言习惯改变布局顺序。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 46| borderColor<sup>12+</sup> | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](ts-types.md#edgecolors9) \| [LocalizedEdgeColors](ts-types.md#localizededgecolors12) | 否 | 是 | 设置弹窗背板的边框颜色。<br/>默认值：Color.Black<br/> 如果使用borderColor属性，需要和borderWidth属性一起使用。<br/>**说明：**<br/>当borderColor属性类型为LocalizedEdgeColors时，支持随语言习惯改变布局顺序。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 47| borderStyle<sup>12+</sup> | [BorderStyle](ts-appendix-enums.md#borderstyle) \| [EdgeStyles](ts-types.md#edgestyles9) | 否 | 是 | 设置弹窗背板的边框样式。<br/>默认值：BorderStyle.Solid<br/>如果使用borderStyle属性，需要和borderWidth属性一起使用。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 48| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 是 | 设置弹窗背板的阴影。 <br /> 当设备为2in1时，默认场景下获焦阴影值为ShadowStyle.OUTER_FLOATING_MD，失焦为ShadowStyle.OUTER_FLOATING_SM。其他设备默认无阴影。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 49| textStyle<sup>12+</sup> | [TextStyle](#textstyle12对象说明) | 否 | 是 | 设置弹窗message内容的文本样式。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 50| enableHoverMode<sup>14+</sup> | boolean | 否 | 是 | 是否响应悬停态，值为true时，响应悬停态。<br />默认值：false，默认不响应。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| 51| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](ts-universal-attributes-sheet-transition.md#hovermodeareatype14) | 否 | 是 | 悬停态下弹窗默认展示区域。<br />默认值：HoverModeAreaType.BOTTOM_SCREEN。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| 52| onWillAppear<sup>19+</sup> | Callback<void> | 否 | 是 | 弹窗显示动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear >> onDidAppear >> onWillDisappear >> onDidDisappear。<br />2.在onWillAppear内设置改变弹窗显示效果的回调事件，二次弹出生效。 <br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。| 53| onDidAppear<sup>19+</sup> | Callback<void> | 否 | 是 | 弹窗弹出时的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear >> onDidAppear >> onWillDisappear >> onDidDisappear。<br />2.在onDidAppear内设置改变弹窗显示效果的回调事件，二次弹出生效。<br />3.快速点击弹出，关闭弹窗时，onWillDisappear在onDidAppear前生效。<br/>4.弹窗入场动效未完成时彻底关闭弹窗，动效打断，onDidAppear不会触发。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 54| onWillDisappear<sup>19+</sup> | Callback<void> | 否 | 是 | 弹窗退出动效前的事件回调。<br />**说明：**<br />正常时序依次为：onWillAppear >> onDidAppear >> onWillDisappear >> onDidDisappear。<br /> **原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。| 55| onDidDisappear<sup>19+</sup> | Callback<void> | 否 | 是 | 弹窗消失时的事件回调。<br />**说明：**<br />正常时序依次为：onWillAppear >> onDidAppear >> onWillDisappear >> onDidDisappear。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 56| levelMode<sup>15+</sup> | [LevelMode](../js-apis-promptAction.md#levelmode15枚举说明) | 否 | 是 | 设置弹窗显示层级。<br />**说明：**<br />- 默认值：LevelMode.OVERLAY。<br />- 当且仅当showInSubWindow属性设置为false时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 57| levelUniqueId<sup>15+</sup> | number | 否 | 是 | 设置页面级弹窗需要显示的层级下的[节点uniqueId](../js-apis-arkui-frameNode.md#getuniqueid12)。仅在levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>取值范围：大于等于0的数字。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 58| immersiveMode<sup>15+</sup> | [ImmersiveMode](../js-apis-promptAction.md#immersivemode15枚举说明) | 否 | 是 | 设置页面内弹窗蒙层效果。<br />**说明：**<br />- 默认值：ImmersiveMode.DEFAULT <br />- 当且仅当levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 59| levelOrder<sup>18+</sup> | [LevelOrder](#levelorder18) | 否 | 是 | 设置弹窗显示的顺序。<br />**说明：**<br />- 默认值：LevelOrder.clamp(0) <br />- 不支持动态刷新顺序。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 60 61## LevelOrder<sup>18+</sup> 62 63type LevelOrder = LevelOrder 64 65弹窗的显示顺序。 66 67**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 68 69**系统能力：** SystemCapability.ArkUI.ArkUI.Full 70 71| 类型 | 说明 | 72| ----------------------------------------------------- | -------------------- | 73| [LevelOrder](../js-apis-promptAction.md#levelorder18) | 设置弹窗的显示顺序。 | 74 75## AlertDialogParamWithConfirm对象说明 76 77继承自[AlertDialogParam](#alertdialogparam对象说明)。 78 79**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 80 81**系统能力：** SystemCapability.ArkUI.ArkUI.Full 82 83| 名称 | 类型 | 只读 | 可选 | 说明 | 84| ---------- | ---------------- | ---------- | ------------------------------- | ------------------------------- | 85| confirm | [AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18对象说明) | 否 | 是 | 确认Button的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。在弹窗获焦且未进行tab键走焦时，该按钮默认响应Enter键。多重弹窗情况下，可自动获焦并连续响应。默认响应Enter键能力在defaultFocus为true时不生效。 | 86 87confirm参数优先级：fontColor、backgroundColor > style > defaultFocus 88 89| backgroundColor | fontColor | style | defaultFocus | 效果 | 90| --------------- | --------- | --------------------------- | ------------ | -------- | 91| 绿底 | 红字 | - | - | 绿底红字 | 92| 绿底 | - | DialogButtonStyle.HIGHLIGHT | - | 绿底白字 | 93| 绿底 | - | DialogButtonStyle.DEFAULT | - | 绿底蓝字 | 94| 绿底 | - | - | TRUE | 绿底白字 | 95| 绿底 | - | - | FALSE/- | 绿底蓝字 | 96| - | 红字 | DialogButtonStyle.HIGHLIGHT | - | 蓝底红字 | 97| - | 红字 | DialogButtonStyle.DEFAULT | - | 白底红字 | 98| - | 红字 | - | TRUE | 蓝底红字 | 99| - | 红字 | - | FALSE/- | 白底红字 | 100| - | - | DialogButtonStyle.HIGHLIGHT | - | 蓝底白字 | 101| - | - | DialogButtonStyle.DEFAULT | - | 白底蓝字 | 102| - | - | - | TRUE | 蓝底白字 | 103| - | - | - | FALSE/- | 白底蓝字 | 104 105## AlertDialogParamWithButtons对象说明 106 107继承自[AlertDialogParam](#alertdialogparam对象说明)。 108 109**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 110 111**系统能力：** SystemCapability.ArkUI.ArkUI.Full 112 113| 名称 | 类型 | 只读 | 可选 | 说明 | 114| --------------- | ---------------------- | ------------ | --------------------- | --------------------- | 115| primaryButton | [AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18对象说明) | 否 | 否 | 确认Button的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。在弹窗获焦且未进行tab键走焦时，该按钮默认响应Enter键，且多重弹窗可自动获焦连续响应。默认响应Enter键能力在defaultFocus为true时不生效。 | 116| secondaryButton | [AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18对象说明) | 否 | 否 | 确认Button的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。 | 117 118## AlertDialogParamWithOptions<sup>10+</sup>对象说明 119 120继承自[AlertDialogParam](#alertdialogparam对象说明)。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126| 名称 | 类型 | 只读 | 可选 | 说明 | 127| --------------- | ---------------------- | ------------ | --------------------- | --------------------- | 128| buttons | Array<[AlertDialogButtonOptions](#alertdialogbuttonoptions10对象说明)> | 否 | 否 | 弹窗容器中的多个按钮。 | 129|buttonDirection | [DialogButtonDirection](#dialogbuttondirection10枚举说明)| 否 | 是 | 按钮排布方向默认为DialogButtonDirection.AUTO。建议3个以上按钮使用Auto模式（两个以上按钮会切换为纵向模式，通常能显示更多按钮）。非Auto模式下，3个以上按钮可能会显示不全，超出显示范围的按钮会被截断。| 130 131## AlertDialogButtonOptions<sup>10+</sup>对象说明 132 133继承自[AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18对象说明)。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137| 名称 | 类型 | 只读 | 可选 | 说明 | 138| --------------------- | ------- | ---- | ---- | ------------------------------------------------------------ | 139| primary<sup>12+</sup> | boolean | 否 | 是 | 在弹窗获焦且未进行tab键走焦时，按钮是否默认响应Enter键。多个Button时，只允许一个Button的该字段配置为true，否则所有Button均不响应。多重弹窗可自动获焦连续响应。在defaultFocus为true时不生效。值为true表示按钮默认响应Enter键，值为false时，按钮不默认响应Enter键。<br/>默认值：false <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 140 141## AlertDialogButtonBaseOptions<sup>18+</sup>对象说明 142 143警告弹窗中按钮的样式。 144 145> **说明：** 146> 147> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 148 149**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 150 151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 152 153| 名称 | 类型 | 只读 | 可选 | 说明 | 154| ------------------| ---------------------- | ------------ | --------------------- | --------------------- | 155| enabled<sup>10+</sup> | boolean | 否 | 是 | 点击Button是否响应，默认值true。<br/>值为true时，Button可以响应。值为false时，Button不可以响应。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 156| defaultFocus<sup>10+</sup> | boolean | 否 | 是 | 设置Button是否是默认焦点，默认值false。值为true表示Button为默认焦点，值为false表示Button不为默认焦点。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 157| style<sup>10+</sup> | [DialogButtonStyle](ts-appendix-enums.md#dialogbuttonstyle10) | 否 | 是 | 设置Button的风格样式，默认值DialogButtonStyle.DEFAULT。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 158| value<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 否 | Button的文本内容，若值为null，则该按钮不显示。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 159| fontColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | Button的文本颜色。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 160| backgroundColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | Button背景颜色。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 161| action<sup>10+</sup> | [VoidCallback](ts-types.md#voidcallback12) | 否 | 否 | Button选中时的回调。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 162 163## DialogButtonDirection<sup>10+</sup>枚举说明 164 165警告弹窗中按钮的对齐方式。 166 167**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 168 169**系统能力：** SystemCapability.ArkUI.ArkUI.Full 170 171| 名称 | 值 | 说明 | 172| -------------------------- | --------- | --------- | 173| AUTO | 0 | 两个及以下按钮水平排布，两个以上为竖直排布。 | 174| HORIZONTAL | 1 | 按钮水平布局。 | 175| VERTICAL | 2 | 按钮竖直布局。 | 176 177## DialogAlignment枚举说明 178 179警告弹窗的对齐方式。 180 181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185| 名称 | 说明 | 186| ------------------------ | -------------- | 187| Top | 垂直顶部对齐。 | 188| Center | 垂直居中对齐。 | 189| Bottom | 垂直底部对齐。 | 190| Default | 默认对齐。 | 191| TopStart<sup>8+</sup> | 左上对齐。 | 192| TopEnd<sup>8+</sup> | 右上对齐。 | 193| CenterStart<sup>8+</sup> | 左中对齐。 | 194| CenterEnd<sup>8+</sup> | 右中对齐。 | 195| BottomStart<sup>8+</sup> | 左下对齐。 | 196| BottomEnd<sup>8+</sup> | 右下对齐。 | 197 198## Rectangle<sup>8+</sup>类型说明 199 200Rectangle是各种Dialog中maskRect参数的类型。 201 202**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 203 204**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 205 206**系统能力：** SystemCapability.ArkUI.ArkUI.Full 207 208| 名称 | 类型 | 只读 | 可选 | 说明 | 209|--------|------------------------------|----|-----------------------------------|-----------------------------------| 210| x | [Length](ts-types.md#length) | 否 | 是 | 弹窗遮蔽层区域相对于窗口左上角的x轴坐标。<br/>默认值：0vp | 211| y | [Length](ts-types.md#length) | 否 | 是 | 弹窗遮蔽层区域相对于窗口左上角的y轴坐标。<br/>默认值：0vp | 212| width | [Length](ts-types.md#length) | 否 | 是 | 弹窗遮蔽层区域的宽度。<br/>默认值：'100%' | 213| height | [Length](ts-types.md#length) | 否 | 是 | 弹窗遮蔽层区域的高度。<br/>默认值：'100%' | 214 215> **说明：** 216> 217> x和y可以设置正负值百分比。当x设置为'100%'时表示遮蔽层区域往右偏移窗口本身宽度大小，当x设置为'-100%'时表示遮蔽层区域往左偏移窗口本身宽度大小。当y设置为'100%'时表示遮蔽层区域往下偏移窗口本身高度大小，当y设置为'-100%'时表示遮蔽层区域往上偏移窗口本身高度大小。 218> 219> width和height只能设置正值，支持百分比，如果设置为负值，那么该值将被重置为默认值。 220> 221> 百分比相对于窗口自身宽高进行计算。 222 223## DismissDialogAction<sup>12+</sup> 224 225Dialog关闭的信息。 226 227**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 228 229**系统能力：** SystemCapability.ArkUI.ArkUI.Full 230 231### 属性 232 233| 名称 | 类型 | 可读 | 可写 | 说明 | 234| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 235| dismiss | Callback<void> | 否 | 否 | Dialog关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 236| reason | [DismissReason](ts-universal-attributes-popup.md#dismissreason12枚举说明) | 否 | 否 | Dialog无法关闭原因。根据开发者需要选择不同操作下，Dialog是否需要关闭。 | 237 238## TextStyle<sup>12+</sup>对象说明 239 240弹窗中message的截断方式。 241 242**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 243 244**系统能力：** SystemCapability.ArkUI.ArkUI.Full 245 246| 名称 | 类型 | 必填 | 说明 | 247|--------|------------------------------|----|-----------------------------------| 248| wordBreak | [WordBreak](ts-appendix-enums.md#wordbreak11) | 否 | 弹窗message内容的文本截断方式。<br/>默认值：WordBreak.BREAK_ALL | 249 250## AlertDialog 251 252### show<sup>(deprecated)</sup> 253 254static show(value: AlertDialogParamWithConfirm | AlertDialogParamWithButtons | AlertDialogParamWithOptions) 255 256定义警告弹窗并弹出。 257 258> **说明：** 259> 260> 从API version 18开始废弃，建议使用[UIContext](../arkts-apis-uicontext-uicontext.md)中的[showAlertDialog](../arkts-apis-uicontext-uicontext.md#showalertdialog)替代。 261> 262> 从API version 10开始，可以通过使用[UIContext](../arkts-apis-uicontext-uicontext.md)中的[showAlertDialog](../arkts-apis-uicontext-uicontext.md#showalertdialog)来明确UI的执行上下文。 263 264**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.ArkUI.ArkUI.Full 267 268**参数：** 269 270| 参数名 | 类型 | 必填 | 说明 | 271| ---- | --------------- | -------- | -------- | 272| value | [AlertDialogParamWithConfirm](#alertdialogparamwithconfirm对象说明) \| [AlertDialogParamWithButtons](#alertdialogparamwithbuttons对象说明) \| [AlertDialogParamWithOptions](#alertdialogparamwithoptions10对象说明)<sup>10+</sup> | 是 | 定义并显示AlertDialog组件。 | 273 274## 示例 275 276> **说明：** 277> 278> 直接使用AlertDialog可能导致[UI上下文不明确](../../../ui/arkts-global-interface.md)的问题，建议使用getUIContext()获取[UIContext](../arkts-apis-uicontext-uicontext.md)实例，并使用[showAlertDialog](../arkts-apis-uicontext-uicontext.md#showalertdialog)调用绑定实例的AlertDialog.show()。 279 280### 示例1（弹出多个按钮的弹窗） 281 282该示例实现了分别弹出一、二、三个按钮的弹窗。 283 284```ts 285// xxx.ets 286@Entry 287@Component 288struct AlertDialogExample { 289 build() { 290 Column({ space: 5 }) { 291 Button('one button dialog') 292 .onClick(() => { 293 this.getUIContext().showAlertDialog( 294 { 295 title: 'title', 296 message: 'text', 297 autoCancel: true, 298 alignment: DialogAlignment.Bottom, 299 offset: { dx: 0, dy: -20 }, 300 gridCount: 3, 301 confirm: { 302 value: 'button', 303 action: () => { 304 console.info('Button-clicking callback'); 305 } 306 }, 307 cancel: () => { 308 console.info('Closed callbacks'); 309 }, 310 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 311 console.info(`reason= ${dismissDialogAction.reason}`); 312 console.info('AlertDialog onWillDismiss'); 313 if (dismissDialogAction.reason === DismissReason.PRESS_BACK) { 314 dismissDialogAction.dismiss(); 315 } 316 if (dismissDialogAction.reason === DismissReason.TOUCH_OUTSIDE) { 317 dismissDialogAction.dismiss(); 318 } 319 } 320 } 321 ) 322 }) 323 .backgroundColor(0x317aff) 324 Button('two button dialog') 325 .onClick(() => { 326 this.getUIContext().showAlertDialog( 327 { 328 title: 'title', 329 subtitle: 'subtitle', 330 message: 'text', 331 autoCancel: true, 332 alignment: DialogAlignment.Bottom, 333 gridCount: 4, 334 offset: { dx: 0, dy: -20 }, 335 primaryButton: { 336 value: 'cancel', 337 action: () => { 338 console.info('Callback when the first button is clicked'); 339 } 340 }, 341 secondaryButton: { 342 enabled: true, 343 defaultFocus: true, 344 style: DialogButtonStyle.HIGHLIGHT, 345 value: 'ok', 346 action: () => { 347 console.info('Callback when the second button is clicked'); 348 } 349 }, 350 cancel: () => { 351 console.info('Closed callbacks'); 352 }, 353 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 354 console.info(`reason= ${dismissDialogAction.reason}`); 355 console.info('AlertDialog onWillDismiss'); 356 if (dismissDialogAction.reason === DismissReason.PRESS_BACK) { 357 dismissDialogAction.dismiss(); 358 } 359 if (dismissDialogAction.reason === DismissReason.TOUCH_OUTSIDE) { 360 dismissDialogAction.dismiss(); 361 } 362 } 363 } 364 ) 365 }).backgroundColor(0x317aff) 366 Button('three button dialog') 367 .onClick(() => { 368 this.getUIContext().showAlertDialog( 369 { 370 title: 'title', 371 subtitle: 'subtitle', 372 message: 'text', 373 autoCancel: true, 374 alignment: DialogAlignment.Bottom, 375 gridCount: 4, 376 offset: { dx: 0, dy: -20 }, 377 buttonDirection: DialogButtonDirection.HORIZONTAL, 378 buttons: [ 379 { 380 value: '按钮', 381 action: () => { 382 console.info('Callback when button1 is clicked'); 383 } 384 }, 385 { 386 value: '按钮', 387 action: () => { 388 console.info('Callback when button2 is clicked'); 389 } 390 }, 391 { 392 value: '按钮', 393 enabled: true, 394 defaultFocus: true, 395 style: DialogButtonStyle.HIGHLIGHT, 396 action: () => { 397 console.info('Callback when button3 is clicked'); 398 } 399 }, 400 ], 401 cancel: () => { 402 console.info('Closed callbacks'); 403 }, 404 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 405 console.info(`reason= ${dismissDialogAction.reason}`); 406 console.info('AlertDialog onWillDismiss'); 407 if (dismissDialogAction.reason === DismissReason.PRESS_BACK) { 408 dismissDialogAction.dismiss(); 409 } 410 if (dismissDialogAction.reason === DismissReason.TOUCH_OUTSIDE) { 411 dismissDialogAction.dismiss(); 412 } 413 } 414 } 415 ) 416 }).backgroundColor(0x317aff) 417 }.width('100%').margin({ top: 5 }) 418 } 419} 420``` 421 422 423 424### 示例2（可在主窗外弹出的弹窗） 425 426在2in1设备上设置showInSubWindow为true时，可以弹出在主窗外显示的弹窗。 427 428```ts 429// xxx.ets 430@Entry 431@Component 432struct AlertDialogExample { 433 build() { 434 Column({ space: 5 }) { 435 Button('one button dialog') 436 .onClick(() => { 437 this.getUIContext().showAlertDialog( 438 { 439 title: 'title', 440 subtitle: 'subtitle', 441 message: 'text', 442 autoCancel: true, 443 alignment: DialogAlignment.Center, 444 gridCount: 4, 445 showInSubWindow: true, 446 isModal: true, 447 offset: { dx: 0, dy: -20 }, 448 buttonDirection: DialogButtonDirection.HORIZONTAL, 449 buttons: [ 450 { 451 value: '按钮', 452 action: () => { 453 console.info('Callback when button1 is clicked'); 454 } 455 }, 456 { 457 value: '按钮', 458 action: () => { 459 console.info('Callback when button2 is clicked'); 460 } 461 }, 462 { 463 value: '按钮', 464 enabled: true, 465 defaultFocus: true, 466 style: DialogButtonStyle.HIGHLIGHT, 467 action: () => { 468 console.info('Callback when button3 is clicked'); 469 } 470 }, 471 ], 472 cancel: () => { 473 console.info('Closed callbacks'); 474 }, 475 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 476 console.info(`reason= ${dismissDialogAction.reason}`); 477 console.info('AlertDialog onWillDismiss'); 478 if (dismissDialogAction.reason === DismissReason.PRESS_BACK) { 479 dismissDialogAction.dismiss(); 480 } 481 if (dismissDialogAction.reason === DismissReason.TOUCH_OUTSIDE) { 482 dismissDialogAction.dismiss(); 483 } 484 } 485 }) 486 }) 487 }.width('100%').margin({ top: 5 }) 488 } 489} 490``` 491 492 493 494### 示例3（设置弹窗的动画） 495 496该示例通过配置transition实现弹窗的显示和消失动画。 497 498```ts 499// xxx.ets 500@Entry 501@Component 502struct AlertDialogExample { 503 build() { 504 Column({ space: 5 }) { 505 Button('AlertDialog Set Duration') 506 .onClick(() => { 507 this.getUIContext().showAlertDialog( 508 { 509 title: 'AlertDialog 1', 510 message: 'Set Animation Duration open 3 second, close 100ms', 511 autoCancel: true, 512 alignment: DialogAlignment.Top, 513 offset: { dx: 0, dy: -20 }, 514 gridCount: 3, 515 transition: TransitionEffect.asymmetric(TransitionEffect.OPACITY 516 .animation({ duration: 3000, curve: Curve.Sharp }) 517 .combine(TransitionEffect.scale({ x: 1.5, y: 1.5 }).animation({ duration: 3000, curve: Curve.Sharp })), 518 TransitionEffect.OPACITY.animation({ duration: 100, curve: Curve.Smooth }) 519 .combine(TransitionEffect.scale({ x: 0.5, y: 0.5 }) 520 .animation({ duration: 100, curve: Curve.Smooth }))), 521 confirm: { 522 value: 'button', 523 action: () => { 524 console.info('Button-clicking callback'); 525 } 526 }, 527 cancel: () => { 528 console.info('Closed callbacks'); 529 } 530 } 531 ) 532 }) 533 .backgroundColor(0x317aff).height('88px') 534 }.width('100%').margin({ top: 5 }) 535 } 536} 537``` 538 539 540 541### 示例4（设置弹窗的样式） 542 543示例定义了AlertDialog的样式，包括宽度、高度、背景色、阴影等。 544 545```ts 546// xxx.ets 547@Entry 548@Component 549struct AlertDialogExample { 550 build() { 551 Column({ space: 5 }) { 552 Button('one button dialog') 553 .onClick(() => { 554 this.getUIContext().showAlertDialog( 555 { 556 title: 'title', 557 message: 'text', 558 autoCancel: true, 559 alignment: DialogAlignment.Center, 560 offset: { dx: 0, dy: -20 }, 561 gridCount: 3, 562 width: 300, 563 height: 200, 564 cornerRadius: 20, 565 borderWidth: 1, 566 borderStyle: BorderStyle.Dashed, //使用borderStyle属性，需要和borderWidth属性一起使用 567 borderColor: Color.Blue, //使用borderColor属性，需要和borderWidth属性一起使用 568 backgroundColor: Color.White, 569 shadow: ({ 570 radius: 20, 571 color: Color.Grey, 572 offsetX: 50, 573 offsetY: 0 574 }), 575 textStyle: { wordBreak: WordBreak.BREAK_ALL }, 576 confirm: { 577 value: 'button', 578 action: () => { 579 console.info('Button-clicking callback'); 580 } 581 }, 582 cancel: () => { 583 console.info('Closed callbacks'); 584 }, 585 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 586 console.info(`reason= ${dismissDialogAction.reason}`); 587 console.info('AlertDialog onWillDismiss'); 588 if (dismissDialogAction.reason === DismissReason.PRESS_BACK) { 589 dismissDialogAction.dismiss(); 590 } 591 if (dismissDialogAction.reason === DismissReason.TOUCH_OUTSIDE) { 592 dismissDialogAction.dismiss(); 593 } 594 } 595 } 596 ) 597 }) 598 .backgroundColor(0x317aff) 599 }.width('100%').margin({ top: 5 }) 600 } 601} 602``` 603 604 605 606### 示例5（悬停态弹窗） 607 608<!--RP1-->该示例展示了在悬停态下设置dialog布局区域的效果。<!--RP1End--> 609 610```ts 611// xxx.ets 612@Entry 613@Component 614struct AlertDialogExample { 615 build() { 616 Column({ space: 5 }) { 617 Button('one button dialog') 618 .onClick(() => { 619 this.getUIContext().showAlertDialog( 620 { 621 title: 'title', 622 message: 'text', 623 autoCancel: true, 624 alignment: DialogAlignment.Bottom, 625 gridCount: 3, 626 confirm: { 627 value: 'button', 628 action: () => { 629 console.info('Button-clicking callback'); 630 } 631 }, 632 cancel: () => { 633 console.info('Closed callbacks'); 634 }, 635 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 636 console.info(`reason= ${dismissDialogAction.reason}`); 637 console.info('AlertDialog onWillDismiss'); 638 if (dismissDialogAction.reason === DismissReason.PRESS_BACK) { 639 dismissDialogAction.dismiss(); 640 } 641 if (dismissDialogAction.reason === DismissReason.TOUCH_OUTSIDE) { 642 dismissDialogAction.dismiss(); 643 } 644 }, 645 enableHoverMode: true, 646 hoverModeArea: HoverModeAreaType.TOP_SCREEN 647 } 648 ) 649 }) 650 .backgroundColor(0x317aff) 651 }.width('100%').margin({ top: 5 }) 652 } 653} 654``` 655 656<!--RP2--><!--RP2End--> 657 658### 示例6（弹窗生命周期） 659 660该示例展示了弹窗生命周期的相关接口的使用方法。 661 662```ts 663// xxx.ets 664@Entry 665@Component 666struct Example2 { 667 @State log: string = 'Log information:'; 668 669 build() { 670 Column({ space: 5 }) { 671 Button('AlertDialog') 672 .onClick(() => { 673 this.getUIContext().showAlertDialog({ 674 title: 'AlertDialog', 675 message: 'message', 676 autoCancel: true, 677 alignment: DialogAlignment.Bottom, 678 offset: { dx: 0, dy: -20 }, 679 confirm: { 680 value: 'button', 681 action: () => { 682 console.info('AlertDialog Button-clicking callback'); 683 } 684 }, 685 cancel: () => { 686 console.info('Closed callbacks'); 687 }, 688 onDidAppear: () => { 689 this.log += '# onDidAppear'; 690 console.info('AlertDialog,is onDidAppear!'); 691 }, 692 onDidDisappear: () => { 693 this.log += '# onDidDisappear'; 694 console.info('AlertDialog,is onDidDisappear!'); 695 }, 696 onWillAppear: () => { 697 this.log = 'Log information:onWillAppear'; 698 console.info('AlertDialog,is onWillAppear!'); 699 }, 700 onWillDisappear: () => { 701 this.log += '# onWillDisappear'; 702 console.info('AlertDialog,is onWillDisappear!'); 703 } 704 }) 705 }) 706 Text(this.log).fontSize(30).margin({ top: 200 }) 707 }.width('100%').margin({ top: 5 }) 708 } 709} 710``` 711 712 713 714### 示例7（自定义背景模糊效果参数） 715 716从API version 19开始，该示例通过配置[backgroundBlurStyleOptions](#alertdialogparam对象说明)，实现自定义背景模糊效果。 717 718```ts 719@Entry 720@Component 721struct AlertDialogExample { 722 build() { 723 Stack({ alignContent: Alignment.Top }) { 724 // $r('app.media.bg')需要替换为开发者所需的图像资源文件。 725 Image($r('app.media.bg')) 726 Column() { 727 Button("AlertDialog") 728 .margin(20) 729 .onClick(() => { 730 this.getUIContext().showAlertDialog({ 731 title: 'AlertDialog Title', 732 message: 'AlertDialog Text', 733 primaryButton: { 734 value: '确定', 735 action: () => { 736 console.info('primaryButton'); 737 } 738 }, 739 secondaryButton: { 740 value: '取消', 741 action: () => { 742 console.info('secondaryButton'); 743 } 744 }, 745 backgroundColor: undefined, 746 backgroundBlurStyle: BlurStyle.Thin, 747 backgroundBlurStyleOptions: { 748 colorMode: ThemeColorMode.LIGHT, 749 adaptiveColor: AdaptiveColor.AVERAGE, 750 scale: 1, 751 blurOptions: { grayscale: [20, 20] }, 752 }, 753 }); 754 }) 755 }.width('100%') 756 } 757 } 758} 759``` 760 761 762 763### 示例8（自定义背景效果参数） 764 765从API version 19开始，该示例通过配置[backgroundEffect](#alertdialogparam对象说明)，实现自定义背景效果。 766 767```ts 768@Entry 769@Component 770struct AlertDialogExample { 771 build() { 772 Stack({ alignContent: Alignment.Top }) { 773 // $r('app.media.bg')需要替换为开发者所需的图像资源文件。 774 Image($r('app.media.bg')) 775 Column() { 776 Button("AlertDialog") 777 .margin(20) 778 .onClick(() => { 779 this.getUIContext().showAlertDialog({ 780 title: 'AlertDialog Title', 781 message: 'AlertDialog Text', 782 primaryButton: { 783 value: '确定', 784 action: () => { 785 console.info('primaryButton'); 786 } 787 }, 788 secondaryButton: { 789 value: '取消', 790 action: () => { 791 console.info('secondaryButton'); 792 } 793 }, 794 backgroundColor: undefined, 795 backgroundBlurStyle: BlurStyle.Thin, 796 backgroundEffect: { 797 radius: 60, 798 saturation: 0, 799 brightness: 1, 800 color: Color.White, 801 blurOptions: { grayscale: [20, 20] } 802 }, 803 }); 804 }) 805 }.width('100%') 806 } 807 } 808} 809``` 810 811
