@ohos.promptAction (Prompt)

The PromptAction module provides APIs for creating and showing toasts, dialog boxes, and action menus.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

This module cannot be used in the file declaration of the UIAbility. In other words, the APIs of this module can be used only after a component instance is created; they cannot be called in the lifecycle of the UIAbility.

The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see UIContext. Except for UI-less scenarios such as ServiceExtension, it is recommended that you use the dialog APIs provided by UIContext.

Modules to Import

import { promptAction } from '@kit.ArkUI';

promptAction.openToast¹⁸⁺

openToast(options: ShowToastOptions): Promise<number>

Opens a toast. This API returns the toast ID.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct toastExample {
  @State toastId: number = 0;

  build() {
    Column() {
      Button('Open Toast')
        .height(100)
        .type(ButtonType.Capsule)
        .onClick(() => {
          promptAction.openToast({
            message: 'Toast Message',
            duration: 10000,
          }).then((toastId: number) => {
            this.toastId = toastId;
          })
            .catch((error: BusinessError) => {
              console.error(`openToast error code is ${error.code}, message is ${error.message}`)
            })
        })
      Blank().height(50);
      Button('Close Toast')
        .height(100)
        .type(ButtonType.Capsule)
        .onClick(() => {
          try {
            promptAction.closeToast(this.toastId);
          } catch (error) {
            let message = (error as BusinessError).message;
            let code = (error as BusinessError).code;
            console.error(`CloseToast error code is ${code}, message is ${message}`);
          };
        })
    }.height('100%').width('100%').justifyContent(FlexAlign.Center)
  }
}

promptAction.closeToast¹⁸⁺

closeToast(toastId: number): void

Closes a toast.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

See the example for promptAction.openToaset18.

ShowToastOptions

Describes the options for showing the toast.

System capability: SystemCapability.ArkUI.ArkUI.Full

ToastShowMode¹¹⁺

Describes the mode in which the toast is shown.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

ShowDialogOptions

Describes the options for showing the dialog box.

System capability: SystemCapability.ArkUI.ArkUI.Full

ShowDialogSuccessResponse

Describes the dialog box response result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

ActionMenuOptions

Describes the options for showing the action menu.

System capability: SystemCapability.ArkUI.ArkUI.Full

ActionMenuSuccessResponse

Describes the action menu response result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

DialogController¹⁸⁺

Implements a custom dialog box controller that inherits from CommonController.

It can be used as a member variable of UIContext to display custom dialog boxes. For specific usage, see the examples for openCustomDialogWithController and presentCustomDialog.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

CommonController¹⁸⁺

Implements a common controller for managing components related to promptAction.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

constructor

constructor()

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

close

close(): void

Closes the custom dialog box. If the dialog box is already closed, this API has no effect.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

LevelOrder¹⁸⁺

Defines the display order of a dialog box.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

clamp¹⁸⁺

static clamp(order: number): LevelOrder

Creates a dialog box level with the specified order.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Return value

getOrder¹⁸⁺

getOrder(): number

Obtains the display order of this dialog box.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

DialogOptions¹⁸⁺

Defines the options of the custom dialog box. This API extends BaseDialogOptions.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

DialogOptionsCornerRadius¹⁸⁺

type DialogOptionsCornerRadius = Dimension |BorderRadiuses

Defines the allowed data types for specifying the background corner radius of a dialog box.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

DialogOptionsBorderWidth¹⁸⁺

type DialogOptionsBorderWidth = Dimension |EdgeWidths

Defines the allowed data types for specifying the background border width of a dialog box.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

DialogOptionsBorderColor¹⁸⁺

type DialogOptionsBorderColor = ResourceColor |EdgeColors

Defines the allowed data types for specifying the background border color of a dialog box.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

DialogOptionsBorderStyle¹⁸⁺

type DialogOptionsBorderStyle = BorderStyle |EdgeStyles

Defines the allowed data types for specifying the background border style of a dialog box.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

DialogOptionsShadow¹⁸⁺

type DialogOptionsShadow = ShadowOptions |ShadowStyle

Defines the allowed data types for specifying the background shadow of a dialog box.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.ArkUI.ArkUI.Full

CustomDialogOptions¹¹⁺

Defines the options of a custom dialog box, which inherit from BaseDialogOptions.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

BaseDialogOptions¹¹⁺

