Tiercel 2！完美支持原生級別後臺下載

時間  2019-11-06
標籤 tiercel 完美 支持 原生 級別 後臺 下載 简体版
原文   原文鏈接

項目地址：github.com/Danie1s/Tie…ios

Tiercel是一個簡單易用且功能豐富的純Swift下載框架，支持原生級別後臺下載，擁有強大的任務管理功能，知足下載類APP的大部分需求。git

Tiercel 2:

Tiercel 2 是全新的版本，下載實現基於URLSessionDownloadTask，支持原生的後臺下載，功能更增強大，使用方式也有了一些改變，不兼容舊版本，請注意新版的使用方法。若是想了解後臺下載的細節和注意事項，能夠看這篇文章：iOS原生級別後臺下載詳解github

舊版本下載實現基於URLSessionDataTask，不支持後臺下載，已經移至dataTask分支，原則上再也不更新，若是不須要後臺下載功能，或者不想遷移到新版，能夠直接下載dataTask分支的源碼使用，也能夠在Podfile裏使用如下方式安裝：swift

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'Tiercel', :git => 'https://github.com/Danie1s/Tiercel.git', :branch => 'dataTask'
end
複製代碼

Features:

  • 原生級別的後臺下載
  • 支持離線斷點續傳，不管crash仍是手動Kill App都不會影響
  • 精細的任務管理，每一個下載任務均可以單獨管理操做和狀態回調
  • 支持多個下載模塊，每一個模塊擁有一個管理者，每一個模塊互不影響
  • 下載模塊的管理者擁有總任務的狀態回調
  • 內置了下載速度、剩餘時間等常見的下載信息
  • 鏈式語法調用
  • 支持控制下載任務的最大併發數
  • 支持文件校驗
  • 線程安全

Requirements

  • iOS 8.0+
  • Xcode 10.0+
  • Swift 4.2+

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:api

$ gem install cocoapods
複製代碼

CocoaPods 1.1+ is required to build Tiercel.數組

To integrate Tiercel into your Xcode project using CocoaPods, specify it in your Podfile:xcode

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'Tiercel'
end
複製代碼

Then, run the following command:緩存

$ pod install
複製代碼

Manually

If you prefer not to use any of the aforementioned dependency managers, you can integrate Tiercel into your project manually.安全

Example

To run the example project, clone the repo, and run Tiercel.xcodeproj .ruby

批量下載

跨控制下載

Usage

配置

Tiercel內置一個全局的TRManager.default單例，由於支持原生後臺下載，因此須要在AppDelegate 文件裏配置

如下爲內置的default單例配置方法，若是須要使用多個下載模塊，或者須要自定義TRManager，可參照Demo

// 在AppDelegate文件裏

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // 若是有使用內置全局的default單例，必須在此方法內調用一次，不然不會在App啓動的時候初始化
    
    // 在這裏進行初始化的配置，也能夠在任何地方，隨時進行配置
    TRManager.default.configuration.allowsCellularAccess = true
    
    return true
}

// 必須實現此方法，而且把identifier對應的completionHandler保存起來
func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {

    if TRManager.default.identifier == identifier {
        TRManager.default.completionHandler = completionHandler
    }

}
複製代碼

基本用法

一行代碼開啓下載

// 建立下載任務而且開啓下載，同時返回可選類型的TRDownloadTask實例，若是URLString無效，則返回nil
let task = TRManager.default.download("http://api.gfs100.cn/upload/20171219/201712191530562229.mp4")

// 批量建立下載任務而且開啓下載，返回有效URLString對應的任務數組，URLStrings須要跟fileNames一一對應
let tasks = TRManager.default.multiDownload(URLStrings)
複製代碼

若是須要設置回調

// 回調閉包的參數是TRDownloadTask實例，能夠獲得全部相關的信息
// 回調閉包都是在主線程運行
// progress 閉包：若是任務正在下載，就會觸發
// success 閉包：任務已經下載過，或者下載完成，都會出發，這時候task.status == .succeeded
// failure 閉包：只要task.status != .succeeded，就會觸發：
// 1. 暫停任務，這時候task.status == .suspended
// 2. 任務下載失敗，這時候task.status == .failed
// 3. 取消任務，這時候task.status == .canceled
// 4. 移除任務，這時候task.status == .removed
let task = TRManager.default.download("http://api.gfs100.cn/upload/20171219/201712191530562229.mp4")

task?.progress({ (task) in
    let progress = task.progress.fractionCompleted
    print("下載中, 進度：\(progress)")
}).success({ (task) in
    print("下載完成")
}).failure({ (task) in
    print("下載失敗")
})
複製代碼

下載任務的管理和操做。在Tiercel中，URLString是下載任務的惟一標識，若是須要對下載任務進行操做，則使用TRManager實例對URLString進行操做。

let URLString = "http://api.gfs100.cn/upload/20171219/201712191530562229.mp4"

