mirror of
https://github.com/ionic-team/ionic-framework.git
synced 2026-03-13 10:22:08 +08:00
docs(loading): add usage, fix docs, update for style guide
This commit is contained in:
Brandy Carney
@@ -1,36 +1,21 @@
|
||||
# ion-loading-controller
|
||||
|
||||
An overlay that can be used to indicate activity while blocking user
|
||||
interaction. The loading indicator appears on top of the app's content,
|
||||
and can be dismissed by the app to resume user interaction with
|
||||
the app. It includes an optional backdrop, which can be disabled
|
||||
by setting `showBackdrop: false` upon creation.
|
||||
Loading controllers programmatically control the loading component. Loadings can be created and dismissed from the loading controller. View the [Loading](../../loading/Loading) documentation for a full list of options to pass upon creation.
|
||||
|
||||
### Creating
|
||||
You can pass all of the loading options in the first argument of
|
||||
the create method: `create(opts)`. The spinner name should be
|
||||
passed in the `spinner` property, and any optional HTML can be passed
|
||||
in the `content` property. If you do not pass a value to `spinner`
|
||||
the loading indicator will use the spinner specified by the mode. To
|
||||
set the spinner name across the app, set the value of `loadingSpinner`
|
||||
in your app's config. To hide the spinner, set `loadingSpinner: 'hide'`
|
||||
in the app's config or pass `spinner: 'hide'` in the loading
|
||||
options. See the [create](#create) method below for all available options.
|
||||
|
||||
### Dismissing
|
||||
The loading indicator can be dismissed automatically after a specific
|
||||
amount of time by passing the number of milliseconds to display it in
|
||||
the `duration` of the loading options. By default the loading indicator
|
||||
will show even during page changes, but this can be disabled by setting
|
||||
`dismissOnPageChange` to `true`. To dismiss the loading indicator after
|
||||
creation, call the `dismiss()` method on the Loading instance. The
|
||||
`onDidDismiss` function can be called to perform an action after the loading
|
||||
indicator is dismissed.
|
||||
```javascript
|
||||
async function presentLoading() {
|
||||
const loadingController = document.querySelector('ion-loading-controller');
|
||||
await loadingController.componentOnReady();
|
||||
|
||||
>Note that after the component is dismissed, it will not be usable anymore
|
||||
and another one must be created. This can be avoided by wrapping the
|
||||
creation and presentation of the component in a reusable function as shown
|
||||
in the `usage` section below.
|
||||
const loadingElement = await loadingController.create({
|
||||
content: 'Please wait...',
|
||||
spinner: 'crescent',
|
||||
duration: 2000
|
||||
});
|
||||
return await loadingElement.present();
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
<!-- Auto Generated Below -->
|
||||
|
||||
@@ -1,17 +1,8 @@
|
||||
import { Component, Element, Event, EventEmitter, Listen, Method, Prop } from '@stencil/core';
|
||||
import {
|
||||
Animation,
|
||||
AnimationBuilder,
|
||||
AnimationController,
|
||||
Config,
|
||||
DomController,
|
||||
OverlayDismissEvent,
|
||||
OverlayDismissEventDetail
|
||||
} from '../../index';
|
||||
import { Animation, AnimationBuilder, AnimationController, Config, DomController, OverlayDismissEvent, OverlayDismissEventDetail } from '../../index';
|
||||
import { domControllerAsync, playAnimationAsync } from '../../utils/helpers';
|
||||
import { createThemedClasses, getClassMap } from '../../utils/theme';
|
||||
|
||||
|
||||
import iosEnterAnimation from './animations/ios.enter';
|
||||
import iosLeaveAnimation from './animations/ios.leave';
|
||||
import mdEnterAnimation from './animations/md.enter';
|
||||
@@ -37,6 +28,67 @@ export class Loading {
|
||||
|
||||
@Element() private el: HTMLElement;
|
||||
|
||||
@Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController;
|
||||
@Prop({ context: 'config' }) config: Config;
|
||||
@Prop({ context: 'dom' }) dom: DomController;
|
||||
|
||||
/**
|
||||
* Animation to use when the loading indicator is presented.
|
||||
*/
|
||||
@Prop() enterAnimation: AnimationBuilder;
|
||||
|
||||
/**
|
||||
* Animation to use when the loading indicator is dismissed.
|
||||
*/
|
||||
@Prop() leaveAnimation: AnimationBuilder;
|
||||
|
||||
/**
|
||||
* Optional text content to display in the loading indicator.
|
||||
*/
|
||||
@Prop() content: string;
|
||||
|
||||
/**
|
||||
* Additional classes to apply for custom CSS. If multiple classes are
|
||||
* provided they should be separated by spaces.
|
||||
*/
|
||||
@Prop() cssClass: string;
|
||||
|
||||
/**
|
||||
* If true, the loading indicator will dismiss when the page changes. Defaults to `false`.
|
||||
*/
|
||||
@Prop() dismissOnPageChange = false;
|
||||
|
||||
/**
|
||||
* Number of milliseconds to wait before dismissing the loading indicator.
|
||||
*/
|
||||
@Prop() duration: number;
|
||||
|
||||
/**
|
||||
* If true, the loading indicator will be dismissed when the backdrop is clicked. Defaults to `false`.
|
||||
*/
|
||||
@Prop() enableBackdropDismiss = false;
|
||||
|
||||
/**
|
||||
* If true, a backdrop will be displayed behind the loading indicator. Defaults to `true`.
|
||||
*/
|
||||
@Prop() showBackdrop = true;
|
||||
|
||||
/**
|
||||
* The name of the spinner to display. Possible values are: `"lines"`, `"lines-sm"`, `"dots"`,
|
||||
* `"bubbles"`, `"circles"`, `"crescent"`.
|
||||
*/
|
||||
@Prop() spinner: string;
|
||||
|
||||
/**
|
||||
* If true, the loading indicator will be translucent. Defaults to `false`.
|
||||
*/
|
||||
@Prop() translucent = false;
|
||||
|
||||
/**
|
||||
* If true, the loading indicator will animate. Defaults to `true`.
|
||||
*/
|
||||
@Prop() willAnimate = true;
|
||||
|
||||
/**
|
||||
* Emitted after the loading has loaded.
|
||||
*/
|
||||
@@ -67,59 +119,40 @@ export class Loading {
|
||||
*/
|
||||
@Event() ionLoadingDidUnload: EventEmitter<LoadingEventDetail>;
|
||||
|
||||
@Prop() spinner: string;
|
||||
componentDidLoad() {
|
||||
if (!this.spinner) {
|
||||
this.spinner = this.config.get('loadingSpinner', this.mode === 'ios' ? 'lines' : 'crescent');
|
||||
}
|
||||
this.ionLoadingDidLoad.emit();
|
||||
}
|
||||
|
||||
@Prop({ connect: 'ion-animation-controller' }) animationCtrl: AnimationController;
|
||||
@Prop({ context: 'config' }) config: Config;
|
||||
@Prop({ context: 'dom' }) dom: DomController;
|
||||
componentDidEnter() {
|
||||
// blur the currently active element
|
||||
const activeElement: any = document.activeElement;
|
||||
activeElement && activeElement.blur && activeElement.blur();
|
||||
|
||||
// If there is a duration, dismiss after that amount of time
|
||||
if (typeof this.duration === 'number' && this.duration > 10) {
|
||||
this.durationTimeout = setTimeout(() => this.dismiss(), this.duration);
|
||||
}
|
||||
|
||||
this.ionLoadingDidPresent.emit();
|
||||
}
|
||||
|
||||
componentDidUnload() {
|
||||
this.ionLoadingDidUnload.emit();
|
||||
}
|
||||
|
||||
@Listen('ionDismiss')
|
||||
protected onDismiss(ev: UIEvent) {
|
||||
ev.stopPropagation();
|
||||
ev.preventDefault();
|
||||
|
||||
this.dismiss();
|
||||
}
|
||||
|
||||
/**
|
||||
* Additional classes to apply for custom CSS
|
||||
*/
|
||||
@Prop() cssClass: string;
|
||||
|
||||
/**
|
||||
* Optional text content to display in the loading indicator
|
||||
*/
|
||||
@Prop() content: string;
|
||||
|
||||
/**
|
||||
* Dismiss the loading indicator if the page is changed
|
||||
*/
|
||||
@Prop() dismissOnPageChange = false;
|
||||
|
||||
/**
|
||||
* Number of milliseconds to wait before dismissing the loading indicator
|
||||
*/
|
||||
@Prop() duration: number;
|
||||
|
||||
/**
|
||||
* If true, the background will be translucent. Browser support for backdrop-filter is required for the full effect
|
||||
*/
|
||||
@Prop() translucent = false;
|
||||
|
||||
/**
|
||||
* Show the backdrop of not
|
||||
*/
|
||||
@Prop() showBackdrop = true;
|
||||
|
||||
/**
|
||||
* Animation to use when loading indicator is presented
|
||||
*/
|
||||
@Prop() enterAnimation: AnimationBuilder;
|
||||
|
||||
/**
|
||||
* Animation to use when a loading indicator is dismissed
|
||||
*/
|
||||
@Prop() leaveAnimation: AnimationBuilder;
|
||||
|
||||
/**
|
||||
* Toggles whether animation should occur or not
|
||||
*/
|
||||
@Prop() willAnimate = true;
|
||||
|
||||
/**
|
||||
* Present a loading overlay after it has been created
|
||||
* Present the loading overlay after it has been created.
|
||||
*/
|
||||
@Method()
|
||||
present() {
|
||||
@@ -151,7 +184,7 @@ export class Loading {
|
||||
}
|
||||
|
||||
/**
|
||||
* Dismiss a loading indicator programatically
|
||||
* Dismiss the loading overlay after it has been presented.
|
||||
*/
|
||||
@Method()
|
||||
dismiss(data?: any, role?: string) {
|
||||
@@ -190,36 +223,10 @@ export class Loading {
|
||||
});
|
||||
}
|
||||
|
||||
componentDidLoad() {
|
||||
if (!this.spinner) {
|
||||
this.spinner = this.config.get('loadingSPinner', this.mode === 'ios' ? 'lines' : 'crescent');
|
||||
protected backdropClick() {
|
||||
if (this.enableBackdropDismiss) {
|
||||
this.dismiss();
|
||||
}
|
||||
this.ionLoadingDidLoad.emit();
|
||||
}
|
||||
|
||||
componentDidEnter() {
|
||||
// blur the currently active element
|
||||
const activeElement: any = document.activeElement;
|
||||
activeElement && activeElement.blur && activeElement.blur();
|
||||
|
||||
// If there is a duration, dismiss after that amount of time
|
||||
if (typeof this.duration === 'number' && this.duration > 10) {
|
||||
this.durationTimeout = setTimeout(() => this.dismiss(), this.duration);
|
||||
}
|
||||
|
||||
this.ionLoadingDidPresent.emit();
|
||||
}
|
||||
|
||||
componentDidUnload() {
|
||||
this.ionLoadingDidUnload.emit();
|
||||
}
|
||||
|
||||
@Listen('ionDismiss')
|
||||
protected onDismiss(ev: UIEvent) {
|
||||
ev.stopPropagation();
|
||||
ev.preventDefault();
|
||||
|
||||
this.dismiss();
|
||||
}
|
||||
|
||||
hostData() {
|
||||
@@ -261,14 +268,12 @@ export class Loading {
|
||||
}
|
||||
|
||||
return [
|
||||
<ion-gesture
|
||||
attachTo='parent'
|
||||
autoBlockAll
|
||||
<ion-backdrop
|
||||
onClick={this.backdropClick.bind(this)}
|
||||
class={{
|
||||
...themedClasses,
|
||||
'hide-backdrop': !this.showBackdrop
|
||||
}}
|
||||
></ion-gesture>,
|
||||
}}></ion-backdrop>,
|
||||
<div class='loading-wrapper' role='dialog'>
|
||||
{loadingInner}
|
||||
</div>
|
||||
|
||||
@@ -1,5 +1,33 @@
|
||||
# ion-loading
|
||||
|
||||
An overlay that can be used to indicate activity while blocking user interaction. The loading indicator appears on top of the app's content, and can be dismissed by the app to resume user interaction with the app. It includes an optional backdrop, which can be disabled by setting `showBackdrop: false` upon creation.
|
||||
|
||||
Loading indicators can be programmatically opened using a [Loading Controller](../../loading-controller/LoadingController). They can be customized by passing loading options in the first argument of the loading controller's create method.
|
||||
|
||||
|
||||
### Creating
|
||||
|
||||
You can pass all of the loading options in the first argument of the create method. The spinner name should be passed in the `spinner` property, and any optional HTML can be passed in the `content` property. If a value is not passed to `spinner` the loading indicator will use the spinner specified by the platform.
|
||||
|
||||
|
||||
### Dismissing
|
||||
|
||||
The loading indicator can be dismissed automatically after a specific amount of time by passing the number of milliseconds to display it in the `duration` of the loading options. By default the loading indicator will show even during page changes, but this can be disabled by setting `dismissOnPageChange` to `true`. To dismiss the loading indicator after creation, call the `dismiss()` method on the loading instance. The `onDidDismiss` function can be called to perform an action after the loading indicator is dismissed.
|
||||
|
||||
|
||||
```javascript
|
||||
async function presentLoading() {
|
||||
const loadingController = document.querySelector('ion-loading-controller');
|
||||
await loadingController.componentOnReady();
|
||||
|
||||
const loadingElement = await loadingController.create({
|
||||
content: 'Please wait...',
|
||||
spinner: 'crescent',
|
||||
duration: 2000
|
||||
});
|
||||
return await loadingElement.present();
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
<!-- Auto Generated Below -->
|
||||
@@ -11,68 +39,79 @@
|
||||
|
||||
string
|
||||
|
||||
Optional text content to display in the loading indicator
|
||||
Optional text content to display in the loading indicator.
|
||||
|
||||
|
||||
#### cssClass
|
||||
|
||||
string
|
||||
|
||||
Additional classes to apply for custom CSS
|
||||
Additional classes to apply for custom CSS. If multiple classes are
|
||||
provided they should be separated by spaces.
|
||||
|
||||
|
||||
#### dismissOnPageChange
|
||||
|
||||
boolean
|
||||
|
||||
Dismiss the loading indicator if the page is changed
|
||||
If true, the loading indicator will dismiss when the page changes. Defaults to `false`.
|
||||
|
||||
|
||||
#### duration
|
||||
|
||||
number
|
||||
|
||||
Number of milliseconds to wait before dismissing the loading indicator
|
||||
Number of milliseconds to wait before dismissing the loading indicator.
|
||||
|
||||
|
||||
#### enableBackdropDismiss
|
||||
|
||||
boolean
|
||||
|
||||
If true, the loading indicator will be dismissed when the backdrop is clicked. Defaults to `false`.
|
||||
|
||||
|
||||
#### enterAnimation
|
||||
|
||||
|
||||
|
||||
Animation to use when loading indicator is presented
|
||||
Animation to use when the loading indicator is presented.
|
||||
|
||||
|
||||
#### leaveAnimation
|
||||
|
||||
|
||||
|
||||
Animation to use when a loading indicator is dismissed
|
||||
Animation to use when the loading indicator is dismissed.
|
||||
|
||||
|
||||
#### showBackdrop
|
||||
|
||||
boolean
|
||||
|
||||
Show the backdrop of not
|
||||
If true, a backdrop will be displayed behind the loading indicator. Defaults to `true`.
|
||||
|
||||
|
||||
#### spinner
|
||||
|
||||
string
|
||||
|
||||
The name of the spinner to display. Possible values are: `"lines"`, `"lines-sm"`, `"dots"`,
|
||||
`"bubbles"`, `"circles"`, `"crescent"`.
|
||||
|
||||
|
||||
#### translucent
|
||||
|
||||
boolean
|
||||
|
||||
If true, the background will be translucent. Browser support for backdrop-filter is required for the full effect
|
||||
If true, the loading indicator will be translucent. Defaults to `false`.
|
||||
|
||||
|
||||
#### willAnimate
|
||||
|
||||
boolean
|
||||
|
||||
Toggles whether animation should occur or not
|
||||
If true, the loading indicator will animate. Defaults to `true`.
|
||||
|
||||
|
||||
## Attributes
|
||||
@@ -81,68 +120,79 @@ Toggles whether animation should occur or not
|
||||
|
||||
string
|
||||
|
||||
Optional text content to display in the loading indicator
|
||||
Optional text content to display in the loading indicator.
|
||||
|
||||
|
||||
#### css-class
|
||||
|
||||
string
|
||||
|
||||
Additional classes to apply for custom CSS
|
||||
Additional classes to apply for custom CSS. If multiple classes are
|
||||
provided they should be separated by spaces.
|
||||
|
||||
|
||||
#### dismiss-on-page-change
|
||||
|
||||
boolean
|
||||
|
||||
Dismiss the loading indicator if the page is changed
|
||||
If true, the loading indicator will dismiss when the page changes. Defaults to `false`.
|
||||
|
||||
|
||||
#### duration
|
||||
|
||||
number
|
||||
|
||||
Number of milliseconds to wait before dismissing the loading indicator
|
||||
Number of milliseconds to wait before dismissing the loading indicator.
|
||||
|
||||
|
||||
#### enable-backdrop-dismiss
|
||||
|
||||
boolean
|
||||
|
||||
If true, the loading indicator will be dismissed when the backdrop is clicked. Defaults to `false`.
|
||||
|
||||
|
||||
#### enter-animation
|
||||
|
||||
|
||||
|
||||
Animation to use when loading indicator is presented
|
||||
Animation to use when the loading indicator is presented.
|
||||
|
||||
|
||||
#### leave-animation
|
||||
|
||||
|
||||
|
||||
Animation to use when a loading indicator is dismissed
|
||||
Animation to use when the loading indicator is dismissed.
|
||||
|
||||
|
||||
#### show-backdrop
|
||||
|
||||
boolean
|
||||
|
||||
Show the backdrop of not
|
||||
If true, a backdrop will be displayed behind the loading indicator. Defaults to `true`.
|
||||
|
||||
|
||||
#### spinner
|
||||
|
||||
string
|
||||
|
||||
The name of the spinner to display. Possible values are: `"lines"`, `"lines-sm"`, `"dots"`,
|
||||
`"bubbles"`, `"circles"`, `"crescent"`.
|
||||
|
||||
|
||||
#### translucent
|
||||
|
||||
boolean
|
||||
|
||||
If true, the background will be translucent. Browser support for backdrop-filter is required for the full effect
|
||||
If true, the loading indicator will be translucent. Defaults to `false`.
|
||||
|
||||
|
||||
#### will-animate
|
||||
|
||||
boolean
|
||||
|
||||
Toggles whether animation should occur or not
|
||||
If true, the loading indicator will animate. Defaults to `true`.
|
||||
|
||||
|
||||
## Events
|
||||
@@ -181,12 +231,12 @@ Emitted before the loading has presented.
|
||||
|
||||
#### dismiss()
|
||||
|
||||
Dismiss a loading indicator programatically
|
||||
Dismiss the loading overlay after it has been presented.
|
||||
|
||||
|
||||
#### present()
|
||||
|
||||
Present a loading overlay after it has been created
|
||||
Present the loading overlay after it has been created.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -27,5 +27,10 @@ platforms.forEach(platform => {
|
||||
const page = new E2ETestPage(driver, platform);
|
||||
return page.present('basic');
|
||||
});
|
||||
|
||||
register('should open default spinner', driver => {
|
||||
const page = new E2ETestPage(driver, platform);
|
||||
return page.present('default');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -19,10 +19,12 @@
|
||||
|
||||
<ion-content padding>
|
||||
<ion-button id="basic" expand="block" onclick="presentLoading()">Show Loading</ion-button>
|
||||
<ion-button id="default" expand="block" onclick="presentLoadingWithOptions({duration: 2000, content: 'Please wait...'})">Show Default Loading</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({duration: 2000, content: 'Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ea voluptatibus quibusdam eum nihil optio, ullam accusamus magni, nobis suscipit reprehenderit, sequi quam amet impedit. Accusamus dolorem voluptates laborum dolor obcaecati.'})">Show Loading with long content</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({duration: 2000, content: 'Loading Please Wait...', spinner: 'hide'})">Show Loading with no spinner</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({duration: 5000, content: 'Loading Please Wait...', translucent: true})">Show Loading with translucent</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({duration: 5000, content: 'Loading Please Wait...', translucent: true, cssClass: 'custom-class custom-loading'})">Show Loading with cssClass</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({duration: 2000, content: 'Please wait...', spinner: 'hide'})">Show Loading with no spinner</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({duration: 5000, content: 'Please wait...', translucent: true})">Show Loading with translucent</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({duration: 5000, content: 'Please wait...', translucent: true, cssClass: 'custom-class custom-loading'})">Show Loading with cssClass</ion-button>
|
||||
<ion-button expand="block" onclick="presentLoadingWithOptions({enableBackdropDismiss: true})">Show Backdrop Click Loading</ion-button>
|
||||
|
||||
<ion-loading-controller></ion-loading-controller>
|
||||
|
||||
@@ -77,9 +79,10 @@
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.custom-loading .loading-wrapper{
|
||||
background: green;
|
||||
.custom-loading .loading-wrapper {
|
||||
background: rgb(155, 221, 226);
|
||||
}
|
||||
|
||||
f {
|
||||
display: block;
|
||||
background: blue;
|
||||
|
||||
Reference in New Issue
Block a user