ion-refresher

リフレッシャーは、コンテンツコンポーネントにプルトゥリフレッシュ機能を提供します。pull-to-refreshパターンは、ユーザがより多くのデータを取得するために、データのリストをプルダウンすることを可能にします。

データは、リフレッシャーの出力イベント中に変更する必要があります。非同期処理が完了し、リフレッシュが終了したら、リフレッシュに対して complete() を呼び出す必要があります。

基本的な使い方

Pull プロパティ

リフレッシャーには、引くジェスチャーをカスタマイズするためのプロパティがいくつかあります。 pullFactor プロパティを設定すると引っ張るスピードを、pullMin プロパティを設定するとユーザが引っ張る最小距離を、pullMax プロパティを設定するとリフレッシャーが refreshing 状態になる前にユーザが引っ張る最大距離を変更することができます。

これらのプロパティは、native refresherが有効な場合には適用されません。

カスタムリフレッシャーコンテンツ

デフォルトのアイコン、スピナー、テキストは、リフレッシャーの状態が pulling か refreshing かによって、リフレッシャーコンテンツ 上でカスタマイズすることができます。

pullingIconを設定すると、native refresherが無効になります。

Native Refreshers

iOSとAndroidの両プラットフォームは、pull-to-refreshにネイティブのような流動的な感覚を与えるために、それぞれのデバイスが公開するプロパティを使用するリフレッシュ機能を提供します。

iOSとMaterial Designのネイティブリフレッシュ機能は、Ionicのデフォルトで有効になっています。ただし、iOSネイティブのリフレッシュ機能は、正しく動作するためにラバーバンドスクロールに依存しており、結果としてiOSデバイスとのみ互換性があります。ラバーバンドスクロールをサポートしていないデバイスでiOSモードで動作するアプリのために、フォールバックリフレッシャーを提供しています。

ネイティブのリフレッシャーでは、マテリアルデザイン用の circular スピナーを使用しますが、iOS では lines スピナーを使用します。iOSでは、ティックマークはページが下に引っ張られるにつれて徐々に表示されます。

Pullプロパティ、closeDuration、snapbackDurationのような特定のリフレッシャープロパティは、ネイティブリフレッシャーの多くがスクロールベースであるため、互換性がありません。サポートされていないプロパティの詳細については、Propertiesを参照してください。

リフレッシュコンテンツの pullingIcon を任意のアイコンまたはスピナーに設定することで、ネイティブリフレッシュモードを無効にすることができます。使用可能な値については、Ionicons および Spinner のドキュメントを参照してください。

Usage with Virtual Scroll

Refresher が機能するためには、スクロールコンテナが必要です。仮想スクロールを使用する場合は、ion-content のスクロールを無効にし、.ion-content-scroll-host クラスターゲットで、どの要素コンテナがスクロールコンテナを担当するかを指定する必要があります。

Developers should apply the following CSS to the scrollable container. This CSS adds a "rubber band" scrolling effect on iOS which allows the native iOS refresher to work properly:

.ion-content-scroll-host::before,
.ion-content-scroll-host::after {
  position: absolute;
  
  width: 1px;
  height: 1px;
  
  content: "";
}

.ion-content-scroll-host::before {
  bottom: -1px;
}

.ion-content-scroll-host::after {
  top: -1px;
}

高度な使用法

リフレッシャーはどのようなタイプのコンテンツでも使用できますが、ネイティブアプリでよくある使用例は、更新時に更新されるデータのリストを表示することです。以下の例では、アプリはデータのリストを生成し、更新が完了したときにリストの先頭にデータを追加します。実際のアプリでは、ネットワークまたはデータベース呼び出しによってリクエストを送信した後に、データを受信して更新します。

Interfaces

RefresherEventDetail

interface RefresherEventDetail {
  complete(): void;
}

RefresherCustomEvent

必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent インターフェースの代わりにこのインターフェースを使用することが可能です。

interface RefresherCustomEvent extends CustomEvent {
  detail: RefresherEventDetail;
  target: HTMLIonRefresherElement;
}

プロパティ

closeDuration

Description	Time it takes to close the refresher. Does not apply when the refresher content uses a spinner, enabling the native refresher.
Attribute	close-duration
Type	string
Default	'280ms'

disabled

Description	If true, the refresher will be hidden.
Attribute	disabled
Type	boolean
Default	false

mode

Description	The mode determines which platform styles to use.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

pullFactor

Description	How much to multiply the pull speed by. To slow the pull animation down, pass a number less than 1. To speed up the pull, pass a number greater than 1. The default value is 1 which is equal to the speed of the cursor. If a negative value is passed in, the factor will be 1 instead. For example: If the value passed is 1.2 and the content is dragged by 10 pixels, instead of 10 pixels the content will be pulled by 12 pixels (an increase of 20 percent). If the value passed is 0.8, the dragged amount will be 8 pixels, less than the amount the cursor has moved. Does not apply when the refresher content uses a spinner, enabling the native refresher.
Attribute	pull-factor
Type	number
Default	1

pullMax

Description	The maximum distance of the pull until the refresher will automatically go into the refreshing state. Defaults to the result of pullMin + 60. Does not apply when the refresher content uses a spinner, enabling the native refresher.
Attribute	pull-max
Type	number
Default	this.pullMin + 60

pullMin

Description	The minimum distance the user must pull down until the refresher will go into the refreshing state. Does not apply when the refresher content uses a spinner, enabling the native refresher.
Attribute	pull-min
Type	number
Default	60

snapbackDuration

Description	Time it takes the refresher to snap back to the refreshing state. Does not apply when the refresher content uses a spinner, enabling the native refresher.
Attribute	snapback-duration
Type	string
Default	'280ms'

イベント

Name	Description	Bubbles
ionPull	Emitted while the user is pulling down the content and exposing the refresher.	true
ionRefresh	Emitted when the user lets go of the content and has pulled down further than the pullMin or pulls the content down and exceeds the pullMax. Updates the refresher state to refreshing. The complete() method should be called when the async operation has completed.	true
ionStart	Emitted when the user begins to start pulling down.	true

メソッド

cancel

Description	Changes the refresher's state from refreshing to cancelling.
Signature	cancel() => Promise<void>

complete

Description

Call complete() when your async operation has completed. For example, the refreshing state is while the app is performing an asynchronous operation, such as receiving more data from an AJAX request. Once the data has been received, you then call this method to signify that the refreshing has completed and to close the refresher. This method also changes the refresher's state from refreshing to completing.

Signature

complete() => Promise<void>

getProgress

Description	A number representing how far down the user has pulled. The number 0 represents the user hasn't pulled down at all. The number 1, and anything greater than 1, represents that the user has pulled far enough down that when they let go then the refresh will happen. If they let go and the number is less than 1, then the refresh will not happen, and the content will return to it's original position.
Signature	getProgress() => Promise<number>

CSS Shadow Parts

No CSS shadow parts available for this component.

CSSカスタムプロパティ

No CSS custom properties available for this component.

Slots

No slots available for this component.