ion-refresher

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.

应在刷新输出事件期间修改数据。一旦异步操作完成并且刷新应该结束，就需要在刷新时调用 complete()。

¥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

刷新器有几个用于自定义拉动手势的属性。设置 pullFactor 来更改拉动的速度，设置 pullMin 属性来更改用户必须下拉的最小距离，设置 pullMax 属性来更改用户在刷新进入 refreshing 状态之前必须下拉的最大距离。

¥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

可以根据刷新器的状态是 pulling 还是 refreshing 在 刷新内容 上自定义默认图标、加载控件和文本。

¥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.

设置 pullingIcon 将禁用 原生刷新。

¥Setting pullingIcon will disable the native refresher.

原生刷新

¥Native Refreshers

iOS 和 Android 平台都提供了刷新器，这些刷新器使用各自设备公开的属性，以便为拉动刷新提供流畅、类似原生的感觉。

¥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.

Ionic 中默认启用 iOS 和 Material Design 原生刷新器。然而，原生 iOS 刷新器依靠橡皮筋滚动才能正常工作，因此仅与 iOS 设备兼容。我们为不支持橡皮筋滚动的设备上以 iOS 模式运行的应用提供了后备刷新。

¥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.

原生刷新器使用 circular 加载控件进行 Material Design，而 iOS 使用 lines 加载控件。在 iOS 上，当页面被下拉时，刻度线将逐渐显示。

¥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.

某些刷新器属性（例如 拉动属性、closeDuration 和 snapbackDuration）不兼容，因为许多原生刷新器都是基于滚动的。有关不支持的属性的更多信息，请参阅 属性。

¥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.

可以通过将 刷新内容 上的 pullingIcon 设置为任何图标或加载控件来禁用原生刷新器。有关可接受的值，请参阅 Ionic 图标 和 旋转器 文档。

¥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

刷新需要滚动容器才能运行。使用虚拟滚动解决方案时，你需要禁用 ion-content 上的滚动，并使用 .ion-content-scroll-host 类目标指示哪个元素容器负责滚动容器。

¥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.

开发者应将以下 CSS 应用到可滚动容器。此 CSS 在 iOS 上添加了 "橡皮筋" 滚动效果，允许原生 iOS 刷新器正常工作：

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

高级用法

¥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

虽然不是必需的，但可以使用此接口代替 CustomEvent 接口，以便使用从此组件发出的 Ionic 事件进行更强的键入。

¥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	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'

事件

¥Events

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

方法

¥Methods

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 阴影部分

¥CSS Shadow Parts

No CSS shadow parts available for this component.

CSS 自定义属性

¥CSS Custom Properties

No CSS custom properties available for this component.

插槽

¥Slots

No slots available for this component.