// 建立下載任務而且開啓下載，同時返回可選類型的TRDownloadTask實例，若是URLString無效，則返回nil
let task = TRManager.default.download(URLString)
// 根據URLString查找下載任務，返回可選類型的TRTask實例，若是不存在，則返回nil
let task = TRManager.default.fetchTask(URLString)

// 開始下載
// 若是調用suspend暫停了下載，能夠調用這個方法繼續下載
TRManager.default.start(URLString)

// 暫停下載
TRManager.default.suspend(URLString)

// 取消下載，沒有下載完成的任務會被移除，不保留緩存，已經下載完成的不受影響
TRManager.default.cancel(URLString)

// 移除下載，任何狀態的任務都會被移除，沒有下載完成的緩存文件會被刪除，能夠選擇是否保留已經下載完成的文件
TRManager.default.remove(URLString, completely: false)

// 除了能夠對單個任務進行操做，TRManager也提供了對全部任務同時操做的API
TRManager.default.totalStart()
TRManager.default.totalSuspend()
TRManager.default.totalCancel()
TRManager.default.totalRemove(completely: false)
複製代碼

後臺下載

Tiercel 2 的下載實現基於URLSessionDownloadTask，支持原生的後臺下載，按照蘋果官方文檔的要求，TRManager實例必須在App啓動的時候建立，而且在AppDelegate 文件裏實現如下方法

// 必須實現此方法，而且把identifier對應的completionHandler保存起來
func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {

    if TRManager.default.identifier == identifier {
        TRManager.default.completionHandler = completionHandler
    }
}
複製代碼

只要使用Tiercel 開啓了下載任務：

  • 手動Kill App，任務會暫時，重啓App後能夠恢復進度，繼續下載
  • 只要不是手動Kill App，任務會一直在下載
    • 把App退回後臺，任務會一直在下載
    • 不管在前臺仍是後臺，若是App崩潰或者被系統關閉，任務仍是會一直在下載
    • 重啓手機，任務會一直在下載

若是想了解後臺下載的細節和注意事項，能夠看這篇文章：iOS原生級別後臺下載詳解

文件校驗

Tiercel提供了文件校驗功能，能夠根據須要添加，校驗結果在回調的task.validation裏

// 回調閉包在主線程運行
let task = TRManager.default.download("http://dldir1.qq.com/qqfile/QQforMac/QQ_V4.2.4.dmg")

task?.validateFile(verificationCode: "9e2a3650530b563da297c9246acaad5c",
                   verificationType: .md5,
                   validateHandler: { (task) in
                    if task.validation == .correct {
                        // 文件正確
                    } else {
                        // 文件錯誤
                    }
})
複製代碼

TRChecksumHelper是文件校驗的工具類，能夠直接使用它對已經存在的文件進行校驗

/// 對文件進行校驗，是在子線程進行的
///
/// - Parameters:
/// - filePath: 文件路徑
/// - verificationCode: 文件的Hash值
/// - verificationType: Hash類型
/// - completion: 完成回調
public class func validateFile(_ filePath: String, verificationCode: String, verificationType: TRVerificationType, completion: @escaping (Bool) -> ()) {
    
}
複製代碼

TRManager

TRManager是下載任務的管理者，管理當前模塊全部下載任務，內置一個全局的default單例，若是須要多個下載模塊，或者須要自定義TRManager，能夠手動建立TRManager實例。

⚠️⚠️⚠️ 按照蘋果官方文檔的要求，TRManager實例必須在App啓動的時候建立，即TRManager的生命週期跟App幾乎一致，爲方便使用，最好是做爲AppDelegate的屬性，或者是全局變量，具體請參照Demo。

/// 初始化方法
///
/// - Parameters:
/// - identifier: 設置TRManager實例的標識，區分不一樣的下載模塊，同時爲urlSession的標識，原生級別的後臺下載必需要有惟一標識
public init(_ identifier: String) {
    // 實現的代碼... 
}
複製代碼

TRManager做爲全部下載任務的管理者，也能夠設置回調

// 回調閉包的參數是TRManager實例，能夠獲得全部相關的信息
// 回調閉包都是在主線程運行
// progress 閉包：只要有一個任務正在下載，就會觸發
// success 閉包：只有一種狀況會觸發：
// 全部任務都下載成功(取消和移除的任務會被移除而後銷燬，再也不被manager管理) ，這時候manager.status == .succeeded
// failure 閉包：只要manager.status != .succeeded，就會觸發：
// 1. 調用所有暫停的方法，或者沒有等待運行的任務，也沒有正在運行的任務，這時候manager.status == .suspended
// 2. 全部任務都結束，但有一個或者多個是失敗的，這時候manager.status == .failed
// 3. 調用所有取消的方法，或者剩下一個任務的時候把這個任務取消，這時候manager.status == .canceled
// 4. 調用所有移除的方法，或者剩下一個任務的時候把這個任務移除，這時候manager.status == .removed
TRManager.default.progress { (manager) in
    let progress = manager.progress.fractionCompleted
    print("downloadManager運行中, 總進度：\(progress)")
    }.success { (manager) in
         print("全部下載任務都成功了")
    }.failure { (manager) in
         if manager.status == .suspended {
            print("全部下載任務都暫停了")
        } else if manager.status == .failed {
            print("存在下載失敗的任務")
        } else if manager.status == .canceled {
            print("全部下載任務都取消了")
        } else if manager.status == .removed {
            print("全部下載任務都移除了")
        }
}
複製代碼