Defines the options of the dialog box.

System capability: SystemCapability.ArkUI.ArkUI.Full

DismissDialogAction¹²⁺

Provides information about the action to dismiss the dialog box.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Attributes

DismissReason¹²⁺

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

LevelMode¹⁵⁺

Enumerates the display level modes of the dialog box.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

ImmersiveMode¹⁵⁺

Enumerates the display area modes of the dialog box overlay within a page.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

Button

Describes the menu item button in the action menu.

System capability: SystemCapability.ArkUI.ArkUI.Full

promptAction.showToast^(deprecated)

showToast(options: ShowToastOptions): void

Shows a toast.

NOTE

This API is deprecated since API version 18. You are advised to use showToast on the obtained PromptAction object.

Since API version 10, you can use the getPromptAction API in UIContext to obtain the PromptAction object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct toastExample {
  build() {
    Column() {
      Button('Show toast').fontSize(20)
        .onClick(() => {
          try {
            promptAction.showToast({
              message: 'Hello World',
              duration: 2000
            });
          } catch (error) {
            let message = (error as BusinessError).message;
            let code = (error as BusinessError).code;
            console.error(`showToast args error code is ${code}, message is ${message}`);
          };
        })
    }.height('100%').width('100%').justifyContent(FlexAlign.Center)
  }
}

Below is a toast in API version 11 and earlier versions.

Below is a toast in API version 12 and later versions.

promptAction.showDialog^(deprecated)

showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse>

Shows a dialog box. This API uses a promise to return the result asynchronously.

NOTE

This API is deprecated since API version 18. You are advised to use showDialog instead on the obtained PromptAction object.

Since API version 10, you can use the getPromptAction API in UIContext to obtain the PromptAction object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

import { promptAction } from '@kit.ArkUI';

promptAction.showDialog({
  title: 'Title Info',
  message: 'Message Info',
  buttons: [
    {
      text: 'button1',
      color: '#000000'
    },
    {
      text: 'button2',
      color: '#000000'
    }
  ],
})
  .then(data => {
    console.info('showDialog success, click button: ' + data.index);
  })
  .catch((err: Error) => {
    console.info('showDialog error: ' + err);
  })

promptAction.showDialog^(deprecated)

showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse>):void

Shows a dialog box. This API uses an asynchronous callback to return the result.

NOTE

This API is deprecated since API version 18. You are advised to use showDialog instead on the obtained PromptAction object.

Since API version 10, you can use the getPromptAction API in UIContext to obtain the PromptAction object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  promptAction.showDialog({
    title: 'showDialog Title Info',
    message: 'Message Info',
    buttons: [
      {
        text: 'button1',
        color: '#000000'
      },
      {
        text: 'button2',
        color: '#000000'
      }
    ]
  }, (err, data) => {
    if (err) {
      console.info('showDialog err: ' + err);
      return;
    }
    console.info('showDialog success callback, click button: ' + data.index);
  });
} catch (error) {
  let message = (error as BusinessError).message;
  let code = (error as BusinessError).code;
  console.error(`showDialog args error code is ${code}, message is ${message}`);
};

When the showInSubWindow attribute is set to true, the toast can be displayed outside the window.

import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  promptAction.showDialog({
    title: 'showDialog Title Info',
    message: 'Message Info',
    isModal: true,
    showInSubWindow: true,
    buttons: [
      {
        text: 'button1',
        color: '#000000'
      },
      {
        text: 'button2',
        color: '#000000'
      }
    ]
  }, (err, data) => {
    if (err) {
      console.info('showDialog err: ' + err);
      return;
    }
    console.info('showDialog success callback, click button: ' + data.index);
  });
} catch (error) {
  let message = (error as BusinessError).message;
  let code = (error as BusinessError).code;
  console.error(`showDialog args error code is ${code}, message is ${message}`);
};

promptAction.showActionMenu^(deprecated)

showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void

Shows an action menu. This API uses a callback to return the result asynchronously.

NOTE

This API is deprecated since API version 18. You are advised to use showActionMenu instead on the obtained PromptAction object.

