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.

原生刷新器在 Material Design 中使用 circular 转子，而 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.

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

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

可以通过将 refresher 内容上的 pullingIcon 设置为任意图标或加载动画来禁用本地刷新器。有关可接受值，请参阅 Ionicons 和 Spinner 文档。

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

事件处理

🌐 Event Handling

使用 `ionPullStart` 和 `ionPullEnd`

🌐 Using ionPullStart and ionPullEnd

ionPullStart 事件在用户开始下拉手势时触发。当用户开始向下拉刷新控件时，会触发此事件。

🌐 The ionPullStart event is emitted when the user begins a pull gesture. This event fires when the user starts to pull the refresher down.

ionPullEnd 事件在刷新器返回到非活动状态时触发，具有 'complete' 或 'cancel' 的原因属性，用于指示刷新操作是成功完成还是被取消。

🌐 The ionPullEnd event is emitted when the refresher returns to an inactive state, with a reason property of 'complete' or 'cancel' indicating whether the refresh operation completed successfully or was canceled.

Console

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

接口

🌐 Interfaces

RefresherEventDetail

interface RefresherEventDetail {
  complete(): void;
}

RefresherPullEndEventDetail

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

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

RefresherPullEndCustomEvent

虽然不是必需的，但可以使用此接口替代 CustomEvent 接口，以便在 ionPullEnd 事件中实现更强的类型检查。

🌐 While not required, this interface can be used in place of the CustomEvent interface for stronger typing with the ionPullEnd event.

interface RefresherPullEndCustomEvent extends CustomEvent {
  detail: RefresherPullEndEventDetail;
  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. 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'`

事件

🌐 Events

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`

方法

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

基本用法​

拉动属性​

自定义刷新内容​

原生刷新​

与虚拟滚动一起使用​

高级用法​

事件处理​

使用 ionPullStart 和 ionPullEnd​

接口​

RefresherEventDetail​

RefresherPullEndEventDetail​

RefresherCustomEvent​

RefresherPullEndCustomEvent​

属性​

closeDuration​

disabled​

mode​

pullFactor​

pullMax​

pullMin​

snapbackDuration​

事件​

方法​

cancel​

complete​

getProgress​

CSS 阴影部分​

CSS 自定义属性​

插槽​

目录