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