TRManager的主要屬性

// 內置的全局單例
public static let `default` = TRManager("default")
// 設置內置日誌打印等級，若是爲none則不打印
public static var logLevel: TRLogLevel = .detailed
// 是否須要對networkActivityIndicator進行管理
public static var isControlNetworkActivityIndicator = true
// TRManager的狀態
public var status: TRStatus = .waiting
// TRManager的緩存管理實例
public var cache: TRCache
// TRManager的標識，區分不一樣的下載模塊
public let identifier: String
// TRManager的進度
public var progress: Progress
// TRManager的配置，能夠設置請求超時時間，最大併發數，是否容許蜂窩網絡下載
public var configuration = TRConfiguration()
// 全部下載中的任務加起來的總速度
public private(set) var speed: Int64 = 0
// 全部下載中的任務須要的剩餘時間
public private(set) var timeRemaining: Int64 = 0
// manager管理的下載任務，取消和移除的任務會被銷燬，但操做是異步的，在回調閉包裏面獲取才能保證正確
public var tasks: [TRTask] = []
複製代碼

TRConfiguration

TRConfiguration是Tiercel中配置TRManager的結構體，可配置屬性以下：

// 請求超時時間
public var timeoutIntervalForRequest = 30.0

// 最大併發數
public var maxConcurrentTasksLimit = Int.max

// 是否容許蜂窩網絡下載
public var allowsCellularAccess = false
複製代碼

更改TRManager的配置

// 不管是否有下載任務正在運行，均可以在任何地方，隨時配置
// 若是隻是更改某一項，能夠直接對TRManager屬性設置
TRManager.default.configuration.allowsCellularAccess = true

// 若是是須要更改多項，最好是從新建立TRConfiguration
let configuration = TRConfiguration()
configuration.allowsCellularAccess = true
configuration.maxConcurrentTasksLimit = 2
configuration.timeoutIntervalForRequest = 60

TRManager.default.configuration = configuration
複製代碼

TRDownloadTask

TRDownloadTask是Tiercel中的下載任務類，繼承自TRTask。**在Tiercel中，URLString是下載任務的惟一標識，URLString表明着任務，若是須要對下載任務進行操做，則使用TRManager實例對URLString進行操做。**因此TRDownloadTask實例都是由TRManager實例建立，單首創建沒有意義。

主要屬性

// 保存到沙盒的下載文件的文件名，若是在下載的時候沒有設置，則默認爲url的md5加上文件擴展名
public internal(set) var fileName: String
// 下載任務對應的URLString
public let URLString: String
// 下載任務的狀態
public var status: TRStatus
// 下載文件的校驗狀態
public var validation: TRValidation
// 下載任務的進度
public var progress: Progress = Progress()
// 下載任務的開始日期
public var startDate: TimeInterval = 0
// 下載任務的結束日期
public var endDate: TimeInterval = Date().timeIntervalSince1970
// 下載任務的速度
public var speed: Int64 = 0
// 下載任務的剩餘時間
public var timeRemaining: Int64 = 0
// 下載文件路徑
public var filePath: String
// 下載文件的擴展名
public var pathExtension: String?
複製代碼

對下載任務操做，必須經過TRManager實例進行，不能用TRDownloadTask實例直接操做

  • 開啓
  • 暫停
  • 取消，沒有完成的任務從TRManager實例中的tasks中移除，不保留緩存，已經下載完成的任務不受影響
  • 移除，已經完成的任務也會被移除，沒有下載完成的緩存文件會被刪除，已經下載完成的文件能夠選擇是否保留

注意：對下載中的任務進行暫停、取消和移除操做，結果是異步回調的，在回調閉包裏面獲取狀態才能保證正確

TRCache

TRCache是Tiercel中負責管理緩存下載任務信息和下載文件的類。TRCache實例通常做爲TRManager實例的屬性來使用，一樣地，Tiercel內置一個全局的TRCache.default單例，對應TRManager.default。

/// 初始化方法
///
/// - Parameters:
/// - name: 不一樣的name，表明不一樣的下載模塊，對應的文件放在不一樣的地方，對應TRManager建立時傳入的identifier
public init(_ name: String) {
    // 實現的代碼...
}
複製代碼

主要屬性

// 下載模塊的目錄路徑
public let downloadPath: String

// 沒有完成的下載文件緩存的目錄路徑
public let downloadTmpPath: String

// 下載完成的文件的目錄路徑
public let downloadFilePath: String
複製代碼

主要API分紅幾大類：

  • 檢查沙盒是否存在文件
  • 移除跟下載任務相關的文件
  • 保存跟下載任務相關的文件
  • 讀取下載任務相關的文件，得到下載任務相關的信息

License

Tiercel is available under the MIT license. See the LICENSE file for more info.

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程