• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.promptAction (Prompt)
2
3The **PromptAction** module provides APIs for creating and showing toasts, dialog boxes, and action menus.
4
5> **NOTE**
6>
7> 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.
8
9## Modules to Import
10
11```js
12import promptAction from '@ohos.promptAction'
13```
14
15## promptAction.showToast
16
17showToast(options: ShowToastOptions): void
18
19Shows a toast.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name    | Type                                   | Mandatory  | Description     |
26| ------- | ------------------------------------- | ---- | ------- |
27| options | [ShowToastOptions](#showtoastoptions) | Yes   | Toast options.|
28
29**Error codes**
30
31For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
32
33| ID  | Error Message|
34| --------- | ------- |
35| 100001    | if UI execution context not found. |
36
37**Example**
38
39```js
40try {
41  promptAction.showToast({
42    message: 'Message Info',
43    duration: 2000,
44  });
45} catch (error) {
46  console.error(`showToast args error code is ${error.code}, message is ${error.message}`);
47};
48
49```
50
51![en-us_image_0001](figures/en-us_image_0001.gif)
52
53## ShowToastOptions
54
55Describes the options for showing the toast.
56
57**System capability**: SystemCapability.ArkUI.ArkUI.Full
58
59| Name      | Type                                      | Mandatory  | Description                                      |
60| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
61| message  | string\| [Resource](../arkui-ts/ts-types.md#resource)<sup>9+</sup>| Yes   | Text to display.                                |
62| 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.|
63| bottom   | string\| number                          | No   | Distance between the toast border and the bottom of the screen.                        |
64
65## promptAction.showDialog
66
67showDialog(options: ShowDialogOptions): Promise&lt;ShowDialogSuccessResponse&gt;
68
69Shows a dialog box. This API uses a promise to return the result synchronously.
70
71**System capability**: SystemCapability.ArkUI.ArkUI.Full
72
73**Parameters**
74
75| Name    | Type                                     | Mandatory  | Description    |
76| ------- | --------------------------------------- | ---- | ------ |
77| options | [ShowDialogOptions](#showdialogoptions) | Yes   | Dialog box options.|
78
79**Return value**
80
81| Type                                      | Description      |
82| ---------------------------------------- | -------- |
83| Promise&lt;[ShowDialogSuccessResponse](#showdialogsuccessresponse)&gt; | Promise used to return the dialog box response result.|
84
85**Error codes**
86
87For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
88
89| ID  | Error Message|
90| --------- | ------- |
91| 100001    | if UI execution context not found. |
92
93**Example**
94
95```js
96try {
97  promptAction.showDialog({
98    title: 'Title Info',
99    message: 'Message Info',
100    buttons: [
101      {
102        text: 'button1',
103        color: '#000000',
104      },
105      {
106        text: 'button2',
107        color: '#000000',
108      }
109    ],
110  })
111    .then(data => {
112      console.info('showDialog success, click button: ' + data.index);
113    })
114    .catch(err => {
115      console.info('showDialog error: ' + err);
116    })
117} catch (error) {
118  console.error(`showDialog args error code is ${error.code}, message is ${error.message}`);
119};
120```
121
122![en-us_image_0002](figures/en-us_image_0002.gif)
123
124## promptAction.showDialog
125
126showDialog(options: ShowDialogOptions, callback: AsyncCallback&lt;ShowDialogSuccessResponse&gt;):void
127
128Shows a dialog box. This API uses an asynchronous callback to return the result.
129
130**System capability**: SystemCapability.ArkUI.ArkUI.Full
131
132**Parameters**
133
134| Name     | Type                                      | Mandatory  | Description          |
135| -------- | ---------------------------------------- | ---- | ------------ |
136| options  | [ShowDialogOptions](#showdialogoptions)  | Yes   | Dialog box options.|
137| callback | AsyncCallback&lt;[ShowDialogSuccessResponse](#showdialogsuccessresponse)&gt; | Yes   | Callback used to return the dialog box response result.  |
138
139**Error codes**
140
141For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
142
143| ID  | Error Message|
144| --------- | ------- |
145| 100001    | if UI execution context not found. |
146
147**Example**
148
149```js
150try {
151  promptAction.showDialog({
152    title: 'showDialog Title Info',
153    message: 'Message Info',
154    buttons: [
155      {
156        text: 'button1',
157        color: '#000000',
158      },
159      {
160        text: 'button2',
161        color: '#000000',
162      }
163    ]
164  }, (err, data) => {
165    if (err) {
166      console.info('showDialog err: ' + err);
167      return;
168    }
169    console.info('showDialog success callback, click button: ' + data.index);
170  });
171} catch (error) {
172  console.error(`showDialog args error code is ${error.code}, message is ${error.message}`);
173};
174```
175
176![en-us_image_0002](figures/en-us_image_0002.gif)
177
178## ShowDialogOptions
179
180Describes the options for showing the dialog box.
181
182**System capability**: SystemCapability.ArkUI.ArkUI.Full
183
184| Name   | Type                                                        | Mandatory| Description                                                        |
185| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
186| title   | string\| [Resource](../arkui-ts/ts-types.md#resource)<sup>9+</sup>| No  | Title of the dialog box.                                                  |
187| message | string\| [Resource](../arkui-ts/ts-types.md#resource)<sup>9+</sup>| No  | Text body.                                                  |
188| 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.|
189
190## ShowDialogSuccessResponse
191
192Describes the dialog box response result.
193
194**System capability**: SystemCapability.ArkUI.ArkUI.Full
195
196| Name | Type  | Mandatory| Description                           |
197| ----- | ------ | ---- | ------------------------------- |
198| index | number | No  | Index of the selected button in the **buttons** array.|
199
200## promptAction.showActionMenu
201
202showActionMenu(options: ActionMenuOptions, callback: AsyncCallback&lt;ActionMenuSuccessResponse&gt;):void
203
204Shows an action menu. This API uses a callback to return the result asynchronously.
205
206**System capability**: SystemCapability.ArkUI.ArkUI.Full
207
208**Parameters**
209
210| Name     | Type                                      | Mandatory  | Description       |
211| -------- | ---------------------------------------- | ---- | --------- |
212| options  | [ActionMenuOptions](#actionmenuoptions)  | Yes   | Action menu options.  |
213| callback | AsyncCallback&lt;[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | Yes   | Callback used to return the action menu response result.|
214
215**Error codes**
216
217For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
218
219| ID  | Error Message|
220| --------- | ------- |
221| 100001    | if UI execution context not found. |
222
223**Example**
224
225```js
226try {
227  promptAction.showActionMenu({
228    title: 'Title Info',
229    buttons: [
230      {
231        text: 'item1',
232        color: '#666666',
233      },
234      {
235        text: 'item2',
236        color: '#000000',
237      },
238    ]
239  }, (err, data) => {
240    if (err) {
241      console.info('showActionMenu err: ' + err);
242      return;
243    }
244    console.info('showActionMenu success callback, click button: ' + data.index);
245  })
246} catch (error) {
247  console.error(`showActionMenu args error code is ${error.code}, message is ${error.message}`);
248};
249```
250
251![en-us_image_0005](figures/en-us_image_0005.gif)
252
253## promptAction.showActionMenu
254
255showActionMenu(options: ActionMenuOptions): Promise&lt;ActionMenuSuccessResponse&gt;
256
257Shows an action menu. This API uses a promise to return the result synchronously.
258
259**System capability**: SystemCapability.ArkUI.ArkUI.Full
260
261**Parameters**
262
263| Name    | Type                                     | Mandatory  | Description     |
264| ------- | --------------------------------------- | ---- | ------- |
265| options | [ActionMenuOptions](#actionmenuoptions) | Yes   | Action menu options.|
266
267**Return value**
268
269| Type                                      | Description     |
270| ---------------------------------------- | ------- |
271| Promise&lt;[ActionMenuSuccessResponse](#actionmenusuccessresponse)&gt; | Promise used to return the action menu response result.|
272
273**Error codes**
274
275For details about the error codes, see [promptAction Error Codes](../errorcodes/errorcode-promptAction.md).
276
277| ID  | Error Message|
278| --------- | ------- |
279| 100001    | if UI execution context not found. |
280
281**Example**
282
283```js
284try {
285  promptAction.showActionMenu({
286    title: 'showActionMenu Title Info',
287    buttons: [
288      {
289        text: 'item1',
290        color: '#666666',
291      },
292      {
293        text: 'item2',
294        color: '#000000',
295      },
296    ]
297  })
298    .then(data => {
299      console.info('showActionMenu success, click button: ' + data.index);
300    })
301    .catch(err => {
302      console.info('showActionMenu error: ' + err);
303    })
304} catch (error) {
305  console.error(`showActionMenu args error code is ${error.code}, message is ${error.message}`);
306};
307```
308
309![en-us_image_0005](figures/en-us_image_0005.gif)
310
311## ActionMenuOptions
312
313Describes the options for showing the action menu.
314
315**System capability**: SystemCapability.ArkUI.ArkUI.Full
316
317| Name   | Type                                                        | Mandatory| Description                                                        |
318| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
319| title   | string\| [Resource](../arkui-ts/ts-types.md#resource)<sup>9+</sup>| No  | Title of the dialog box.                                                  |
320| 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.|
321
322## ActionMenuSuccessResponse
323
324Describes the action menu response result.
325
326**System capability**: SystemCapability.ArkUI.ArkUI.Full
327
328| Name   | Type    | Mandatory  | Description                      |
329| ----- | ------ | ---- | ------------------------ |
330| index | number | No   | Index of the selected button in the **buttons** array, starting from **0**.|
331
332## Button
333
334Describes the menu item button in the action menu.
335
336**System capability**: SystemCapability.ArkUI.ArkUI.Full
337
338| Name   | Type                                      | Mandatory  | Description     |
339| ----- | ---------------------------------------- | ---- | ------- |
340| text  | string\| [Resource](../arkui-ts/ts-types.md#resource)<sup>9+</sup>| Yes   | Button text.|
341| color | string\| [Resource](../arkui-ts/ts-types.md#resource)<sup>9+</sup>| Yes   | Text color of the button.|
342