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	リフレッシャーを閉じるのにかかる時間。リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシャーが有効になります。
Attribute	close-duration
Type	string
Default	'280ms'

disabled

Description	trueの場合、リフレッシャーは非表示となる。
Attribute	disabled
Type	boolean
Default	false

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

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'

イベント

Name	Description
ionPull	ユーザーがコンテンツを引き下げ、リフレッシャーを露出している間に発行されます。
ionRefresh	ユーザーがコンテンツから手を離し、pullMinを越えて下に引いたとき、またはコンテンツを下に引き、pullMaxを越えたときに発行されます。リフレッシャーの状態を refreshing に更新します。非同期処理が完了したら complete() メソッドを呼び出す必要があります。
ionStart	ユーザーが引き下げを開始するときに発行されます。

メソッド

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カスタムプロパティ

No CSS custom properties available for this component.

Slots

No slots available for this component.