1# ArkUI_NativeDialogAPI_1 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @houguobiao--> 5<!--Designer: @liyi0309--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9## 概述 10 11ArkUI提供的Native侧自定义弹窗接口集合。 12 13**起始版本：** 12 14 15**相关模块：** [ArkUI_NativeModule](capi-arkui-nativemodule.md) 16 17**所在头文件：** [native_dialog.h](capi-native-dialog-h.md) 18 19## 汇总 20 21### 成员函数 22 23| 名称 | 描述 | 24| -- | -- | 25| [ArkUI_NativeDialogHandle (\*create)()](#create) | 创建自定义弹窗并返回指向自定义弹窗的指针。 | 26| [void (\*dispose)(ArkUI_NativeDialogHandle handle)](#dispose) | 销毁自定义弹窗。 | 27| [int32_t (\*setContent)(ArkUI_NativeDialogHandle handle, ArkUI_NodeHandle content)](#setcontent) | 挂载自定义弹窗内容。 | 28| [int32_t (\*removeContent)(ArkUI_NativeDialogHandle handle)](#removecontent) | 卸载自定义弹窗内容。 | 29| [int32_t (\*setContentAlignment)(ArkUI_NativeDialogHandle handle, int32_t alignment, float offsetX, float offsetY)](#setcontentalignment) | 设置自定义弹窗对齐方式。 | 30| [int32_t (\*resetContentAlignment)(ArkUI_NativeDialogHandle handle)](#resetcontentalignment) | 重置setContentAlignment方法设置的属性，使用系统默认的对齐方式。 | 31| [int32_t (\*setModalMode)(ArkUI_NativeDialogHandle handle, bool isModal)](#setmodalmode) | 设置自定义弹窗是否开启模态样式的弹窗。 | 32| [int32_t (\*setAutoCancel)(ArkUI_NativeDialogHandle handle, bool autoCancel)](#setautocancel) | 设置自定义弹窗是否允许通过点击遮罩层退出。 | 33| [int32_t (\*setMask)(ArkUI_NativeDialogHandle handle, uint32_t maskColor, const ArkUI_Rect* maskRect)](#setmask) | 设置自定义弹窗遮罩属性。 | 34| [int32_t (\*setBackgroundColor)(ArkUI_NativeDialogHandle handle, uint32_t backgroundColor)](#setbackgroundcolor) | 设置弹窗背景色。 | 35| [int32_t (\*setCornerRadius)(ArkUI_NativeDialogHandle handle, float topLeft, float topRight,float bottomLeft, float bottomRight)](#setcornerradius) | 设置弹窗背板圆角半径。 | 36| [int32_t (\*setGridColumnCount)(ArkUI_NativeDialogHandle handle, int32_t gridCount)](#setgridcolumncount) | 设置弹窗宽度占栅格宽度的个数。 | 37| [int32_t (\*enableCustomStyle)(ArkUI_NativeDialogHandle handle, bool enableCustomStyle)](#enablecustomstyle) | 弹窗容器样式是否可以自定义。 | 38| [int32_t (\*enableCustomAnimation)(ArkUI_NativeDialogHandle handle, bool enableCustomAnimation)](#enablecustomanimation) | 弹窗容器是否使用自定义弹窗动画。 | 39| [int32_t (\*registerOnWillDismiss)(ArkUI_NativeDialogHandle handle, ArkUI_OnWillDismissEvent eventHandler)](#registeronwilldismiss) | 当触发系统定义的返回操作、键盘ESC关闭交互操作时，如果注册了该回调函数，弹窗不会立即关闭，而是由用户决定是否关闭。 | 40| [int32_t (\*show)(ArkUI_NativeDialogHandle handle, bool showInSubWindow)](#show) | 显示自定义弹窗。 | 41| [int32_t (\*close)(ArkUI_NativeDialogHandle handle)](#close) | 关闭自定义弹窗，如已关闭，则不生效。 | 42| [int32_t (\*registerOnWillDismissWithUserData)(ArkUI_NativeDialogHandle handle, void* userData, void (\*callback)(ArkUI_DialogDismissEvent* event))](#registeronwilldismisswithuserdata) | 注册系统关闭自定义弹窗的监听事件。 | 43 44## 成员函数说明 45 46### create() 47 48``` 49ArkUI_NativeDialogHandle (*create)() 50``` 51 52**描述：** 53 54创建自定义弹窗并返回指向自定义弹窗的指针。 55 56> **说明：** 57> 58> create方法需要在调用[show](#show)方法之前调用。 59 60**返回：** 61 62| 类型 | 说明 | 63|------------------------------| -- | 64| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) | 返回指向自定义弹窗的指针，如果创建失败，则返回空指针。 | 65 66### dispose() 67 68``` 69void (*dispose)(ArkUI_NativeDialogHandle handle) 70``` 71 72**描述：** 73 74 75销毁自定义弹窗。 76 77### setContent() 78 79``` 80int32_t (*setContent)(ArkUI_NativeDialogHandle handle, ArkUI_NodeHandle content) 81``` 82 83**描述：** 84 85挂载自定义弹窗内容。 86 87> **说明：** 88> 89> setContent方法需要在调用[show](#show)方法之前调用。 90 91**参数：** 92 93| 参数项 | 描述 | 94|------------------------------------------------------------------------------------| -- | 95| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 96| [ArkUI_NodeHandle](capi-arkui-nativemodule-arkui-node8h.md) content | 弹窗内容根节点指针。 | 97 98**返回：** 99 100| 类型 | 说明 | 101| -- | -- | 102| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 103 104### removeContent() 105 106``` 107int32_t (*removeContent)(ArkUI_NativeDialogHandle handle) 108``` 109 110**描述：** 111 112卸载自定义弹窗内容。 113 114> **说明：** 115> 116> removeContent方法需要在调用[show](#show)方法之前调用。 117 118**参数：** 119 120| 参数项 | 描述 | 121| -- | -- | 122| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 123 124**返回：** 125 126| 类型 | 说明 | 127| -- | -- | 128| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 129 130### setContentAlignment() 131 132``` 133int32_t (*setContentAlignment)(ArkUI_NativeDialogHandle handle, int32_t alignment, float offsetX, float offsetY) 134``` 135 136**描述：** 137 138设置自定义弹窗对齐方式。 139 140> **说明：** 141> 142> setContentAlignment方法需要在调用[show](#show)方法之前调用。 143 144**参数：** 145 146| 参数项 | 描述 | 147| -- | -- | 148| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 149| int32_t alignment | 对齐方式，参数类型ArkUI_Alignment。 | 150| float offsetX | 弹窗的水平偏移量，浮点型。 | 151| float offsetY | 弹窗的垂直偏移量，浮点型。 | 152 153**返回：** 154 155| 类型 | 说明 | 156| -- | -- | 157| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 158 159### resetContentAlignment() 160 161``` 162int32_t (*resetContentAlignment)(ArkUI_NativeDialogHandle handle) 163``` 164 165**描述：** 166 167重置setContentAlignment方法设置的属性，使用系统默认的对齐方式。 168 169> **说明：** 170> 171> resetContentAlignment方法需要在调用[show](#show)方法之前调用。 172 173**参数：** 174 175| 参数项 | 描述 | 176| -- | -- | 177| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 178 179**返回：** 180 181| 类型 | 说明 | 182| -- | -- | 183| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 184 185### setModalMode() 186 187``` 188int32_t (*setModalMode)(ArkUI_NativeDialogHandle handle, bool isModal) 189``` 190 191**描述：** 192 193设置自定义弹窗是否开启模态样式的弹窗。 194 195> **说明：** 196> 197> setModalMode方法需要在调用[show](#show)方法之前调用。 198 199**参数：** 200 201| 参数项 | 描述 | 202| -- | -- | 203| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 204| bool isModal | 设置是否开启模态窗口，模态窗口有蒙层，非模态窗口无蒙层。为true时开启模态窗口，为false时不开启模态窗口。 | 205 206**返回：** 207 208| 类型 | 说明 | 209| -- | -- | 210| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 211 212### setAutoCancel() 213 214``` 215int32_t (*setAutoCancel)(ArkUI_NativeDialogHandle handle, bool autoCancel) 216``` 217 218**描述：** 219 220设置自定义弹窗是否允许通过点击遮罩层退出。 221 222> **说明：** 223> 224> setAutoCancel方法需要在调用[show](#show)方法之前调用。 225 226**参数：** 227 228| 参数项 | 描述 | 229| -- | -- | 230| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 231| bool autoCancel | 设置是否允许通过点击遮罩层退出，true表示关闭弹窗，false表示不关闭弹窗。 | 232 233**返回：** 234 235| 类型 | 说明 | 236| -- | -- | 237| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 238 239### setMask() 240 241``` 242int32_t (*setMask)(ArkUI_NativeDialogHandle handle, uint32_t maskColor, const ArkUI_Rect* maskRect) 243``` 244 245**描述：** 246 247设置自定义弹窗遮罩属性。 248 249> **说明：** 250> 251> setMask方法需要在调用[show](#show)方法之前调用。 252 253**参数：** 254 255| 参数项 | 描述 | 256|------------------------------------------------------------------------------------| -- | 257| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 258| uint32_t maskColor | 设置遮罩颜色，0xargb格式。 | 259| const [ArkUI_Rect](capi-arkui-nativemodule-arkui-rect.md)* maskRect | 遮蔽层区域范围的指针，遮蔽层区域内的事件不透传，在遮蔽层区域外的事件透传。参数类型[ArkUI_Rect](capi-arkui-nativemodule-arkui-rect.md)。 | 260 261**返回：** 262 263| 类型 | 说明 | 264| -- | -- | 265| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 266 267### setBackgroundColor() 268 269``` 270int32_t (*setBackgroundColor)(ArkUI_NativeDialogHandle handle, uint32_t backgroundColor) 271``` 272 273**描述：** 274 275设置弹窗背景色。 276 277> **说明：** 278> 279> setBackgroundColor方法需要在调用[show](#show)方法之前调用。 280 281**参数：** 282 283| 参数项 | 描述 | 284| -- | -- | 285| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 286| uint32_t backgroundColor | 设置弹窗背景颜色，0xargb格式。 | 287 288**返回：** 289 290| 类型 | 说明 | 291| -- | -- | 292| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 293 294### setCornerRadius() 295 296``` 297int32_t (*setCornerRadius)(ArkUI_NativeDialogHandle handle, float topLeft, float topRight,float bottomLeft, float bottomRight) 298``` 299 300**描述：** 301 302设置弹窗背板圆角半径。 303 304> **说明：** 305> 306> setCornerRadius方法需要在调用[show](#show)方法之前调用。 307 308**参数：** 309 310| 参数项 | 描述 | 311| -- | -- | 312| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 313| float topLeft | 设置弹窗背板左上角圆角半径。 | 314| float topRight | 设置弹窗背板右上角圆角半径。 | 315| float bottomLeft | 设置弹窗背板左下圆角半径。 | 316| float bottomRight | 设置弹窗背板右下角圆角半径。 | 317 318**返回：** 319 320| 类型 | 说明 | 321| -- | -- | 322| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 323 324### setGridColumnCount() 325 326``` 327int32_t (*setGridColumnCount)(ArkUI_NativeDialogHandle handle, int32_t gridCount) 328``` 329 330**描述：** 331 332设置弹窗宽度占栅格宽度的个数。 333 334> **说明：** 335> 336> setGridColumnCount方法需要在调用[show](#show)方法之前调用。 337 338**参数：** 339 340| 参数项 | 描述 | 341| -- | -- | 342| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 343| int32_t gridCount | 默认为按照窗口大小自适应，最大栅格数为系统最大栅格数。 | 344 345**返回：** 346 347| 类型 | 说明 | 348| -- | -- | 349| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 350 351### enableCustomStyle() 352 353``` 354int32_t (*enableCustomStyle)(ArkUI_NativeDialogHandle handle, bool enableCustomStyle) 355``` 356 357**描述：** 358 359弹窗容器样式是否可以自定义。 360 361> **说明：** 362> 363> enableCustomStyle方法需要在调用[show](#show)方法之前调用。 364 365**参数：** 366 367| 参数项 | 描述 | 368| -- | -- | 369| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 370| bool enableCustomStyle | true:宽度自适应子节点，圆角为0，弹窗背景色透明；false:高度自适应子节点，宽度由栅格系统定义, 圆角半径24vp。 | 371 372**返回：** 373 374| 类型 | 说明 | 375| -- | -- | 376| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 377 378### enableCustomAnimation() 379 380``` 381int32_t (*enableCustomAnimation)(ArkUI_NativeDialogHandle handle, bool enableCustomAnimation) 382``` 383 384**描述：** 385 386弹窗容器是否使用自定义弹窗动画。 387 388> **说明：** 389> 390> enableCustomAnimation方法需要在调用[show](#show)方法之前调用。 391 392**参数：** 393 394| 参数项 | 描述 | 395| -- | -- | 396| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 397| bool enableCustomAnimation | true:使用自定义动画，关闭系统默认动画；false:使用系统默认动画。 | 398 399**返回：** 400 401| 类型 | 说明 | 402| -- | -- | 403| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 404 405### registerOnWillDismiss() 406 407``` 408int32_t (*registerOnWillDismiss)(ArkUI_NativeDialogHandle handle, ArkUI_OnWillDismissEvent eventHandler) 409``` 410 411**描述：** 412 413当触发系统定义的返回操作、键盘ESC关闭交互操作时，如果注册了该回调函数，弹窗不会立即关闭，而是由用户决定是否关闭。 414 415> **说明：** 416> 417> registerOnWillDismiss方法需要在调用[show](#show)方法之前调用。 418 419**参数：** 420 421| 参数项 | 描述 | 422|-------------------------------------------------------------------------------------------| -- | 423| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 424| [ArkUI_OnWillDismissEvent](capi-native-dialog-h.md#arkui_onwilldismissevent) eventHandler | 弹窗关闭的回调函数。 | 425 426**返回：** 427 428| 类型 | 说明 | 429| -- | -- | 430| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 431 432### show() 433 434``` 435int32_t (*show)(ArkUI_NativeDialogHandle handle, bool showInSubWindow) 436``` 437 438**描述：** 439 440显示自定义弹窗。 441 442**参数：** 443 444| 参数项 | 描述 | 445| -- | -- | 446| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 447| bool showInSubWindow | 是否在子窗口显示弹窗。true表示在子窗显示弹窗。false表示不在子窗显示弹窗。 | 448 449**返回：** 450 451| 类型 | 说明 | 452| -- | -- | 453| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 454 455### close() 456 457``` 458int32_t (*close)(ArkUI_NativeDialogHandle handle) 459``` 460 461**描述：** 462 463 464关闭自定义弹窗，如已关闭，则不生效。 465 466**参数：** 467 468| 参数项 | 描述 | 469| -- | -- | 470| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 471 472**返回：** 473 474| 类型 | 说明 | 475| -- | -- | 476| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 477 478### registerOnWillDismissWithUserData() 479 480``` 481int32_t (*registerOnWillDismissWithUserData)(ArkUI_NativeDialogHandle handle, void* userData, void (*callback)(ArkUI_DialogDismissEvent* event)) 482``` 483 484**描述：** 485 486 487注册系统关闭自定义弹窗的监听事件。 488 489**参数：** 490 491| 参数项 | 描述 | 492| -- | -- | 493| [ArkUI_NativeDialogHandle](capi-arkui-nativemodule-arkui-nativedialog8h.md) handle | 指向自定义弹窗控制器的指针。 | 494| void* userData | 用户自定义数据指针。 | 495| callback | 监听自定义弹窗关闭的回调事件。<br> - event: 回调函数的入参，捕获关闭原因。 | 496 497**返回：** 498 499| 类型 | 说明 | 500| -- | -- | 501| int32_t | 错误码。<br> [ARKUI_ERROR_CODE_NO_ERROR](capi-native-type-h.md#arkui_errorcode) 成功。<br> [ARKUI_ERROR_CODE_PARAM_INVALID](capi-native-type-h.md#arkui_errorcode) 函数参数异常。 | 502 503 504