1# Custom Dialog Box 2 3A custom dialog box is a dialog box you customize by using APIs of the **CustomDialogController** class. You can set the style and content to your preference for a custom dialog box. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10 11 12## APIs 13 14CustomDialogController(value:{builder: CustomDialog, cancel?: () => void, autoCancel?: boolean, alignment?: DialogAlignment, offset?: Offset, customStyle?: boolean, gridCount?: number, maskColor?: ResourceColor, maskRect?: Rectangle, openAnimation?: AnimateParam, closeAniamtion?: AnimateParam, showInSubWindow?: boolean, backgroundColor?:ResourceColor, cornerRadius?:Dimension \| BorderRadiuses}) 15 16**Parameters** 17 18| Name | Type | Mandatory | Description | 19| ----------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 20| builder | CustomDialog | Yes | Builder of the custom dialog box content. | 21| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay exits. | 22| autoCancel | boolean | No | Whether to allow users to click the overlay to exit.<br>Default value: **true** | 23| alignment | [DialogAlignment](ts-methods-alert-dialog-box.md#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**| 24| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position. | 25| customStyle | boolean | No | Whether to use a custom style for the dialog box.<br>Default value: **false**, which means that the dialog box automatically adapts its width to the grid system and its height to the child components; the maximum height is 90% of the container height; the rounded corner is 24 vp.| 26| gridCount<sup>8+</sup> | number | No | Number of [grid columns](../../ui/arkts-layout-development-grid-layout.md) occupied by the dialog box.<br>The default value is subject to the window size, and the maximum value is the maximum number of columns supported by the system. If this parameter is set to an invalid value, the default value is used.| 27| maskColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No | Custom mask color.<br>Default value: **0x33000000** | 28| maskRect<sup>10+</sup> | [Rectangle](ts-methods-alert-dialog-box.md#rectangle10) | No | Mask area of the dialog box. Events outside the mask area are transparently transmitted, and events within the mask area are not.<br>Default value: **{ x: 0, y: 0, width: '100%', height: '100%' }**| 29| openAnimation<sup>10+</sup> | [AnimateParam](ts-explicit-animation.md#animateparam) | No | Parameters for defining the open animation of the dialog box.<br>**NOTE**<br>**iterations**: The default value is **1**, indicating that the animation is played once; any other value evaluates to the default value.<br>**playMode**: The default value is **PlayMode.Normal**; any other value evaluates to the default value.| 30| closeAniamtion<sup>10+</sup> | [AnimateParam](ts-explicit-animation.md#animateparam) | No | Parameters for defining the close animation of the dialog box.<br>**NOTE**<br>**iterations**: The default value is **1**, indicating that the animation is played once; any other value evaluates to the default value.<br>**playMode**: The default value is **PlayMode.Normal**; any other value evaluates to the default value. | 31| showInSubWindow<sup>10+</sup> | boolean | No | Whether to display a dialog box in a subwindow.<br>Default value: **false**, indicating that the dialog box is not displayed in the subwindow<br>**NOTE**<br>A dialog box whose **showInSubWindow** attribute is **true** cannot trigger the display of another dialog box whose **showInSubWindow** attribute is also **true**.| 32| backgroundColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the dialog box.<br>**NOTE**<br>If the content builder also has the background color set, the background color set here will be overridden by the background color of the content builder.| 33| cornerRadius<sup>10+</sup> | [BorderRadiuses](ts-types.md#borderradiuses9) \| [Dimension](ts-types.md#dimension10) | No | Radius of the rounded corners of the background.<br>You can set separate radiuses for the four rounded corners.<br>Default value: **{ topLeft: '24vp', topRight: '24vp', bottomLeft: '24vp', bottomRight: '24vp' }**<br>**NOTE**<br>This attribute must be used together with the [borderRadius](ts-universal-attributes-border.md) attribute.| 34 35## CustomDialogController 36 37### Objects to Import 38 39``` 40let dialogController : CustomDialogController = new CustomDialogController(...) 41``` 42> **NOTE** 43> 44> **CustomDialogController** is valid only when it is a member variable of the **@CustomDialog** and **@Component** decorated struct and is defined in the **@Component** decorated struct. For details, see the following example. 45 46### open() 47open(): void 48 49 50Opens the content of the custom dialog box. This API can be called multiple times. If the dialog box displayed in a subwindow, no new subwindow is allowed. 51 52 53### close 54close(): void 55 56 57Closes the custom dialog box. If the dialog box is closed, this API does not take effect. 58 59 60## Example 61 62```ts 63// xxx.ets 64@CustomDialog 65struct CustomDialogExample { 66 @Link textValue: string 67 @Link inputValue: string 68 controller?: CustomDialogController 69 // You can pass in multiple other controllers in the CustomDialog to open one or more other CustomDialogs in the CustomDialog. In this case, you must place the controller pointing to the self at the end. 70 cancel: () => void = () => {} 71 confirm: () => void = () => {} 72 73 build() { 74 Column() { 75 Text('Change text').fontSize(20).margin({ top: 10, bottom: 10 }) 76 TextInput({ placeholder: '', text: this.textValue }).height(60).width('90%') 77 .onChange((value: string) => { 78 this.textValue = value 79 }) 80 Text('Whether to change a text?').fontSize(16).margin({ bottom: 10 }) 81 Flex({ justifyContent: FlexAlign.SpaceAround }) { 82 Button('cancel') 83 .onClick(() => { 84 if (this.controller != undefined) { 85 this.controller.close() 86 this.cancel() 87 } 88 }).backgroundColor(0xffffff).fontColor(Color.Black) 89 Button('confirm') 90 .onClick(() => { 91 if (this.controller != undefined) { 92 this.inputValue = this.textValue 93 this.controller.close() 94 this.confirm() 95 } 96 }).backgroundColor(0xffffff).fontColor(Color.Red) 97 }.margin({ bottom: 10 }) 98 }.borderRadius(10) 99 // When using the border or cornerRadius attribute, use it together with the borderRadius attribute. 100 } 101} 102 103@Entry 104@Component 105struct CustomDialogUser { 106 @State textValue: string = '' 107 @State inputValue: string = 'click me' 108 dialogController: CustomDialogController | null = new CustomDialogController({ 109 builder: CustomDialogExample({ 110 cancel: this.onCancel, 111 confirm: this.onAccept, 112 textValue: $textValue, 113 inputValue: $inputValue 114 }), 115 cancel: this.existApp, 116 autoCancel: true, 117 alignment: DialogAlignment.Bottom, 118 offset: { dx: 0, dy: -20 }, 119 gridCount: 4, 120 customStyle: false, 121 backgroundColor: 0xd9ffffff, 122 cornerRadius: 10, 123 }) 124 125 // Set dialogController to null when the custom component is about to be destructed. 126 aboutToDisappear() { 127 this.dialogController = null // Set dialogController to null. 128 } 129 130 onCancel() { 131 console.info('Callback when the first button is clicked') 132 } 133 134 onAccept() { 135 console.info('Callback when the second button is clicked') 136 } 137 138 existApp() { 139 console.info('Click the callback in the blank area') 140 } 141 142 build() { 143 Column() { 144 Button(this.inputValue) 145 .onClick(() => { 146 if (this.dialogController != null) { 147 this.dialogController.open() 148 } 149 }).backgroundColor(0x317aff) 150 }.width('100%').margin({ top: 5 }) 151 } 152} 153``` 154 155 156
