UNPKG

7.67 kBTypeScriptView Raw
1import { ActionSheet } from './action-sheet';
2import { ActionSheetOptions } from './action-sheet-options';
3import { App } from '../app/app';
4import { Config } from '../../config/config';
5/**
6 * @name ActionSheetController
7 * @description
8 * An Action Sheet is a dialog that lets the user choose from a set of
9 * options. It appears on top of the app's content, and must be manually
10 * dismissed by the user before they can resume interaction with the app.
11 * Dangerous (destructive) options are made obvious in `ios` mode. There are easy
12 * ways to cancel out of the action sheet, such as tapping the backdrop or
13 * hitting the escape key on desktop.
14 *
15 * An action sheet is created from an array of `buttons`, with each button
16 * including properties for its `text`, and optionally a `handler` and `role`.
17 * If a handler returns `false` then the action sheet will not be dismissed. An
18 * action sheet can also optionally have a `title`, `subTitle` and an `icon`.
19 *
20 * A button's `role` property can either be `destructive` or `cancel`. Buttons
21 * without a role property will have the default look for the platform. Buttons
22 * with the `cancel` role will always load as the bottom button, no matter where
23 * they are in the array. All other buttons will be displayed in the order they
24 * have been added to the `buttons` array. Note: We recommend that `destructive`
25 * buttons are always the first button in the array, making them the top button.
26 * Additionally, if the action sheet is dismissed by tapping the backdrop, then
27 * it will fire the handler from the button with the cancel role.
28 *
29 * You can pass all of the action sheet's options in the first argument of
30 * the create method: `ActionSheet.create(opts)`. Otherwise the action sheet's
31 * instance has methods to add options, like `setTitle()` or `addButton()`.
32 *
33 * @usage
34 * ```ts
35 * import { ActionSheetController } from 'ionic-angular'
36 *
37 * export class MyClass{
38 *
39 * constructor(public actionSheetCtrl: ActionSheetController) { }
40 *
41 * presentActionSheet() {
42 * const actionSheet = this.actionSheetCtrl.create({
43 * title: 'Modify your album',
44 * buttons: [
45 * {
46 * text: 'Destructive',
47 * role: 'destructive',
48 * handler: () => {
49 * console.log('Destructive clicked');
50 * }
51 * },
52 * {
53 * text: 'Archive',
54 * handler: () => {
55 * console.log('Archive clicked');
56 * }
57 * },
58 * {
59 * text: 'Cancel',
60 * role: 'cancel',
61 * handler: () => {
62 * console.log('Cancel clicked');
63 * }
64 * }
65 * ]
66 * });
67 *
68 * actionSheet.present();
69 * }
70 * }
71 * ```
72 *
73 * @advanced
74 *
75 * ActionSheet create options
76 *
77 * | Option | Type | Description |
78 * |-----------------------|------------|--------------------------------------------------------------------|
79 * | title |`string` | The title for the Action Sheet. |
80 * | subTitle |`string` | The sub-title for the Action Sheet. |
81 * | cssClass |`string` | Additional classes for custom styles, separated by spaces. |
82 * | enableBackdropDismiss |`boolean` | If the Action Sheet should close when the user taps the backdrop. |
83 * | buttons |`array<any>`| An array of buttons to display. |
84 *
85 * ActionSheet button options
86 *
87 * | Option | Type | Description |
88 * |----------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
89 * | text | `string` | The buttons text. |
90 * | icon | `icon` | The buttons icons. |
91 * | handler | `any` | An express the button should evaluate. |
92 * | cssClass | `string` | Additional classes for custom styles, separated by spaces. |
93 * | role | `string` | How the button should be displayed, `destructive` or `cancel`. If no role is provided, it will display the button without any additional styles. |
94 *
95 *
96 * ### Dismissing And Async Navigation
97 *
98 * After an action sheet has been dismissed, the app may need to also transition
99 * to another page depending on the handler's logic. However, because multiple
100 * transitions were fired at roughly the same time, it's difficult for the
101 * nav controller to cleanly animate multiple transitions that may
102 * have been kicked off asynchronously. This is further described in the
103 * [`Nav Transition Promises`](../../nav/NavController/#nav-transition-promises) section. For action sheets,
104 * this means it's best to wait for the action sheet to finish its transition
105 * out before starting a new transition on the same nav controller.
106 *
107 * In the example below, after the button has been clicked, its handler
108 * waits on async operation to complete, *then* it uses `pop` to navigate
109 * back a page in the same stack. The potential problem is that the async operation
110 * may have been completed before the action sheet has even finished its transition
111 * out. In this case, it's best to ensure the action sheet has finished its transition
112 * out first, *then* start the next transition.
113 *
114 * ```ts
115 * const actionSheet = this.actionSheetCtrl.create({
116 * title: 'Hello',
117 * buttons: [{
118 * text: 'Ok',
119 * handler: () => {
120 * // user has clicked the action sheet button
121 * // begin the action sheet's dimiss transition
122 * let navTransition = actionSheet.dismiss();
123 *
124 * // start some async method
125 * someAsyncOperation().then(() => {
126 * // once the async operation has completed
127 * // then run the next nav transition after the
128 * // first transition has finished animating out
129 *
130 * navTransition.then(() => {
131 * this.nav.pop();
132 * });
133 * });
134 * return false;
135 * }
136 * }]
137 * });
138 *
139 * actionSheet.present();
140 * ```
141 *
142 * It's important to note that the handler returns `false`. A feature of
143 * button handlers is that they automatically dismiss the action sheet when their button
144 * was clicked, however, we'll need more control regarding the transition. Because
145 * the handler returns `false`, then the action sheet does not automatically dismiss
146 * itself. Instead, you now have complete control of when the action sheet has finished
147 * transitioning, and the ability to wait for the action sheet to finish transitioning
148 * out before starting a new transition.
149 *
150 *
151 * @demo /docs/demos/src/action-sheet/
152 * @see {@link /docs/components#action-sheets ActionSheet Component Docs}
153 */
154export declare class ActionSheetController {
155 private _app;
156 config: Config;
157 constructor(_app: App, config: Config);
158 /**
159 * Open an action sheet with a title, subTitle, and an array of buttons
160 * @param {ActionSheetOptions} opts Action sheet options
161 */
162 create(opts?: ActionSheetOptions): ActionSheet;
163}