Innovative Software Technology

Building a Custom, Non-Intrusive Pull-to-Refresh Component for Mobile Apps

Introduction

Pull-to-refresh and load-more functionality are ubiquitous features in mobile applications. While many platforms provide built-in refresh components, they often lack the flexibility needed for custom designs and unique product requirements. This article outlines a method to create a highly customizable and non-intrusive pull-to-refresh component from the ground up.

Key Features and Goals

The ideal pull-to-refresh component should have the following characteristics:

  1. Non-Intrusive: It should not require modification of the existing data source.
  2. Universal Compatibility: It should work with any layout, including lists, grids, web views, scrollable text, rows, columns, and more.
  3. Customizable Header and Footer: Support for personalized header and footer views, including animations (like Lottie animations).
  4. Direction Agnostic: Works for both vertical (pull-down to refresh, pull-up to load more) and horizontal (pull-left/right) lists.
  5. Actionable Pull: Ability to trigger actions beyond refreshing, such as opening another page on a sufficiently large pull.

Visual Examples

Here’s a visual overview of the component’s capabilities:

Vertical List Examples:

| Feature | Description |
| :———————– | :——————————————————————————————————————————————————————————————– |
| Vertical List Refresh | Standard pull-down refresh on a vertical list. |
| Vertical Grid Refresh | Pull-down refresh applied to a grid layout. |
| Pull-to-Open | Pulling down far enough triggers navigation to a different page. |
| Auto-Refresh | Automatic refresh initiation (e.g., triggered by a timer or other event). |
|Web View Refresh|Pull to refresh on an integrated web view.|
|Custom animation refresh|Using a user-defined animation in the refresh header.|
|Lottie animation refresh|Implementation of Lottie Files in the refresh header|
|Horizontal List refresh|Left/Right refresh for horizonal lists.|
Horizontal Header/Footer Styles (Footer is analogous):

| Header Style | Description |
| :—————————————— | :———————————————————————————————————– |
| Normal Horizontal | Header with a fixed width and full height. |
| Rotated 90° Counter-Clockwise | Header rotated, full width, fixed height (layout similar to vertical list headers). |
| Rotated 90° Clockwise | Header rotated, full width, fixed height (layout similar to vertical list headers). |
Placeholder states(Loading, Empty Data, Load Failed, No Network):
It is included in the GIF above.

Implementation Steps

The implementation can be broken down into these key steps:

Step 1: Constructing the Layout Structure

The basic structure consists of three main parts: a header, the content area, and a footer. All of these views are provided externally, allowing for maximum flexibility.

//header
@BuilderParam headerView: () => void
//Content
@BuilderParam contentView: () => void
//Footer
@BuilderParam loadView: () => void

build() {
   this.headerAndContent()
}

@Builder
private headerAndContent() {
  // Header view (full width, auto height for vertical lists)
  Stack(){
      this.headerView()
  }.width("100%")

  // Content view
  Stack(){
      this.contentView()
  }.width("100%").height("100%")

  // Footer view (full width, auto height for vertical lists)
  Stack(){
      this.loadView()
  }.width("100%")
}

Initially, these views will overlap. We use onMeasureSize() and onPlaceChildren() to correctly measure and position the header, content, and footer. The core idea is to offset the header upwards by its own height and the footer downwards by the content’s height.

private sizeResult: SizeResult = { width: 0, height: 0 }
// Header view height
private headerHeight = 0

// View measurement
onMeasureSize(selfLayoutInfo: GeometryInfo, children: Measurable[], constraint: ConstraintSizeOptions): SizeResult {
    // Measure child components
    const headerResult  = children[0].measure(constraint)
    const contentResult = children[1].measure(constraint)
    const footerResult  = children[2].measure(constraint)

    // Record header height (needed for animation)
    this.headerHeight = headerResult.height;

    // Set component dimensions to match the content area
    this.sizeResult.width = contentResult.width;
    this.sizeResult.height = contentResult.height;

    // Return the component's size
    return this.sizeResult
}

// View layout
onPlaceChildren(selfLayoutInfo: GeometryInfo, children: Layoutable[], constraint: ConstraintSizeOptions): void {
    const childHeader = children[0]
    // Offset header upwards by its height
    childHeader.layout({ y: -childHeader.measureResult.height })

    const childContent = children[1]
    // Content view doesn't need offsetting
    childContent.layout({})

    const childFooter = children[2]
    // Offset footer downwards by the content height
    childFooter.layout({ y: this.sizeResult.height })
}

Step 2: Implementing the Pull Action

  1. Bind a PanGesture (specifically, PanDirection.Vertical) to the content view using parallelGesture.
  2. Track the gesture’s offset. Use the offset property of the header and content views to create the pull-down effect.
// Total offset for header and content (used for animation)
totalOffsetY: number = 0

// Current offset for header and content
@State currentOffsetY: number = 0

// Previous offset during drag
preOffsetY = 0;

// Apply offset to header and content views
.offset({ y: this.currentOffsetY })

