刷新组件

Refresher 为内容组件提供下拉刷新功能。下拉刷新模式允许用户下拉数据列表以获取更多数据。

数据应在 Refresher 的输出事件中进行修改。一旦异步操作完成且刷新应结束时，需要在 Refresher 上调用 complete() 方法。

基本用法

拉动属性

Refresher 具有多个用于自定义下拉手势的属性。设置 pullFactor 可改变下拉速度，设置 pullMin 属性可更改用户必须下拉的最小距离，设置 pullMax 属性可更改用户必须下拉的最大距离，然后 Refresher 才会进入 refreshing 状态。

启用原生 Refresher 时，这些属性不适用。

自定义 Refresher 内容

根据 Refresher 的状态是 pulling 还是 refreshing，可以在 refresher content 上自定义默认的图标、旋转器和文本。

设置 pullingIcon 将禁用原生 Refresher。

原生 Refresher

iOS 和 Android 平台都提供了原生 Refresher，它们利用各自设备暴露的属性来实现流畅、类原生的下拉刷新体验。

在 Ionic 中，iOS 和 Material Design 的原生 Refresher 默认启用。但是，iOS 原生 Refresher 依赖橡皮筋滚动效果才能正常工作，因此仅与 iOS 设备兼容。对于在不支持橡皮筋滚动的设备上以 iOS 模式运行的应用程序，我们提供了备用的 Refresher。

原生 Refresher 在 Material Design 中使用 circular 旋转器，而 iOS 使用 lines 旋转器。在 iOS 上，随着页面下拉，刻度标记会逐步显示。

某些 Refresher 属性（例如拉动属性、closeDuration 和 snapbackDuration）不兼容，因为大部分原生 Refresher 是基于滚动的。有关不受支持的属性，请参阅属性部分。

可以通过将 refresher content 上的 pullingIcon 设置为任意图标或旋转器来禁用原生 Refresher。有关可接受的值，请参阅 Ionicons 和 Spinner 文档。

与虚拟滚动结合使用

Refresher 需要一个滚动容器才能工作。使用虚拟滚动解决方案时，需要禁用 ion-content 上的滚动，并通过 .ion-content-scroll-host 类目标指示哪个元素容器负责滚动容器。

开发人员应将以下 CSS 应用于可滚动容器。此 CSS 在 iOS 上添加“橡皮筋”滚动效果，使原生 iOS Refresher 能够正常工作：

.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;
}

高级用法

虽然 Refresher 可以与任何类型的内容一起使用，但在原生应用程序中，一个常见用例是显示一个数据列表，并在刷新时更新该列表。在下面的示例中，应用程序生成一个数据列表，然后在刷新完成时将数据追加到列表顶部。在实际应用中，数据将通过网络或数据库调用发送请求后接收并更新。

事件处理

使用 ionPullStart 和 ionPullEnd

当用户开始下拉手势时，会触发 ionPullStart 事件。该事件在用户开始下拉 Refresher 时触发。

当 Refresher 返回到非活动状态时，会触发 ionPullEnd 事件，其 reason 属性为 'complete' 或 'cancel'，指示刷新操作是成功完成还是被取消。

Console

Console messages will appear here when logged from the example above.

接口

RefresherEventDetail

interface RefresherEventDetail {
  complete(): void;
}

RefresherPullEndEventDetail

interface RefresherPullEndEventDetail {
  reason: 'complete' | 'cancel';
}

RefresherCustomEvent

虽然不是必需的，但此接口可用于替代 CustomEvent 接口，以便对此组件发出的 Ionic 事件进行更强的类型检查。

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

RefresherPullEndCustomEvent

虽然不是必需的，但此接口可用于替代 CustomEvent 接口，以便对 ionPullEnd 事件进行更强的类型检查。

interface RefresherPullEndCustomEvent extends CustomEvent {
  detail: RefresherPullEndEventDetail;
  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. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
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
ionPullEnd	Emitted when the refresher has returned to the inactive state after a pull gesture. This fires whether the refresh completed successfully or was canceled.	true
ionPullStart	Emitted when the user begins to start pulling down.	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 (deprecated)	Emitted when the user begins to start pulling down. Deprecated — Use ionPullStart instead.	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.