Since API version 11, you can use the getPromptAction API in UIContext to obtain the PromptAction object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  promptAction.showActionMenu({
    title: 'Title Info',
    buttons: [
      {
        text: 'item1',
        color: '#666666'
      },
      {
        text: 'item2',
        color: '#000000'
      },
    ]
  }, (err, data) => {
    if (err) {
      console.info('showActionMenu err: ' + err);
      return;
    }
    console.info('showActionMenu success callback, click button: ' + data.index);
  })
} catch (error) {
  let message = (error as BusinessError).message
  let code = (error as BusinessError).code
  console.error(`showActionMenu args error code is ${code}, message is ${message}`);
};

promptAction.showActionMenu^(deprecated)

showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse>

Shows an action menu. This API uses a promise to return the result asynchronously.

NOTE

This API is deprecated since API version 18. You are advised to use showActionMenu instead on the obtained PromptAction object.instead

Since API version 10, you can use the getPromptAction API in UIContext to obtain the PromptAction object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

import { promptAction } from '@kit.ArkUI';

promptAction.showActionMenu({
  title: 'showActionMenu Title Info',
  buttons: [
    {
      text: 'item1',
      color: '#666666'
    },
    {
      text: 'item2',
      color: '#000000'
    },
  ]
})
  .then(data => {
    console.info('showActionMenu success, click button: ' + data.index);
  })
  .catch((err: Error) => {
    console.info('showActionMenu error: ' + err);
  })

promptAction.openCustomDialog^(deprecated)

openCustomDialog(options: CustomDialogOptions): Promise<number>

Opens a custom dialog box.

This API cannot be used in ServiceExtension.

isModal = true and showInSubWindow = true cannot be used at the same time.

By default, the width of the dialog box in portrait mode is the width of the window where it is located minus the left and right margins (40 vp for 2-in-1 devices and 16 vp for other devices), and the maximum width is 400 vp.

NOTE

This API is supported since API version 11 and deprecated since API version 18. You are advised to use openCustomDialog instead on the obtained PromptAction object.