// Content view
Stack() {
    this.contentView()
}
.offset({ y: this.currentOffsetY })
.width("100%")
.height("100%")
.parallelGesture(PanGesture(new PanGestureOptions({ direction: PanDirection.Vertical }))
.onActionStart((event: GestureEvent) => {
    // Pan gesture recognized - record initial offset
    this.preOffsetY = event.offsetY
}).onActionUpdate((event: GestureEvent) => {
    // Pan gesture movement
    // New offset = (current offset - previous offset) * 0.5 (damping factor)
    // Total offset = new offset + current view offset
    this.currentOffsetY = this.currentOffsetY + (event.offsetY - this.preOffsetY)*0.5
    if(this.currentOffsetY<0){
       // Prevent content from going out of bounds during pull-up
       this.currentOffsetY=0
    }
    this.totalOffsetY=this.currentOffsetY
    this.preOffsetY = event.offsetY

    if(this.currentOffsetY<100){
        // Display "Pull to refresh" UI when offset is less than 100vp
    }else{
        // Display "Release to refresh" UI when offset is greater than or equal to 100vp
    }

}).onActionEnd((event: GestureEvent)=>{
    // Pan gesture ended (finger lifted)
}).onActionCancel(()=>{
    // Pan gesture cancelled (e.g., window loses focus)
}))

Step 3: Implementing the Snap-Back Animation

  1. Add an onTouch listener to the content view. Trigger the snap-back animation on TouchType.Up and TouchType.Cancel events.

It is crucial to use onTouch in addition to PanGesture‘s onActionEnd because PanGesture requires a minimum drag distance to be recognized. onTouch ensures that the animation is triggered even if the user just taps without dragging. It also handles cases where the animation needs to be interrupted.

import animator from '@ohos.animator'
private animOption:AnimatorOptions={
  duration: 250,
  easing: "fast-out-linear-in",
  delay: 0,
  fill: "forwards",
  direction: "normal",
  iterations: 1,
  begin: 0,
  end: 1
}
private anim: AnimatorResult = animator.create(this.animOption);
private animPause=false;

aboutToAppear(): void {
  this.anim.onFrame = (progress: number) => {
    if(this.animPause){
      // If animation is cancelled, progress becomes 1; return to avoid immediate jump
      return
    }
    // Calculate current offset based on total offset and animation progress
    this.currentOffsetY = this.totalOffsetY * (1 - progress)
  }
  this.anim.onFinish=()=> {
    // Animation completed - set total offset to current offset
    this.totalOffsetY=this.currentOffsetY
  }
  this.anim.onCancel=()=> {
    // Animation cancelled - set total offset to current offset
    this.totalOffsetY=this.currentOffsetY
  }
}

// Add onTouch listener to content view
.onTouch((event: TouchEvent) => {
  const type = event.type
  if(type==TouchType.Down){
    // If there's a pull offset, pause the animation on touch
    if(this.currentOffsetY>0){
      this.animPause=true
      this.anim.cancel()
    }
  }else if (type == TouchType.Up || type == TouchType.Cancel) {
    // If there's a pull offset, resume/start the animation on release
    if(this.currentOffsetY>0){
      this.animPause=false
      // Play the snap-back animation
      this.anim.play()
    }
  }
})

We use cancel() instead of pause() to interrupt the animation. This is because if we use pause(), then drag the view again (changing totalOffsetY), and then release, the animation’s progress would be incorrect, leading to a jarring visual effect. cancel() resets the animation, ensuring smooth transitions.

Step 4: Triggering the Refresh and Displaying the Refreshing Header

Different UI states are displayed based on the pull offset. For example:

  • offset <= 100vp: Show “Pull to refresh”
  • offset >= 100vp: Show “Release to refresh”

When the refresh condition is met, and the user releases, the animation plays, but it stops at the header’s height, displaying a “Refreshing” state.

// Callback for starting the refresh (set externally)
public onRefresh: () => void = () => {
}

// Release triggers refresh
.onTouch((event: TouchEvent) => {
  const type = event.type
  if (type == TouchType.Down) {
    if (this.currentOffsetY > 0) {
      this.animPause = true
      this.anim.cancel()
    }
  } else if (type == TouchType.Up || type == TouchType.Cancel) {
    this.animPause = false
    if (this.currentOffsetY > 100) {
      // Update header view to show "Refreshing" state

      // Trigger the refresh action
      this.onRefresh()

      /* Calculate the animation progress to snap back to the header height */
      this.animOption.end = (this.currentOffsetY - this.headerHeight) / this.currentOffsetY
      this.anim.reset(this.animOption)
      this.anim.play()
    } else if (this.currentOffsetY > 0) {
      // Play the full snap-back animation
      this.animOption.end = 1
      this.anim.reset(this.animOption)
      this.anim.play()
    }
  }
})

Step 5: Creating a Controller for Refresh Completion

How does the external code (e.g., your data loading logic) notify the component that the refresh is complete? We use a controller.

