DOCSEARCHbyAlgolia
Submit Docs

MJRefresh

repository·master·Indexed 12 days ago

https://github.com/codermjlee/mjrefresh

A pull-to-refresh framework for iOS supporting UIScrollView, UITableView, UICollectionView, and WKWebView. It provides components for drop-down refresh headers, pull-to-refresh footers, and trailers, including GIF-based animations and Swift chaining grammar. Supports dynamic internationalization and is compatible with iOS 9.0+.

Tokens
2.8K
Snippets
10
Records
14
Agent score
46%

What's inside MJRefresh

  1. Use MJRefresh with UICollectionView and WKWebView

    master

    MJRefresh supports various scrollable controls:

    UICollectionView

    • Drop-down refresh: Set collectionView.mj_header.
    • Pull-to-refresh: Set collectionView.mj_footer.
    • Trailer refresh (Side pull): Set collectionView.mj_trailer using MJRefreshNormalTrailer.

    WKWebView

    • To add refresh controls to a WKWebView, apply the header to its underlying UIScrollView: self.webView.scrollView.mj_header = ...
    // UICollectionView Drop-down
self.collectionView.mj_header = [MJRefreshNormalHeader headerWithRefreshingBlock:^{ ... }];

// UICollectionView Pull-to-refresh
self.collectionView.mj_footer = [MJRefreshAutoNormalFooter footerWithRefreshingBlock:^{ ... }];

// UICollectionView Trailer (Side pull)
self.collectionView.mj_trailer = [MJRefreshNormalTrailer trailerWithRefreshingBlock:^{ ... }];

// WKWebView Drop-down
self.webView.scrollView.mj_header = [MJRefreshNormalHeader headerWithRefreshingBlock:^{ ... }];

  3. Install MJRefresh

    master

    You can install MJRefresh using CocoaPods, Carthage, or by manual import.

    CocoaPods

    Add the following to your Podfile:

    pod 'MJRefresh'

    Carthage

    Add the following to your Cartfile:

    github "CoderMJLee/MJRefresh"

    Manual Import

    1. Drag all files in the MJRefresh folder into your Xcode project.
    2. Import the main header in your source files:
    #import "MJRefresh.h"
    pod 'MJRefresh'

  4. Configure Dynamic i18n (Internationalization) Switching

    master

    MJRefresh components automatically re-render when MJRefreshConfig.default.language is changed.

    Setting Language and Bundles

    Use MJRefreshConfig.default to configure the localization settings:

    • language: The language code (e.g., "zh-hans").
    • i18nFilename: The name of your .strings file (excluding the extension).
    • i18nBundle: The Bundle containing your localization files.

    Implementing i18n in Custom Components

    If you are building a DIY component, override i18nDidChange and use the provided localization methods to reset your text labels. You must call super.i18nDidChange() to ensure the layout is updated.

    Required localization methods:

    • Bundle.mj_localizedString(forKey: "")
    • Bundle.mj_localizedString(forKey: "", value: "")
    MJRefreshConfig.default.language = "zh-hans"
MJRefreshConfig.default.i18nFilename = "MyStringsFile"
MJRefreshConfig.default.i18nBundle = myBundle

  5. Use Swift Chaining Grammar for MJRefresh

    master

    If you are using Swift, MJRefresh supports a chaining syntax for easier configuration of headers.

    // Example using MJRefreshNormalHeader