Since API version 12, you can use the getPromptAction API in UIContext to obtain the PromptAction object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private customDialogComponentId: number = 0;

  @Builder
  customDialogComponent() {
    Column() {
      Text('Dialog box').fontSize(30)
      Row({ space: 50 }) {
        Button("OK").onClick(() => {
          try {
            promptAction.closeCustomDialog(this.customDialogComponentId)
          } catch (error) {
            let message = (error as BusinessError).message;
            let code = (error as BusinessError).code;
            console.error(`closeCustomDialog error code is ${code}, message is ${message}`);
          }
        })
        Button("Cancel").onClick(() => {
          try {
            promptAction.closeCustomDialog(this.customDialogComponentId)
          } catch (error) {
            let message = (error as BusinessError).message;
            let code = (error as BusinessError).code;
            console.error(`closeCustomDialog error code is ${code}, message is ${message}`);
          }
        })
      }
    }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween)
  }

  build() {
    Row() {
      Column({ space: 20 }) {
        Text('In-component dialog box')
          .fontSize(30)
          .onClick(() => {
            promptAction.openCustomDialog({
              builder: () => {
                this.customDialogComponent()
              },
              onWillDismiss: (dismissDialogAction: DismissDialogAction) => {
                console.info("reason" + JSON.stringify(dismissDialogAction.reason));
                console.log("dialog onWillDismiss");
                if (dismissDialogAction.reason == DismissReason.PRESS_BACK) {
                  dismissDialogAction.dismiss();
                }
                if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) {
                  dismissDialogAction.dismiss();
                }
              }
            }).then((dialogId: number) => {
              this.customDialogComponentId = dialogId;
            })
              .catch((error: BusinessError) => {
                console.error(`openCustomDialog error code is ${error.code}, message is ${error.message}`);
              })
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

This example demonstrates how to set styles of a dialog box, including the width, height, background color, and shadow.

NOTE

Directly using openCustomDialog can lead to ambiguous instance issues. To avoid this, obtain a PromptAction instance using the getPromptAction API in UIContext, and then call openCustomDialog on the obtained instance.

import { LevelMode, ImmersiveMode } from '@kit.ArkUI';

let customDialogId: number = 0;

@Builder
function customDialogBuilder(uiContext: UIContext) {
  Column() {
    Text('Custom dialog Message').fontSize(10)
    Row() {
      Button("OK").onClick(() => {
        uiContext.getPromptAction().closeCustomDialog(customDialogId);
      })
      Blank().width(50)
      Button("Cancel").onClick(() => {
        uiContext.getPromptAction().closeCustomDialog(customDialogId);
      })
    }
  }
}

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';
  private uiContext: UIContext = this.getUIContext();

  @Builder
  customDialogComponent() {
    customDialogBuilder(this.uiContext)
  }

  build() {
    Row() {
      Column() {
        Text(this.message).id("test_text")
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            const node: FrameNode|null = this.uiContext.getFrameNodeById("test_text")||null;
            this.uiContext.getPromptAction().openCustomDialog({
              builder: () => {
                this.customDialogComponent()
              },
              keyboardAvoidMode: KeyboardAvoidMode.NONE,
              showInSubWindow: false,
              offset: { dx: 5, dy: 5 },
              backgroundColor: 0xd9ffffff,
              cornerRadius: 20,
              width: '80%',
              height: 200,
              borderWidth: 1,
              borderStyle: BorderStyle.Dashed, // borderStyle must be used with borderWidth in pairs.
              borderColor: Color.Blue, // borderColor must be used with borderWidth in pairs.
              shadow: ({
                radius: 20,
                color: Color.Grey,
                offsetX: 50,
                offsetY: 0
              }),
              levelMode: LevelMode.EMBEDDED,
              levelUniqueId: node?.getUniqueId(),
              immersiveMode: ImmersiveMode.DEFAULT,
            }).then((dialogId: number) => {
              customDialogId = dialogId;
            })
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

This example shows how to implement a dialog box on a page.

NOTE

Directly using openCustomDialog can lead to ambiguous instance issues. To avoid this, it is recommended that you obtain a PromptAction instance using the getPromptAction API in UIContext, and then call openCustomDialog on the obtained instance.

// Index.ets
import { LevelMode, ImmersiveMode } from '@kit.ArkUI';

let customDialogId: number = 0;

@Builder
function customDialogBuilder(uiContext: UIContext) {
  Column() {
    Text('Custom dialog Message').fontSize(10).height(100)
    Row() {
      Button("Next").onClick(() => {
        uiContext.getRouter().pushUrl({ url: 'pages/Next' });
      })
      Blank().width(50)
      Button("Close").onClick(() => {
        uiContext.getPromptAction().closeCustomDialog(customDialogId);
      })
    }
  }.padding(20)
}

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';
  private uiContext: UIContext = this.getUIContext();

  @Builder
  customDialogComponent() {
    customDialogBuilder(this.uiContext)
  }

  build() {
    Row() {
      Column() {
        Text(this.message).id("test_text")
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            const node: FrameNode|null = this.uiContext.getFrameNodeById("test_text")||null;
            this.uiContext.getPromptAction().openCustomDialog({
              builder: () => {
                this.customDialogComponent()
              },
              levelMode: LevelMode.EMBEDDED,
              levelUniqueId: node?.getUniqueId(),
              immersiveMode: ImmersiveMode.DEFAULT,
            }).then((dialogId: number) => {
              customDialogId = dialogId;
            })
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

// Next.ets
@Entry
@Component
struct Next {
  @State message: string = 'Back';

  build() {
    Row() {
      Column() {
        Button(this.message)
          .onClick(() => {
            this.getUIContext().getRouter().back();
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

promptAction.closeCustomDialog^(deprecated)

closeCustomDialog(dialogId: number): void

Closes the specified custom dialog box.

NOTE

This API is supported since API version 11 and deprecated since API version 18. You are advised to use closeCustomDialog instead on the obtained PromptAction object.

Since API version 12, you can use the getPromptAction API in UIContext to obtain the PromptAction object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Error codes

For details about the error codes, see Universal Error Codes and promptAction Error Codes.

Example

See the example of promptAction.openCustomDialog.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkUI

harmony 鸿蒙ARKUI_TextPickerCascadeRangeContent

harmony 鸿蒙ARKUI_TextPickerRangeContent

harmony 鸿蒙ArkUI_AnimateCompleteCallback

harmony 鸿蒙ArkUI_AttributeItem

harmony 鸿蒙ArkUI_ColorStop

harmony 鸿蒙ArkUI_ContextCallback

harmony 鸿蒙ArkUI_EventModule

harmony 鸿蒙ArkUI_ExpectedFrameRateRange

harmony 鸿蒙ArkUI_IntOffset