1# 自定义弹窗 (CustomDialog) 2 3通过CustomDialogController类显示自定义弹窗。使用弹窗组件时，可优先考虑自定义弹窗，便于自定义弹窗的样式与内容。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 接口 11 12CustomDialogController(value: CustomDialogControllerOptions) 13 14配置自定义弹窗的参数。 15 16> **说明：** 17> 18> 自定义弹窗的所有参数，不支持动态刷新。 19 20**系统能力：** SystemCapability.ArkUI.ArkUI.Full 21 22**参数：** 23 24| 参数名 | 类型 | 必填 | 说明 | 25| ------ | ------------------------------------------------------------ | ---- | ---------------------- | 26| value | [CustomDialogControllerOptions](#customdialogcontrolleroptions对象说明) | 是 | 配置自定义弹窗的参数。 | 27 28## CustomDialogControllerOptions对象说明 29 30| 名称 | 参数类型 | 必填 | 描述 | 31| ----------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 32| builder | [CustomDialog](../../../ui/arkts-common-components-custom-dialog.md) | 是 | 自定义弹窗内容构造器。<br/>**说明：** <br/>若builder构造器使用回调函数作为入参，请注意使用this绑定问题，如build: custombuilder({ callback: ()=> {...}})。 | 33| cancel | () => void | 否 | 返回、ESC键和点击遮障层弹窗退出时的回调。 | 34| autoCancel | boolean | 否 | 是否允许点击遮障层退出，true表示关闭弹窗。false表示不关闭弹窗。<br>默认值：true | 35| alignment | [DialogAlignment](ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否 | 弹窗在竖直方向上的对齐方式。<br>默认值：DialogAlignment.Default | 36| offset | [Offset](ts-types.md#offset) | 否 | 弹窗相对alignment所在位置的偏移量。 | 37| customStyle | boolean | 否 | 弹窗容器样式是否自定义。<br>默认值：false，弹窗容器的宽度根据栅格系统自适应，不跟随子节点；高度自适应子节点，最大为窗口高度的90%；圆角为24vp。<br>设置为true时，宽度跟随子节点自适应，圆角为0，弹窗背景色为透明色。 | 38| gridCount<sup>8+</sup> | number | 否 | 弹窗宽度占[栅格宽度](../../../ui/arkts-layout-development-grid-layout.md)的个数。<br>默认为按照窗口大小自适应，异常值按默认值处理，最大栅格数为系统最大栅格数。 | 39| maskColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 自定义蒙层颜色。<br>默认值: 0x33000000 | 40| maskRect<sup>10+</sup> | [Rectangle](ts-methods-alert-dialog-box.md#rectangle8类型说明) | 否 | 弹窗遮蔽层区域，在遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传。<br/>默认值：{ x: 0, y: 0, width: '100%', height: '100%' } <br/>**说明：**<br/>showInSubWindow为true时，maskRect不生效。| 41| openAnimation<sup>10+</sup> | [AnimateParam](ts-explicit-animation.md#animateparam对象说明) | 否 | 自定义设置弹窗弹出的动画效果相关参数。<br>**说明**：<br>tempo默认值为1，当设置小于0的值时按默认值处理。<br/>iterations默认值为1，默认播放一次，设置为其他数值时按默认值处理。<br>playMode控制动画播放模式，默认值为PlayMode.Normal，设置为其他数值时按照默认值处理。 | 42| closeAnimation<sup>10+</sup> | [AnimateParam](ts-explicit-animation.md#animateparam对象说明) | 否 | 自定义设置弹窗关闭的动画效果相关参数。<br>**说明**：<br>tempo默认值为1，当设置小于0的值时按默认值处理。<br/>iterations默认值为1，默认播放一次，设置为其他数值时按默认值处理。<br>playMode控制动画播放模式，默认值为PlayMode.Normal，设置为其他数值时按照默认值处理。<br/>页面转场切换时，建议使用默认关闭动效。 | 43| showInSubWindow<sup>10+</sup> | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br>默认值：false，弹窗显示在应用内，而非独立子窗口。<br>**说明**：showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。 | 44| backgroundColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置弹窗背板填充。<br />**说明**：如果同时设置了内容构造器的背景色，则backgroundColor会被内容构造器的背景色覆盖。 | 45| cornerRadius<sup>10+</sup> | [BorderRadiuses](ts-types.md#borderradiuses9) \| [Dimension](ts-types.md#dimension10) | 否 | 设置背板的圆角半径。<br />可分别设置4个圆角的半径。<br />默认值：{ topLeft: '24vp', topRight: '24vp', bottomLeft: '24vp', bottomRight: '24vp' }<br />**说明**：自定义弹窗默认的背板圆角半径为24vp，如果需要使用cornerRadius属性，请和[borderRadius](ts-universal-attributes-border.md#borderradius)属性一起使用。 | 46| isModal<sup>11+</sup> | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。 | 47 48> **说明：** 49> 50> - 按下返回键和ESC键时会让弹窗退出。 51> - 自定义弹窗仅适用于简单提示场景，不能替代页面使用。由于弹窗存在完全避让输入法行为，即在软键盘弹出时，会自动向上抬起软键盘高度，因此如果弹窗高度过大时，可能会导致部分区域不可见。 52 53## CustomDialogController 54 55### 导入对象 56 57```ts 58dialogController : CustomDialogController | null = new CustomDialogController(CustomDialogControllerOptions) 59``` 60**说明**：CustomDialogController仅在作为@CustomDialog和@Component struct的成员变量，且在@Component struct内部定义时赋值才有效，具体用法可看下方示例。 61 62### open 63open(): void 64 65 66显示自定义弹窗内容，允许多次使用，但如果弹框为SubWindow模式，则该弹框不允许再弹出SubWindow弹框。 67 68 69### close 70close(): void 71 72 73关闭显示的自定义弹窗，若已关闭，则不生效。 74 75## 示例 76 77### 示例1 78 79```ts 80// xxx.ets 81@CustomDialog 82struct CustomDialogExampleTwo { 83 controllerTwo?: CustomDialogController 84 build() { 85 Column() { 86 Text('我是第二个弹窗') 87 .fontSize(30) 88 .height(100) 89 Button('点我关闭第二个弹窗') 90 .onClick(() => { 91 if (this.controllerTwo != undefined) { 92 this.controllerTwo.close() 93 } 94 }) 95 .margin(20) 96 } 97 } 98} 99@CustomDialog 100struct CustomDialogExample { 101 @Link textValue: string 102 @Link inputValue: string 103 dialogControllerTwo: CustomDialogController | null = new CustomDialogController({ 104 builder: CustomDialogExampleTwo(), 105 alignment: DialogAlignment.Bottom, 106 offset: { dx: 0, dy: -25 } }) 107 controller?: CustomDialogController 108 // 若尝试在CustomDialog中传入多个其他的Controller，以实现在CustomDialog中打开另一个或另一些CustomDialog，那么此处需要将指向自己的controller放在所有controller的后面 109 cancel: () => void = () => { 110 } 111 confirm: () => void = () => { 112 } 113 114 build() { 115 Column() { 116 Text('Change text').fontSize(20).margin({ top: 10, bottom: 10 }) 117 TextInput({ placeholder: '', text: this.textValue }).height(60).width('90%') 118 .onChange((value: string) => { 119 this.textValue = value 120 }) 121 Text('Whether to change a text?').fontSize(16).margin({ bottom: 10 }) 122 Flex({ justifyContent: FlexAlign.SpaceAround }) { 123 Button('cancel') 124 .onClick(() => { 125 if (this.controller != undefined) { 126 this.controller.close() 127 this.cancel() 128 } 129 }).backgroundColor(0xffffff).fontColor(Color.Black) 130 Button('confirm') 131 .onClick(() => { 132 if (this.controller != undefined) { 133 this.inputValue = this.textValue 134 this.controller.close() 135 this.confirm() 136 } 137 }).backgroundColor(0xffffff).fontColor(Color.Red) 138 }.margin({ bottom: 10 }) 139 140 Button('点我打开第二个弹窗') 141 .onClick(() => { 142 if (this.dialogControllerTwo != null) { 143 this.dialogControllerTwo.open() 144 } 145 }) 146 .margin(20) 147 }.borderRadius(10) 148 // 如果需要使用border属性或cornerRadius属性，请和borderRadius属性一起使用。 149 } 150} 151@Entry 152@Component 153struct CustomDialogUser { 154 @State textValue: string = '' 155 @State inputValue: string = 'click me' 156 dialogController: CustomDialogController | null = new CustomDialogController({ 157 builder: CustomDialogExample({ 158 cancel: ()=> { this.onCancel() }, 159 confirm: ()=> { this.onAccept() }, 160 textValue: $textValue, 161 inputValue: $inputValue 162 }), 163 cancel: this.exitApp, 164 autoCancel: true, 165 alignment: DialogAlignment.Bottom, 166 offset: { dx: 0, dy: -20 }, 167 gridCount: 4, 168 customStyle: false, 169 cornerRadius: 10, 170 }) 171 172 // 在自定义组件即将析构销毁时将dialogControlle置空 173 aboutToDisappear() { 174 this.dialogController = null // 将dialogController置空 175 } 176 177 onCancel() { 178 console.info('Callback when the first button is clicked') 179 } 180 181 onAccept() { 182 console.info('Callback when the second button is clicked') 183 } 184 185 exitApp() { 186 console.info('Click the callback in the blank area') 187 } 188 build() { 189 Column() { 190 Button(this.inputValue) 191 .onClick(() => { 192 if (this.dialogController != null) { 193 this.dialogController.open() 194 } 195 }).backgroundColor(0x317aff) 196 }.width('100%').margin({ top: 5 }) 197 } 198} 199``` 200 201 202 203### 示例2 204 205```ts 206// xxx.ets 207@CustomDialog 208struct CustomDialogExample { 209 controller?: CustomDialogController 210 cancel: () => void = () => { 211 } 212 confirm: () => void = () => { 213 } 214 build() { 215 Column() { 216 Text('可展示在主窗口外的弹窗') 217 .fontSize(30) 218 .height(100) 219 Button('点我关闭弹窗') 220 .onClick(() => { 221 if (this.controller != undefined) { 222 this.controller.close() 223 } 224 }) 225 .margin(20) 226 } 227 } 228} 229@Entry 230@Component 231struct CustomDialogUser { 232 dialogController: CustomDialogController | null = new CustomDialogController({ 233 builder: CustomDialogExample({ 234 cancel: ()=> { this.onCancel() }, 235 confirm: ()=> { this.onAccept() } 236 }), 237 cancel: this.existApp, 238 autoCancel: true, 239 alignment: DialogAlignment.Center, 240 offset: { dx: 0, dy: -20 }, 241 gridCount: 4, 242 showInSubWindow: true, 243 isModal: true, 244 customStyle: false, 245 cornerRadius: 10, 246 }) 247 // 在自定义组件即将析构销毁时将dialogControlle置空 248 aboutToDisappear() { 249 this.dialogController = null // 将dialogController置空 250 } 251 252 onCancel() { 253 console.info('Callback when the first button is clicked') 254 } 255 256 onAccept() { 257 console.info('Callback when the second button is clicked') 258 } 259 260 existApp() { 261 console.info('Click the callback in the blank area') 262 } 263 264 build() { 265 Column() { 266 Button('click me') 267 .onClick(() => { 268 if (this.dialogController != null) { 269 this.dialogController.open() 270 } 271 }).backgroundColor(0x317aff) 272 }.width('100%').margin({ top: 5 }) 273 } 274} 275``` 276 277 278