func addRefreshHeader() {
    MJRefreshNormalHeader { [weak self] in
        // load some data
    }
    .autoChangeTransparency(true)
    .link(to: tableView)
}
    MJRefreshNormalHeader { [weak self] in
    // load some data
}.autoChangeTransparency(true).link(to: tableView)

  6. Manage pull-to-refresh footer states and visibility

    master

    For footers:

    • No More Data: Call [footer noticeNoMoreData] to transition the footer to the MJRefreshStateNoMoreData state.
    • Hide Title: Set footer.refreshingTitleHidden = YES or footer.stateLabel.hidden = YES to hide the status text.
    • Hide Footer: Use self.tableView.mj_footer.hidden = YES to hide the entire footer control.
    • Custom Text: Use setTitle:forState: to set custom strings for MJRefreshStateIdle, MJRefreshStateRefreshing, and MJRefreshStateNoMoreData.
    ```objc
// Become the status of NoMoreData
[footer noticeNoMoreData];

// Hide the title of refresh status
footer.refreshingTitleHidden = YES;

// Set title
[footer setTitle:@

  7. Use MJRefreshTrailer

    master
    A MJRefreshTrailer is a component used to add a refresh control at the end of a scroll view (similar to a footer but distinct in the class hierarchy). It can be initialized with a refreshing block or a target/action pair. It also supports ignoredScrollViewContentInsetRight to manage layout offsets.

  8. Implement Pull-to-Refresh (Footer)

    master

    Footers are used for 'load more' or 'automatic refresh' functionality at the bottom of a scroll view.

    Footer Types

    • MJRefreshFooter: The base class for footers.
    • MJRefreshAutoFooter: A footer that automatically triggers a refresh when the user reaches the bottom.

    Key Methods

    • noticeNoMoreData: Notifies the user that no more data is available (e.g., shows 'No more data').
    • resetNoMoreData: Clears the 'No more data' status.

    Auto-Refresh Configuration

    For MJRefreshAutoFooter, you can control:

    • automaticallyRefresh: A boolean to enable/disable auto-refresh (defaults to YES).
    • triggerAutomaticallyRefreshPercent: The threshold (e.g., 1.0) at which the refresh triggers. A value of 1.0 means the refresh triggers when the footer is fully visible.

  9. Configure GIF-based pull-to-refresh footers

    master

    Use MJRefreshAutoGifFooter to implement pull-to-refresh with animated images. You can set the images for the MJRefreshStateRefreshing state.

    // Set the callback
MJRefreshAutoGifFooter *footer = [MJRefreshAutoGifFooter footerWithRefreshingTarget:self refreshingAction:@selector(loadMoreData)];

// Set the refresh image
[footer setImages:refreshingImages forState:MJRefreshStateRefreshing];

// Set footer
self.tableView.mj_footer = footer;

  10. Implement Drop-down Refresh (Header)

    master

    To add a pull-to-refresh header to a UITableView or UICollectionView, use MJRefreshNormalHeader. You can provide a refreshing block or a target/action pair.

    Using a Refreshing Block

    This is the most common way to handle the refresh logic.

    Using Target and Action

    Use this if you want to trigger a specific selector on an object.

    Manual Trigger

    You can force the header into the refreshing state immediately using beginRefreshing.

    self.tableView.mj_header = [MJRefreshNormalHeader headerWithRefreshingBlock:^{
   // Call this Block when entering the refresh status automatically 
}];

// OR

self.tableView.mj_header = [MJRefreshNormalHeader headerWithRefreshingTarget:self refreshingAction:@selector(loadNewData)];

// To enter refresh status immediately:
[self.tableView.mj_header beginRefreshing];

  11. Configure GIF-based drop-down refresh headers

    master

    Use MJRefreshGifHeader to create a drop-down refresh header that uses animated GIF images for different states. You must provide a target object and a selector for the refresh action. You can set specific images for the MJRefreshStateIdle, MJRefreshStatePulling, and MJRefreshStateRefreshing states.

    // Set the callback
MJRefreshGifHeader *header = [MJRefreshGifHeader headerWithRefreshingTarget:self refreshingAction:@selector(loadNewData)];

// Set the ordinary state of animated images
[header setImages:idleImages forState:MJRefreshStateIdle];

// Set the pulling state of animated images
[header setImages:pullingImages forState:MJRefreshStatePulling];

// Set the refreshing state of animated images
[header setImages:refreshingImages forState:MJRefreshStateRefreshing];

// Set header
self.tableView.mj_header = header;

  12. Control Refresh State via MJRefreshComponent

    master

    All refresh controls (Headers, Footers, Trailers) inherit from MJRefreshComponent. You can control the state of the refresh manually using these methods:

    • beginRefreshing: Starts the refreshing animation/state.
    • endRefreshing: Stops the refreshing animation/state.
    • isRefreshing: Returns a boolean indicating if the control is currently refreshing.

    Additionally, you can set automaticallyChangeAlpha to control how the component's transparency changes during dragging.