• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.prompt (Prompt)
2
3The **Prompt** module provides APIs for creating and showing toasts, dialog boxes, and action menus.
4
5> **NOTE**
6>
7> The APIs of this module are deprecated since API Version 9. You are advised to use [@ohos.promptAction](js-apis-promptAction.md) instead.
8>
9> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
10
11## Modules to Import
12
13```ts
14import prompt from '@ohos.prompt'
15```
16
17## prompt.showToast
18
19showToast(options: ShowToastOptions): void
20
21Shows a toast.
22
23**System capability**: SystemCapability.ArkUI.ArkUI.Full
24
25**Parameters**
26
27| Name    | Type                                   | Mandatory  | Description     |
28| ------- | ------------------------------------- | ---- | ------- |
29| options | [ShowToastOptions](#showtoastoptions) | Yes   | Toast options.|
30
31**Example**
32
33```ts
34import prompt from '@ohos.prompt'
35prompt.showToast({
36  message: 'Message Info',
37    duration: 2000
38});
39```
40
41![en-us_image_0001](figures/en-us_image_0001.gif)
42
43## ShowToastOptions
44
45Describes the options for showing the toast.
46
47**System capability**: SystemCapability.ArkUI.ArkUI.Full
48
49| Name    | Type           | Mandatory| Description                                                        |
50| -------- | --------------- | ---- | ------------------------------------------------------------ |
51| message  | string          | Yes  | Text to display.                                            |
52| duration | number          | No  | Duration that the toast will remain on the screen. The default value is 1500 ms. The value range is 1500 ms to 10000 ms. If a value less than 1500 ms is set, the default value is used. If the value greater than 10000 ms is set, the upper limit 10000 ms is used.|
53| bottom   | string\| number | No  | Distance between the toast border and the bottom of the screen. It does not have an upper limit. The default unit is vp.      |
54
55## prompt.showDialog
56
57showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse>
58
59Shows a dialog box. This API uses a promise to return the result synchronously.
60
61**System capability**: SystemCapability.ArkUI.ArkUI.Full
62
63**Parameters**
64
65| Name    | Type                                     | Mandatory  | Description    |
66| ------- | --------------------------------------- | ---- | ------ |
67| options | [ShowDialogOptions](#showdialogoptions) | Yes   | Dialog box options.|
68
69**Return value**
70
71| Type                                      | Description      |
72| ---------------------------------------- | -------- |
73| Promise<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | Promise used to return the dialog box response result.|
74
75**Example**
76
77```ts
78import prompt from '@ohos.prompt'
79prompt.showDialog({
80  title: 'Title Info',
81  message: 'Message Info',
82  buttons: [
83    {
84      text: 'button1',
85      color: '#000000'
86    },
87    {
88      text: 'button2',
89      color: '#000000'
90    }
91  ],
92})
93  .then(data => {
94    console.info('showDialog success, click button: ' + data.index);
95  })
96  .catch((err:Error) => {
97    console.info('showDialog error: ' + err);
98  })
99```
100
101![en-us_image_0002](figures/en-us_image_0002.gif)
102
103## prompt.showDialog
104
105showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse>):void
106
107Shows a dialog box. This API uses an asynchronous callback to return the result.
108
109**System capability**: SystemCapability.ArkUI.ArkUI.Full
110
111**Parameters**
112
113| Name     | Type                                      | Mandatory  | Description          |
114| -------- | ---------------------------------------- | ---- | ------------ |
115| options  | [ShowDialogOptions](#showdialogoptions)  | Yes   | Dialog box options.|
116| callback | AsyncCallback<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | Yes   | Callback used to return the dialog box response result.  |
117
118**Example**
119
120```ts
121import prompt from '@ohos.prompt'
122prompt.showDialog({
123  title: 'showDialog Title Info',
124  message: 'Message Info',
125  buttons: [
126    {
127      text: 'button1',
128      color: '#000000'
129    },
130    {
131      text: 'button2',
132      color: '#000000'
133    }
134  ]
135}, (err, data) => {
136  if (err) {
137    console.info('showDialog err: ' + err);
138    return;
139  }
140  console.info('showDialog success callback, click button: ' + data.index);
141});
142```
143
144![en-us_image_0004](figures/en-us_image_0004.gif)
145
146## ShowDialogOptions
147
148Describes the options for showing the dialog box.
149
150**System capability**: SystemCapability.ArkUI.ArkUI.Full
151
152| Name   | Type                                                     | Mandatory| Description                                                        |
153| ------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
154| title   | string                                                    | No  | Title of the dialog box.                                                  |
155| message | string                                                    | No  | Text body.                                                  |
156| buttons | [[Button](#button),[Button](#button)?,[Button](#button)?] | No  | Array of buttons in the dialog box. The array structure is **{text:'button', color: '\#666666'}**. Up to three buttons are supported. The first button is of the **positiveButton** type, the second is of the **negativeButton** type, and the third is of the **neutralButton** type.|
157
158## ShowDialogSuccessResponse
159
160Describes the dialog box response result.
161
162**System capability**: SystemCapability.ArkUI.ArkUI.Full
163
164| Name | Type  | Mandatory| Description                           |
165| ----- | ------ | ---- | ------------------------------- |
166| index | number | No  | Index of the selected button in the **buttons** array.|
167
168
169## prompt.showActionMenu
170
171showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void
172
173Shows an action menu. This API uses a callback to return the result asynchronously.
174
175**System capability**: SystemCapability.ArkUI.ArkUI.Full
176
177**Parameters**
178
179| Name     | Type                                      | Mandatory  | Description       |
180| -------- | ---------------------------------------- | ---- | --------- |
181| options  | [ActionMenuOptions](#actionmenuoptions)  | Yes   | Action menu options.  |
182| callback | AsyncCallback<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | Yes   | Callback used to return the action menu response result.|
183
184**Example**
185
186```ts
187import prompt from '@ohos.prompt'
188prompt.showActionMenu({
189  title: 'Title Info',
190  buttons: [
191    {
192      text: 'item1',
193      color: '#666666'
194    },
195    {
196      text: 'item2',
197      color: '#000000'
198    },
199  ]
200}, (err, data) => {
201  if (err) {
202    console.info('showActionMenu err: ' + err);
203    return;
204  }
205  console.info('showActionMenu success callback, click button: ' + data.index);
206})
207```
208
209![en-us_image_0005](figures/en-us_image_0005.gif)
210
211## prompt.showActionMenu
212
213showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse>
214
215Shows an action menu. This API uses a promise to return the result synchronously.
216
217**System capability**: SystemCapability.ArkUI.ArkUI.Full
218
219**Parameters**
220
221| Name    | Type                                     | Mandatory  | Description     |
222| ------- | --------------------------------------- | ---- | ------- |
223| options | [ActionMenuOptions](#actionmenuoptions) | Yes   | Action menu options.|
224
225**Return value**
226
227| Type                                      | Description     |
228| ---------------------------------------- | ------- |
229| Promise<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | Promise used to return the action menu response result.|
230
231**Example**
232
233```ts
234import prompt from '@ohos.prompt'
235prompt.showActionMenu({
236  title: 'showActionMenu Title Info',
237  buttons: [
238    {
239      text: 'item1',
240      color: '#666666'
241    },
242    {
243      text: 'item2',
244      color: '#000000'
245    },
246  ]
247})
248  .then(data => {
249    console.info('showActionMenu success, click button: ' + data.index);
250  })
251  .catch((err:Error) => {
252    console.info('showActionMenu error: ' + err);
253  })
254```
255![en-us_image_0006](figures/en-us_image_0006.gif)
256
257## ActionMenuOptions
258
259Describes the options for showing the action menu.
260
261**System capability**: SystemCapability.ArkUI.ArkUI.Full
262
263| Name   | Type                                                        | Mandatory| Description                                                        |
264| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
265| title   | string                                                       | No  | Title of the text to display.                                                  |
266| buttons | [[Button](#button),[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?] | Yes  | Array of menu item buttons. The array structure is **{text:'button', color: '\#666666'}**. Up to six buttons are supported. If there are more than six buttons, extra buttons will not be displayed.|
267
268## ActionMenuSuccessResponse
269
270Describes the action menu response result.
271
272**System capability**: SystemCapability.ArkUI.ArkUI.Full
273
274| Name   | Type    | Mandatory  | Description                      |
275| ----- | ------ | ---- | ------------------------ |
276| index | number | No   | Index of the selected button in the **buttons** array, starting from **0**.|
277
278## Button
279
280Describes the menu item button in the action menu.
281
282**System capability**: SystemCapability.ArkUI.ArkUI.Full
283
284| Name | Type  | Mandatory| Description          |
285| ----- | ------ | ---- | -------------- |
286| text  | string | Yes  | Button text.|
287| color | string | Yes  | Text color of the button.|
288