PullToRefreshLayout({
    /* Set the controller */
    controller: this.controller,
    /* Content view */
    contentView: () => {
       this.contentView()
    },
    /* Trigger refresh */
    onRefresh: () => {
       setTimeout(() => {
           // Notify refresh completion (success in this case)
          this.controller.refreshComplete(true)
      }, 1000)
    }
    }).width("100%").height("100%").clip(true)

export class RefreshController {
  /* Refresh complete callback (true: success, false: failure) */
  refreshComplete: (isSuccess: boolean) => void = (isSuccess: boolean) => {
  }
}

public controller: RefreshController = new RefreshController()

aboutToAppear(): void {
  /* Notify the component of the refresh result */
  this.controller.refreshComplete = (isSuccess: boolean) => {
    if(isSuccess){
        // Handle refresh success
    }else if(){
        // Handle refresh failure
    }
    // Update header to show "Refresh successful" or "Refresh failed"

    // Animate back to hide the header
    this.animOption.end = 1
    this.anim.reset(this.animOption)
    this.anim.play()
  }
}

Step 6: Handling Pull-Down After Scroll-Up

If the content view is a scrollable list (like List), a problem arises: scrolling the list up and then pulling down causes the header to shift downwards incorrectly. This is because the pull-down gesture is not aware of the list’s scroll position.

Solution: The external code needs to inform the component whether the list is at the top.

PullToRefreshLayout({
    /* Set the controller */
    controller: this.controller,
    /* Content view */
    contentView: () => {
       this.contentView()
    },
    /* Trigger refresh */
    onRefresh: () => {
       setTimeout(() => {
       // Notify refresh success
      this.controller.refreshSuccess()
      }, 1000)
    },
    /* Check if pull-to-refresh is allowed */
    onCanPullRefresh: () => {
        if (!this.scroller.currentOffset()) {
            /* Handle empty data case */
           return true
        }
        // If the list is at the top, allow pull-down; otherwise, prevent it
        return this.scroller.currentOffset().yOffset <= 0
    }
    }).width("100%").height("100%").clip(true)


/* Callback to check if pull-to-refresh is allowed (default: true) */
public onCanPullRefresh: () => boolean = () => true

.onActionUpdate((event: GestureEvent) => {
    // If pull-to-refresh is not allowed, don't offset the header
    if(!this.onCanPullRefresh()){
      return
    }
    // ... rest of the onActionUpdate logic ...
})

Step 7: Handling Pull-Up After Pull-Down

Another issue with scrollable content: pulling down to show the header, and then pulling up, causes the list content to scroll unnecessarily.

Solution: When pulling up to hide the header, explicitly set the list’s scroll offset to 0.

public scroller: Scroller | undefined = undefined

.onActionUpdate((event: GestureEvent) => {
if(!this.onCanPullRefresh()){
  return
}
// If pulling up while the header is visible
if (this.currentOffsetY > 0 && this.preOffsetY>event.offsetY) {
  /* Prevent list scrolling during pull-up after pull-down */
  if (this.scroller) {
    this.scroller.scrollTo({ yOffset: 0, xOffset: this.scroller.currentOffset()?.xOffset ?? 0 })
  }
}

// ... rest of onActionUpdate


scroller: Scroller = new Scroller()
PullToRefreshLayout({
    // Set the content list's scroll controller
    scroller: this.scroller,
    controller: this.controller,
    /* Content view */
    contentView: () => {
       this.contentView()
    }
    })
    .width("100%")
    .height("100%")
    .clip(true)

@Builder
contentView() {
  List({ scroller: this.scroller }) {

  }.width("100%").height("100%")
  .edgeEffect(EdgeEffect.None)
}

Note: clip(true) is used on the custom component to address the issue from Step 1 where the header might be visible even when positioned outside the component’s bounds.

Conclusion

This article presents a foundational approach to building a robust and highly customizable pull-to-refresh component. The key principles are:

  • Separation of Concerns: The component manages layout and animation, while the external code handles data loading and scroll position.
  • Event Handling: Careful use of onTouch and PanGesture events ensures proper animation control.
  • External Control: A controller allows the external code to communicate with the component (e.g., to signal refresh completion).
  • Scroll Awareness: Handling scroll position prevents unwanted content movement during pull gestures.

While this guide covers the core logic, a complete implementation would involve additional details and edge-case handling.

How Innovative Software Technology Can Help

At Innovative Software Technology, we specialize in crafting high-performance, user-friendly mobile applications. Our expertise in custom UI component development, like the pull-to-refresh solution detailed above, enables us to deliver exceptional user experiences. We can seamlessly integrate this component, or build entirely bespoke UI solutions, optimized for your specific app’s needs and target audience. Our focus on SEO-friendly development practices, combined with our UI/UX design skills, ensures that your application not only functions flawlessly but also achieves high visibility in app stores and search engines. Contact us today to discuss how we can elevate your mobile app with cutting-edge UI and robust, SEO-optimized code.

Leave a Reply

Your email address will not be published. Required fields are marked *

Fill out this field
Fill out this field
Please enter a valid email address.
You need to agree with the terms to proceed