1# 警告弹窗 (AlertDialog) 2 3显示警告弹窗组件，可设置文本内容与响应回调。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](../js-apis-arkui-UIContext.md#uicontext)说明。 10> 11> 从API version 10开始，可以通过使用[UIContext](../js-apis-arkui-UIContext.md#uicontext)中的[showAlertDialog](../js-apis-arkui-UIContext.md#showalertdialog)来明确UI的执行上下文。 12 13## 属性 14 15| 名称 | 参数类型 | 参数描述 | 16| ---- | --------------- | -------- | 17| show | [AlertDialogParamWithConfirm](#alertdialogparamwithconfirm对象说明) \| [AlertDialogParamWithButtons](#alertdialogparamwithbuttons对象说明) \| [AlertDialogParamWithOptions](#alertdialogparamwithoptions10对象说明)<sup>10+</sup> | 定义并显示AlertDialog组件。 | 18 19## AlertDialogParam对象说明 20 21| 名称 | 类型 | 必填 | 描述 | 22| --------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 23| title | [ResourceStr](ts-types.md#resourcestr) | 否 | 弹窗标题。 | 24| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 弹窗副标题。 | 25| message | [ResourceStr](ts-types.md#resourcestr) | 是 | 弹窗内容。 | 26| autoCancel | boolean | 否 | 点击遮障层时，是否关闭弹窗，true表示关闭弹窗。false表示不关闭弹窗。<br/>默认值：true | 27| cancel | () => void | 否 | 点击遮障层关闭dialog时的回调。 | 28| alignment | [DialogAlignment](#dialogalignment枚举说明) | 否 | 弹窗在竖直方向上的对齐方式。<br/>默认值：DialogAlignment.Default | 29| offset | [Offset](ts-types.md#offset) | 否 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 } | 30| gridCount | number | 否 | 弹窗容器宽度所占用栅格数。<br/>默认值：4 | 31| maskRect<sup>10+</sup> | [Rectangle](#rectangle8类型说明) | 否 | 弹窗遮蔽层区域，在遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传。<br/>默认值：{ x: 0, y: 0, width: '100%', height: '100%' } <br/>**说明：**<br/>showInSubWindow为true时，maskRect不生效。| 32| showInSubWindow<sup>11+</sup> | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。<br/>**说明**：showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。 | 33| isModal<sup>11+</sup> | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。 | 34| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 弹窗背板颜色。<br/>默认值：Color.Transparent | 35| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-appendix-enums.md#blurstyle9) | 否 | 弹窗背板模糊材质。<br/>默认值：BlurStyle.COMPONENT_ULTRA_THICK | 36 37## AlertDialogParamWithConfirm对象说明 38 39继承自[AlertDialogParam](#alertdialogparam对象说明)。 40 41| 参数名 | 参数类型 | 必填 | 参数描述 | 42| ---------- | ---------------- | ---------- | ------------------------------- | 43| confirm | {<br/>enabled<sup>10+</sup>?: boolean,<br/>defaultFocus<sup>10+</sup>?: boolean,<br />style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10枚举说明),<br />value: [ResourceStr](ts-types.md#resourcestr),<br/>fontColor?: [ResourceColor](ts-types.md#resourcecolor),<br/>backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),<br/>action: () => void<br/>} | 否 | 确认Button的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。<br />enabled：点击Button是否响应，true表示Button可以响应，false表示Button不可以响应。<br />默认值：true<br />defaultFocus：设置Button是否是默认焦点，true表示Button是默认焦点，false表示Button不是默认焦点。<br />默认值：false<br />style：设置Button的风格样式。<br />默认值：DialogButtonStyle.DEFAULT。<br />value：Button文本内容。<br />fontColor：Button文本颜色。<br />backgroundColor：Button背景颜色。<br />action： Button选中时的回调。 | 44 45## AlertDialogParamWithButtons对象说明 46 47继承自[AlertDialogParam](#alertdialogparam对象说明)。 48 49| 参数名 | 参数类型 | 必填 | 参数描述 | 50| --------------- | ---------------------- | ------------ | --------------------- | 51| primaryButton | {<br/>enabled<sup>10+</sup>?: boolean,<br/>defaultFocus<sup>10+</sup>?: boolean,<br />style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10枚举说明),<br />value: [ResourceStr](ts-types.md#resourcestr),<br/>fontColor?: [ResourceColor](ts-types.md#resourcecolor),<br/>backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),<br/>action: () => void;<br/>} | 否 | 确认Button的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。<br />enabled：点击Button是否响应。<br />默认值：true<br />defaultFocus：设置Button是否是默认焦点。<br />默认值：false<br />style：设置Button的风格样式。<br />默认值：DialogButtonStyle.DEFAULT。<br />value：Button文本内容。<br />fontColor：Button文本颜色。<br />backgroundColor：Button背景颜色。<br />action： Button选中时的回调。 | 52| secondaryButton | {<br/>enabled<sup>10+</sup>?: boolean,<br/>defaultFocus<sup>10+</sup>?: boolean,<br />style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10枚举说明),<br />value: [ResourceStr](ts-types.md#resourcestr),<br/>fontColor?: [ResourceColor](ts-types.md#resourcecolor),<br/>backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),<br/>action: () => void;<br/>} | 否 | 确认Button的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。<br />enabled：点击Button是否响应。<br />默认值：true。<br />defaultFocus：设置Button是否是默认焦点。<br />默认值：false。<br />style：设置Button的风格样式。<br />默认值：DialogButtonStyle.DEFAULT。<br />value：Button文本内容。<br />fontColor：Button文本颜色。<br />backgroundColor：Button背景颜色。<br />action： Button选中时的回调。 | 53 54## AlertDialogParamWithOptions<sup>10+</sup>对象说明 55 56继承自[AlertDialogParam](#alertdialogparam对象说明)。 57 58| 参数名 | 参数类型 | 必填 | 参数描述 | 59| --------------- | ---------------------- | ------------ | --------------------- | 60| buttons<sup>10+</sup> | Array<[AlertDialogButtonOptions](#alertdialogbuttonoptions10对象说明)> | 否 | 弹窗容器中的多个按钮。 | 61|buttonDirection<sup>10+</sup> | [DialogButtonDirection](#dialogbuttondirection10枚举说明)| 否 | 按钮排布方向默认值为DialogButtonDirection.AUTO，建议3个以上按钮使用Auto模式（两个以上按钮会切换为纵向模式，通常能显示更多按钮），非Auto模式下，3个以上按钮可能会显示不全，超出显示范围的按钮会被截断。| 62 63## AlertDialogButtonOptions<sup>10+</sup>对象说明 64| 参数名 | 参数类型 | 必填 | 参数描述 | 65| ------------------| ---------------------- | ------------ | --------------------- | 66| enabled | boolean | 否 | 点击Button是否响应，默认值true。 | 67| defaultFocus | boolean | 否 | 设置Button是否是默认焦点，默认值false。 | 68| style | [DialogButtonStyle](#dialogbuttonstyle10枚举说明) | 否 | 设置Button的风格样式，默认值DialogButtonStyle.DEFAULT。 | 69| value | [ResourceStr](ts-types.md#resourcestr) | 是 | Button的文本内容，若值为null，则该按钮不显示。 | 70| fontColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | Button的文本颜色。 | 71| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | Button背景颜色。 | 72| action | () => void | 是 | Button选中时的回调。 | 73 74## DialogButtonDirection<sup>10+</sup>枚举说明 75| 名称 | 描述 | 76| -------------------------- | --------- | 77| AUTO | 两个及以下按钮水平排布，两个以上为竖直排布。 | 78| HORIZONTAL | 按钮水平布局。 | 79| VERTICAL | 按钮竖直布局。 | 80 81confirm参数优先级：fontColor、backgroundColor > style > defaultFocus 82 83| backgroundColor | fontColor | style | defaultFocus | 效果 | 84| --------------- | --------- | --------------------------- | ------------ | -------- | 85| 绿底 | 红字 | - | - | 绿底红字 | 86| 绿底 | - | DialogButtonStyle.HIGHLIGHT | - | 绿底白字 | 87| 绿底 | - | DialogButtonStyle.DEFAULT | - | 绿底蓝字 | 88| 绿底 | - | - | TRUE | 绿底白字 | 89| 绿底 | - | - | FALSE/- | 绿底蓝字 | 90| - | 红字 | DialogButtonStyle.HIGHLIGHT | - | 蓝底红字 | 91| - | 红字 | DialogButtonStyle.DEFAULT | - | 白底红字 | 92| - | 红字 | - | TRUE | 蓝底红字 | 93| - | 红字 | - | FALSE/- | 白底红字 | 94| - | - | DialogButtonStyle.HIGHLIGHT | - | 蓝底白字 | 95| - | - | DialogButtonStyle.DEFAULT | - | 白底蓝字 | 96| - | - | - | TRUE | 蓝底白字 | 97| - | - | - | FALSE/- | 白底蓝字 | 98 99## DialogAlignment枚举说明 100 101| 名称 | 描述 | 102| ------------------------ | ------- | 103| Top | 垂直顶部对齐。 | 104| Center | 垂直居中对齐。 | 105| Bottom | 垂直底部对齐。 | 106| Default | 默认对齐。 | 107| TopStart<sup>8+</sup> | 左上对齐。 | 108| TopEnd<sup>8+</sup> | 右上对齐。 | 109| CenterStart<sup>8+</sup> | 左中对齐。 | 110| CenterEnd<sup>8+</sup> | 右中对齐。 | 111| BottomStart<sup>8+</sup> | 左下对齐。 | 112| BottomEnd<sup>8+</sup> | 右下对齐。 | 113 114## Rectangle<sup>8+</sup>类型说明 115 116Rectangle是各种Dialog中maskRect参数的类型。 117 118| 名称 | 类型 | 必填 | 描述 | 119|--------|------------------------------|----|-----------------------------------| 120| x | [Length](ts-types.md#length) | 否 | 弹窗遮蔽层区域相对于窗口左上角的x轴坐标。<br/>默认值：0vp | 121| y | [Length](ts-types.md#length) | 否 | 弹窗遮蔽层区域相对于窗口左上角的y轴坐标。<br/>默认值：0vp | 122| width | [Length](ts-types.md#length) | 否 | 弹窗遮蔽层区域的宽度。<br/>默认值：'100%' | 123| height | [Length](ts-types.md#length) | 否 | 弹窗遮蔽层区域的高度。<br/>默认值：'100%' | 124 125> **说明：** 126> 127> x和y可以设置正负值百分比。当x设置为'100%'时表示遮蔽层区域往右偏移窗口本身宽度大小，当x设置为'-100%'时表示遮蔽层区域往左偏移窗口本身宽度大小。当y设置为'100%'时表示遮蔽层区域往下偏移窗口本身高度大小，当y设置为'-100%'时表示遮蔽层区域往上偏移窗口本身高度大小。 128> 129> width和height只能设置正值，支持百分比，如果设置为负值，那么该值将被重置为默认值。 130> 131> 百分比相对于窗口自身宽高进行计算。 132 133## DialogButtonStyle<sup>10+</sup>枚举说明 134 135| 名称 | 描述 | 136| --------- | --------------------------------- | 137| DEFAULT | 白底蓝字（深色主题：白底=黑底）。 | 138| HIGHLIGHT | 蓝底白字。 | 139 140## 示例 141 142### 示例1 143 144```ts 145// xxx.ets 146@Entry 147@Component 148struct AlertDialogExample { 149 build() { 150 Column({ space: 5 }) { 151 Button('one button dialog') 152 .onClick(() => { 153 AlertDialog.show( 154 { 155 title: 'title', 156 message: 'text', 157 autoCancel: true, 158 alignment: DialogAlignment.Bottom, 159 offset: { dx: 0, dy: -20 }, 160 gridCount: 3, 161 confirm: { 162 value: 'button', 163 action: () => { 164 console.info('Button-clicking callback') 165 } 166 }, 167 cancel: () => { 168 console.info('Closed callbacks') 169 } 170 } 171 ) 172 }) 173 .backgroundColor(0x317aff) 174 Button('two button dialog') 175 .onClick(() => { 176 AlertDialog.show( 177 { 178 title: 'title', 179 subtitle: 'subtitle', 180 message: 'text', 181 autoCancel: true, 182 alignment: DialogAlignment.Bottom, 183 gridCount: 4, 184 offset: { dx: 0, dy: -20 }, 185 primaryButton: { 186 value: 'cancel', 187 action: () => { 188 console.info('Callback when the first button is clicked') 189 } 190 }, 191 secondaryButton: { 192 enabled: true, 193 defaultFocus: true, 194 style: DialogButtonStyle.HIGHLIGHT, 195 value: 'ok', 196 action: () => { 197 console.info('Callback when the second button is clicked') 198 } 199 }, 200 cancel: () => { 201 console.info('Closed callbacks') 202 } 203 } 204 ) 205 }).backgroundColor(0x317aff) 206 Button('three button dialog') 207 .onClick(() => { 208 AlertDialog.show( 209 { 210 title: 'title', 211 subtitle: 'subtitle', 212 message: 'text', 213 autoCancel: true, 214 alignment: DialogAlignment.Bottom, 215 gridCount: 4, 216 offset: { dx: 0, dy: -20 }, 217 buttonDirection: DialogButtonDirection.HORIZONTAL, 218 buttons: [ 219 { 220 value: '按钮', 221 action: () => { 222 console.info('Callback when button1 is clicked') 223 } 224 }, 225 { 226 value: '按钮', 227 action: () => { 228 console.info('Callback when button2 is clicked') 229 } 230 }, 231 { 232 value: '按钮', 233 enabled: true, 234 defaultFocus: true, 235 style: DialogButtonStyle.HIGHLIGHT, 236 action: () => { 237 console.info('Callback when button3 is clicked') 238 } 239 }, 240 ], 241 cancel: () => { 242 console.info('Closed callbacks') 243 } 244 } 245 ) 246 }).backgroundColor(0x317aff) 247 }.width('100%').margin({ top: 5 }) 248 } 249} 250``` 251 252 253 254### 示例2 255 256```ts 257// xxx.ets 258@Entry 259@Component 260struct AlertDialogExample { 261 build() { 262 Column({ space: 5 }) { 263 Button('one button dialog') 264 .onClick(() => { 265 AlertDialog.show( 266 { 267 title: 'title', 268 subtitle: 'subtitle', 269 message: 'text', 270 autoCancel: true, 271 alignment: DialogAlignment.Center, 272 gridCount: 4, 273 showInSubWindow: true, 274 isModal: true, 275 offset: { dx: 0, dy: -20 }, 276 buttonDirection: DialogButtonDirection.HORIZONTAL, 277 buttons: [ 278 { 279 value: '按钮', 280 action: () => { 281 console.info('Callback when button1 is clicked') 282 } 283 }, 284 { 285 value: '按钮', 286 action: () => { 287 console.info('Callback when button2 is clicked') 288 } 289 }, 290 { 291 value: '按钮', 292 enabled: true, 293 defaultFocus: true, 294 style: DialogButtonStyle.HIGHLIGHT, 295 action: () => { 296 console.info('Callback when button3 is clicked') 297 } 298 }, 299 ], 300 cancel: () => { 301 console.info('Closed callbacks') 302 } 303 } 304 ) 305 }).backgroundColor(0x317aff) 306 }.width('100%').margin({ top: 5 }) 307 } 308} 309``` 310 311
