ts-methods-alert-dialog-box.md 18.1 KB
Newer Older
Z
zengyawen 已提交
1
# 警告弹窗
Z
zengyawen 已提交
2

3 4
显示警告弹窗组件,可设置文本内容与响应回调。

H
geshi  
HelloCrease 已提交
5
>  **说明:**
H
hebingxue 已提交
6
>
Z
zengyawen 已提交
7
> 从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
H
huangdong57 已提交
8 9 10 11
>
> 本模块功能依赖UI的执行上下文,不可在UI上下文不明确的地方使用,参见[UIContext](../apis/js-apis-arkui-UIContext.md#uicontext)说明。
>
> 从API version 10开始,可以通过使用[UIContext](../apis/js-apis-arkui-UIContext.md#uicontext)中的[showAlertDialog](../apis/js-apis-arkui-UIContext.md#showalertdialog)来明确UI的执行上下文。
Z
zengyawen 已提交
12

Z
zengyawen 已提交
13
## 属性
Z
zengyawen 已提交
14

H
hebingxue 已提交
15 16
| 名称    | 参数类型  | 参数描述 |
| ---- | --------------- | -------- |
17
| show | [AlertDialogParamWithConfirm](#alertdialogparamwithconfirm对象说明) \| [AlertDialogParamWithButtons](#alertdialogparamwithbuttons对象说明) \| [AlertDialogParamWithOptions](#alertdialogparamwithoptions10对象说明) | 定义并显示AlertDialog组件。 |
Z
zengyawen 已提交
18

K
kangchongtao 已提交
19
## AlertDialogParamWithConfirm对象说明
H
hebingxue 已提交
20 21 22
| 参数名       | 参数类型     | 必填     | 参数描述         |
| ---------- | ---------------- | ---------- | ------------------------------- |
| title      | [ResourceStr](ts-types.md#resourcestr) | 否    | 弹窗标题。 |
T
tengfan 已提交
23
| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 弹窗副标题。 |
H
hebingxue 已提交
24 25
| message    | [ResourceStr](ts-types.md#resourcestr) | 是    | 弹窗内容。 |
| autoCancel | boolean | 否   | 点击遮障层时,是否关闭弹窗。<br>默认值:true |
T
tengfan 已提交
26
| confirm    | {<br/>enabled<sup>10+</sup>?: boolean,<br/>defaultFocus<sup>10+</sup>?: boolean,<br />style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10枚举说明),<br />value:&nbsp;[ResourceStr](ts-types.md#resourcestr),<br/>fontColor?:&nbsp;[ResourceColor](ts-types.md#resourcecolor),<br/>backgroundColor?:&nbsp;&nbsp;[ResourceColor](ts-types.md#resourcecolor),<br/>action:&nbsp;()&nbsp;=&gt;&nbsp;void<br/>} | 否   | 确认按钮的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。<br />enabled:点击button是否响应。<br />默认值:true。<br />defaultFocus:设置button是否是默认焦点。<br />默认值:false。<br />style:设置button的风格样式。<br />默认值:DialogButtonStyle.DEFAULT。<br />value:按钮文本内容。<br />fontColor:按钮文本颜色。<br />backgroundColor:按钮背景颜色。<br />action:&nbsp;按钮选中时的回调。 |
H
hebingxue 已提交
27
| cancel     | ()&nbsp;=&gt;&nbsp;void      | 否     | 点击遮障层关闭dialog时的回调。 |
28
| alignment  | [DialogAlignment](#dialogalignment枚举说明) | 否   | 弹窗在竖直方向上的对齐方式。<br>默认值:DialogAlignment.Default |
29 30
| offset     | [Offset](ts-types.md#offset) | 否     | 弹窗相对alignment所在位置的偏移量。<br/>默认值:{&nbsp;dx:&nbsp;0&nbsp;,&nbsp;dy:&nbsp;0&nbsp;} |
| gridCount  | number                       | 否     | 弹窗容器宽度所占用栅格数。<br/>默认值:4 |
31
| maskRect<sup>10+</sup>| [Rectangle](#rectangle10类型说明) | 否     | 弹窗遮蔽层区域,在遮蔽层区域内的事件不透传,在遮蔽层区域外的事件透传。<br/>默认值:{ x: 0, y: 0, width: '100%', height: '100%' } |
Z
zengyawen 已提交
32

T
tengfan 已提交
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
confirm参数优先级:fontColor、backgroundColor  > style > defaultFocus

| backgroundColor | fontColor | style                       | defaultFocus | 效果     |
| --------------- | --------- | --------------------------- | ------------ | -------- |
| 绿底            | 红字      | -                           | -            | 绿底红字 |
| 绿底            | -         | DialogButtonStyle.HIGHLIGHT | -            | 绿底白字 |
| 绿底            | -         | DialogButtonStyle.DEFAULT   | -            | 绿底蓝字 |
| 绿底            | -         | -                           | TRUE         | 绿底白字 |
| 绿底            | -         | -                           | FALSE/-      | 绿底蓝字 |
| -               | 红字      | DialogButtonStyle.HIGHLIGHT | -            | 蓝底红字 |
| -               | 红字      | DialogButtonStyle.DEFAULT   | -            | 白底红字 |
| -               | 红字      | -                           | TRUE         | 蓝底红字 |
| -               | 红字      | -                           | FALSE/-      | 白底红字 |
| -               | -         | DialogButtonStyle.HIGHLIGHT | -            | 蓝底白字 |
| -               | -         | DialogButtonStyle.DEFAULT   | -            | 白底蓝字 |
| -               | -         | -                           | TRUE         | 蓝底白字 |
| -               | -         | -                           | FALSE/-      | 白底蓝字 |

K
kangchongtao 已提交
51
## AlertDialogParamWithButtons对象说明
H
hebingxue 已提交
52 53 54
| 参数名             | 参数类型                | 必填     | 参数描述                     |
| --------------- | ---------------------- | ------------ | --------------------- |
| title           | [ResourceStr](ts-types.md#resourcestr) | 否     | 弹窗标题。              |
T
tengfan 已提交
55
| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | 否 | 弹窗副标题。 |
H
hebingxue 已提交
56 57
| message         | [ResourceStr](ts-types.md#resourcestr) | 是     | 弹窗内容。              |
| autoCancel      | boolean           | 否   | 点击遮障层时,是否关闭弹窗。<br>默认值:true      |
T
tengfan 已提交
58 59
| primaryButton   | {<br/>enabled<sup>10+</sup>?: boolean,<br/>defaultFocus<sup>10+</sup>?: boolean,<br />style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10枚举说明),<br />value:&nbsp;[ResourceStr](ts-types.md#resourcestr),<br/>fontColor?:&nbsp;[ResourceColor](ts-types.md#resourcecolor),<br/>backgroundColor?:&nbsp;[ResourceColor](ts-types.md#resourcecolor),<br/>action:&nbsp;()&nbsp;=&gt;&nbsp;void;<br/>} | 否 | 确认按钮的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。<br />enabled:点击button是否响应。<br />默认值:true。<br />defaultFocus:设置button是否是默认焦点。<br />默认值:false。<br />style:设置button的风格样式。<br />默认值:DialogButtonStyle.DEFAULT。<br />value:按钮文本内容。<br />fontColor:按钮文本颜色。<br />backgroundColor:按钮背景颜色。<br />action:&nbsp;按钮选中时的回调。 |
| secondaryButton | {<br/>enabled<sup>10+</sup>?: boolean,<br/>defaultFocus<sup>10+</sup>?: boolean,<br />style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10枚举说明),<br />value:&nbsp;[ResourceStr](ts-types.md#resourcestr),<br/>fontColor?:&nbsp;[ResourceColor](ts-types.md#resourcecolor),<br/>backgroundColor?:&nbsp;[ResourceColor](ts-types.md#resourcecolor),<br/>action:&nbsp;()&nbsp;=&gt;&nbsp;void;<br/>} | 否  | 确认按钮的使能状态、默认焦点、按钮风格、文本内容、文本色、按钮背景色和点击回调。<br />enabled:点击button是否响应。<br />默认值:true。<br />defaultFocus:设置button是否是默认焦点。<br />默认值:false。<br />style:设置button的风格样式。<br />默认值:DialogButtonStyle.DEFAULT。<br />value:按钮文本内容。<br />fontColor:按钮文本颜色。<br />backgroundColor:按钮背景颜色。<br />action:&nbsp;按钮选中时的回调。 |
H
hebingxue 已提交
60
| cancel          | ()&nbsp;=&gt;&nbsp;void      | 否  | 点击遮障层关闭dialog时的回调。         |
61
| alignment       | [DialogAlignment](#dialogalignment枚举说明) | 否   | 弹窗在竖直方向上的对齐方式。<br>默认值:DialogAlignment.Default |
H
hebingxue 已提交
62
| offset          | [Offset](ts-types.md#offset) | 否  | 弹窗相对alignment所在位置的偏移量。 |
M
matchzhou 已提交
63
| gridCount       | number                       | 否  | 弹窗容器宽度所占用栅格数。 |
64
| maskRect<sup>10+</sup> | [Rectangle](#rectangle10类型说明) | 否     | 弹窗遮蔽层区域,在遮蔽层区域内的事件不透传,在遮蔽层区域外的事件透传。<br/>默认值:{ x: 0, y: 0, width: '100%', height: '100%' } |
Z
zengyawen 已提交
65

66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
## AlertDialogParamWithOptions<sup>10+</sup>对象说明
| 参数名             | 参数类型                | 必填     | 参数描述                     |
| --------------- | ---------------------- | ------------ | --------------------- |
| title           | [ResourceStr](ts-types.md#resourcestr) | 否     | 弹窗标题。              |
| subtitle<sup>10+</sup>           | [ResourceStr](ts-types.md#resourcestr) | 否     | 弹窗子标题。              |
| message         | [ResourceStr](ts-types.md#resourcestr) | 是     | 弹窗内容。              |
| autoCancel      | boolean           | 否   | 点击遮障层时,是否关闭弹窗。<br>默认值:true      |
| cancel          | ()&nbsp;=&gt;&nbsp;void      | 否  | 点击遮障层关闭dialog时的回调。         |
| alignment       | [DialogAlignment](#dialogalignment枚举说明) | 否   | 弹窗在竖直方向上的对齐方式。<br>默认值:DialogAlignment.Default |
| offset          | [Offset](ts-types.md#offset) | 否  | 弹窗相对alignment所在位置的偏移量。 |
| gridCount       | number                       | 否  | 弹窗容器宽度所占用栅格数。 |
| maskRect<sup>10+</sup>| [Rectangle](#rectangle10类型说明) | 否     | 弹窗遮蔽层区域,在遮蔽层区域内的事件不透传,在遮蔽层区域外的事件透传。<br/>默认值:{ x: 0, y: 0, width: '100%', height: '100%' } |
| buttons<sup>10+</sup>       | Array&lt;[AlertDialogButtonOptions](#alertdialogbuttonoptions10对象说明)&gt;                 | 否  | 弹窗容器中的多个按钮。 |
|buttonDirection<sup>10+</sup>      | [DialogButtonDirection](#dialogbuttondirection10枚举说明)| 否  | 按钮排布方向默认值为DialogButtonDirection.AUTO,建议3个以上按钮使用Auto模式(两个以上按钮会切换为纵向模式,通常能显示更多按钮),非Auto模式下,3个以上按钮可能会显示不全,超出显示范围的按钮会被截断。|

## AlertDialogButtonOptions<sup>10+</sup>对象说明
| 参数名             | 参数类型                | 必填     | 参数描述                     |
| ------------------| ---------------------- | ------------ | --------------------- |
| enabled           | boolean | 否     | 点击button是否响应,默认值true。              |
| defaultFocus           | boolean | 否     | 设置button是否是默认焦点,默认值false。              |
| style           | [DialogButtonStyle](#dialogbuttonstyle10枚举说明) | 否     | 设置button的风格样式,默认值DialogButtonStyle.DEFAULT。              |
| value           | [ResourceStr](ts-types.md#resourcestr) | 是     | 按钮的文本内容,若值为null,则该按钮不显示。              |
| fontColor           | [ResourceColor](ts-types.md#resourcecolor) | 否     | 按钮的文本颜色。              |
| backgroundColor           | [ResourceColor](ts-types.md#resourcecolor) | 否     | 按钮背景颜色。              |
| action           | 	() => void | 是     | 按钮选中时的回调。              |

## DialogButtonDirection<sup>10+</sup>枚举说明
| 名称                       | 描述      |
| -------------------------- | --------- |
| AUTO                      | 两个及以下按钮水平排布,两个以上为竖直排布。 |
| HORIZONTAL                      | 按钮水平布局。 |
| VERTICAL                      | 按钮竖直布局。 |

T
tengfan 已提交
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
confirm参数优先级:fontColor、backgroundColor  > style > defaultFocus

| backgroundColor | fontColor | style                       | defaultFocus | 效果     |
| --------------- | --------- | --------------------------- | ------------ | -------- |
| 绿底            | 红字      | -                           | -            | 绿底红字 |
| 绿底            | -         | DialogButtonStyle.HIGHLIGHT | -            | 绿底白字 |
| 绿底            | -         | DialogButtonStyle.DEFAULT   | -            | 绿底蓝字 |
| 绿底            | -         | -                           | TRUE         | 绿底白字 |
| 绿底            | -         | -                           | FALSE/-      | 绿底蓝字 |
| -               | 红字      | DialogButtonStyle.HIGHLIGHT | -            | 蓝底红字 |
| -               | 红字      | DialogButtonStyle.DEFAULT   | -            | 白底红字 |
| -               | 红字      | -                           | TRUE         | 蓝底红字 |
| -               | 红字      | -                           | FALSE/-      | 白底红字 |
| -               | -         | DialogButtonStyle.HIGHLIGHT | -            | 蓝底白字 |
| -               | -         | DialogButtonStyle.DEFAULT   | -            | 白底蓝字 |
| -               | -         | -                           | TRUE         | 蓝底白字 |
| -               | -         | -                           | FALSE/-      | 白底蓝字 |

117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
## DialogAlignment枚举说明

| 名称                       | 描述      |
| ------------------------ | ------- |
| Top                      | 垂直顶部对齐。 |
| Center                   | 垂直居中对齐。 |
| Bottom                   | 垂直底部对齐。 |
| Default                  | 默认对齐。   |
| TopStart<sup>8+</sup>    | 左上对齐。   |
| TopEnd<sup>8+</sup>      | 右上对齐。   |
| CenterStart<sup>8+</sup> | 左中对齐。   |
| CenterEnd<sup>8+</sup>   | 右中对齐。   |
| BottomStart<sup>8+</sup> | 左下对齐。   |
| BottomEnd<sup>8+</sup>   | 右下对齐。   |

132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
## Rectangle<sup>10+</sup>类型说明

Rectangle是各种Dialog中maskRect参数的类型。

| 名称     | 类型                           | 必填 | 描述                                |
|--------|------------------------------|----|-----------------------------------|
| x      | [Length](ts-types.md#length) | 否  | 弹窗遮蔽层区域相对于窗口左上角的x轴坐标。<br/>默认值:0vp |
| y      | [Length](ts-types.md#length) | 否  | 弹窗遮蔽层区域相对于窗口左上角的y轴坐标。<br/>默认值:0vp |
| width  | [Length](ts-types.md#length) | 否  | 弹窗遮蔽层区域的宽度。<br/>默认值:'100%'        |
| height | [Length](ts-types.md#length) | 否  | 弹窗遮蔽层区域的高度。<br/>默认值:'100%'        |

>  **说明:**
>
>  x和y可以设置正负值百分比。当x设置为'100%'时表示遮蔽层区域往右偏移窗口本身宽度大小,当x设置为'-100%'时表示遮蔽层区域往左偏移窗口本身宽度大小。当y设置为'100%'时表示遮蔽层区域往下偏移窗口本身高度大小,当y设置为'-100%'时表示遮蔽层区域往上偏移窗口本身高度大小。
>
>  width和height只能设置正值,支持百分比,如果设置为负值,那么该值将被重置为默认值。
>
>  百分比相对于窗口自身宽高进行计算。

T
tengfan 已提交
151 152 153 154 155 156 157
## DialogButtonStyle<sup>10+</sup>枚举说明

| 名称      | 描述                              |
| --------- | --------------------------------- |
| DEFAULT   | 白底蓝字(深色主题:白底=黑底)。 |
| HIGHLIGHT | 蓝底白字。                        |

Z
zengyawen 已提交
158
## 示例
Z
zengyawen 已提交
159

H
geshi  
HelloCrease 已提交
160 161
```ts
// xxx.ets
Z
zengyawen 已提交
162 163 164 165 166 167 168 169 170 171 172
@Entry
@Component
struct AlertDialogExample {
  build() {
    Column({ space: 5 }) {
      Button('one button dialog')
        .onClick(() => {
          AlertDialog.show(
            {
              title: 'title',
              message: 'text',
M
match 已提交
173 174 175 176
              autoCancel: true,
              alignment: DialogAlignment.Bottom,
              offset: { dx: 0, dy: -20 },
              gridCount: 3,
Z
zengyawen 已提交
177 178 179 180 181 182 183 184 185 186 187
              confirm: {
                value: 'button',
                action: () => {
                  console.info('Button-clicking callback')
                }
              },
              cancel: () => {
                console.info('Closed callbacks')
              }
            }
          )
M
match 已提交
188
        })
Z
zengyawen 已提交
189 190 191 192 193 194
        .backgroundColor(0x317aff)
      Button('two button dialog')
        .onClick(() => {
          AlertDialog.show(
            {
              title: 'title',
T
tengfan 已提交
195
              subtitle: 'subtitle',
Z
zengyawen 已提交
196
              message: 'text',
M
match 已提交
197 198 199 200
              autoCancel: true,
              alignment: DialogAlignment.Bottom,
              gridCount: 4,
              offset: { dx: 0, dy: -20 },
Z
zengyawen 已提交
201 202 203 204 205 206 207
              primaryButton: {
                value: 'cancel',
                action: () => {
                  console.info('Callback when the first button is clicked')
                }
              },
              secondaryButton: {
T
tengfan 已提交
208 209 210
                enabled: true,
                defaultFocus: true,
                style: DialogButtonStyle.HIGHLIGHT,
Z
zengyawen 已提交
211 212 213 214 215 216 217 218 219 220
                value: 'ok',
                action: () => {
                  console.info('Callback when the second button is clicked')
                }
              },
              cancel: () => {
                console.info('Closed callbacks')
              }
            }
          )
M
match 已提交
221
        }).backgroundColor(0x317aff)
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
        Button('three button dialog')
        .onClick(() => {
          AlertDialog.show(
            {
              title: 'title',
              subtitle: 'subtitle',
              message: 'text',
              autoCancel: true,
              alignment: DialogAlignment.Bottom,
              gridCount: 4,
              offset: { dx: 0, dy: -20 },
              buttonDirection: DialogButtonDirection.HORIZONTAL,
              buttons: [
                {
                  value: '按钮',
                  action: () => {
                    console.info('Callback when button1 is clicked')
                  }
                },
                {
                  value: '按钮',
                  action: () => {
                    console.info('Callback when button2 is clicked')
                  }
                },
                {
                  value: '按钮',
                  enabled: true,
                  defaultFocus: true,
                  style: DialogButtonStyle.HIGHLIGHT,
                  action: () => {
                    console.info('Callback when button3 is clicked')
                  }
                },
              ],
              cancel: () => {
                console.info('Closed callbacks')
              }
            }
          )
        }).backgroundColor(0x317aff)
Z
zengyawen 已提交
263 264 265 266 267
    }.width('100%').margin({ top: 5 })
  }
}
```

T
tengfan 已提交
268
![zh-cn_image_alert](figures/zh-cn_image_alert.gif)