ion-refresher
Refresher provides pull-to-refresh functionality on a content component. The pull-to-refresh pattern lets a user pull down on a list of data in order to retrieve more data.
Data should be modified during the refresher's output events. Once the async operation has completed and the refreshing should end, complete() needs to be called on the refresher.
Basic Usage
Pull Properties
The refresher has several properties for customizing the pull gesture. Set the pullFactor to change the speed of the pull, the pullMin property to change the minimum distance the user must pull down, and the pullMax property to change the maximum distance the user must pull down before the refresher enters the refreshing state.
These properties do not apply when the native refresher is enabled.
Custom Refresher Content
The default icon, spinner, and text can be customized on the refresher content based on whether the state of the refresher is pulling or refreshing.
Setting pullingIcon will disable the native refresher.
Native Refreshers
Both iOS and Android platforms provide refreshers that use properties exposed by their respective devices in order to give pull-to-refresh a fluid, native-like feel.
The iOS and Material Design native refreshers are enabled by default in Ionic. However, the native iOS refresher relies on rubber band scrolling in order to work properly and is only compatible with iOS devices as a result. We provide a fallback refresher for apps running in iOS mode on devices that do not support rubber band scrolling.
The native refresher uses a circular spinner for Material Design, while iOS uses the lines spinner. On iOS, the tick marks will progressively show as the page is pulled down.
Certain refresher properties such as the Pull Properties, closeDuration and snapbackDuration are not compatible because much of the native refreshers are scroll-based. See Properties for more information on unsupported properties.
The native refreshers can be disabled by setting the pullingIcon on the refresher content to any icon or spinner. See the Ionicons and Spinner documentation for accepted values.
Usage with Virtual Scroll
Refresher requires a scroll container to function. When using a virtual scrolling solution, you will need to disable scrolling on the ion-content and indicate which element container is responsible for the scroll container with the .ion-content-scroll-host class target.
Advanced Usage
While the refresher can be used with any type of content, a common use case in native apps is to display a list of data that gets updated on refresh. In the below example, the app generates a list of data and then appends data to the top of the list when the refresh is completed. In a real app, the data would be received and updated after sending a request via a network or database call.
Interfaces
RefresherEventDetail
interface RefresherEventDetail {
complete(): void;
}
RefresherCustomEvent
While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.
interface RefresherCustomEvent extends CustomEvent {
detail: RefresherEventDetail;
target: HTMLIonRefresherElement;
}
Properties
closeDuration
| Description | リフレッシャーを閉じるのにかかる時間。リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシャーが有効になります。 |
| Attribute | close-duration |
| Type | string |
| Default | '280ms' |
disabled
| Description | trueの場合、リフレッシャーは非表示となる。 |
| Attribute | disabled |
| Type | boolean |
| Default | false |
pullFactor
| Description | 引きの速さを何倍にするか。引きのアニメーションを遅くするには、1より小さい数値を渡します。引っ張る速度を速くするには、1より大きい数値を渡します。デフォルト値は 1 で、カーソルの速度と同じです。もし負の値が渡された場合、代わりに 1 が係数となります。 例えば例えば、渡された値が 1.2 で、コンテンツが 10 ピクセルでドラッグされた場合、10 ピクセルではなく、12 ピクセルでドラッグされます（20% の増加です）。渡された値が 0.8 の場合、ドラッグされた量はカーソルの移動量より少ない 8 ピクセルとなります。 リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシャーが有効になります。 |
| Attribute | pull-factor |
| Type | number |
| Default | 1 |
pullMax
| Description | リフレッシャーが自動的に refreshing 状態になるまでの、引っ張りの最大距離。デフォルトは pullMin + 60 の結果です。リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシャーが有効になります。 |
| Attribute | pull-max |
| Type | number |
| Default | this.pullMin + 60 |
pullMin
| Description | リフレッシャーが refreshing 状態になるまでに、ユーザが引き下げるべき最小距離。リフレッシャーコンテンツがスピナーを使用する場合は適用されず、ネイティブリフレッシャーが有効になる。 |
| Attribute | pull-min |
| Type | number |
| Default | 60 |
snapbackDuration
| Description | リフレッシャーが refreshing 状態にスナップバックするのにかかる時間。リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシュが有効になります。 |
| Attribute | snapback-duration |
| Type | string |
| Default | '280ms' |
Events
| Name | Description |
|---|---|
ionPull | ユーザーがコンテンツを引き下げ、リフレッシャーを露出している間に発します。 |
ionRefresh | ユーザーがコンテンツから手を離し、pullMinを越えて下に引いたとき、またはコンテンツを下に引き、pullMaxを越えたときに発行されます。リフレッシャーの状態を refreshing に更新します。非同期処理が完了したら complete() メソッドを呼び出す必要があります。 |
ionStart | ユーザーが引き下げを開始するときに発します。 |
Methods
cancel
| Description | リフレッシュの状態を refreshing から cancelling に変更します。 |
| Signature | cancel() => Promise<void> |
complete
| Description | 非同期操作が完了したら complete() を呼び出します。例えば、refreshing状態は、アプリがAJAXリクエストからより多くのデータを受信するなど、非同期操作を実行している間です。データを受信したら、このメソッドを呼び出して、リフレッシュが完了したことを示し、リフレッシュャを閉じます。このメソッドは、リフレッシャーの状態を refreshing から completing に変更します。 |
| Signature | complete() => Promise<void> |
getProgress
| Description | ユーザーがどれだけ下に引っ張られたかを表す数値です。数値 0 は、ユーザーが全く下に引いていないことを表します。数値 1 および 1 より大きい数値は、ユーザーが手を離したときに更新が行われるほど十分に下に引っ張られたことを表します。もしユーザーが手を離し、数値が 1 より小さい場合は、更新は行われず、コンテンツは元の位置に戻ります。 |
| Signature | getProgress() => Promise<number> |
CSS Shadow Parts
No CSS shadow parts available for this component.
CSS Custom Properties
No CSS custom properties available for this component.
Slots
No slots available for this component.