Ketch

一个基于WorkManager的Android文件下载库，支持暂停和恢复

关于Ketch

Ketch是一个简单、强大、可定制的Android文件下载库，完全用Kotlin编写。它通过利用WorkManager的功能，简化了Android应用程序中下载文件的过程。Ketch保证无论应用程序处于何种状态都能完成下载。

高级设计

为什么使用Ketch

Ketch可以下载任何类型的文件（jpg、png、gif、mp4、mp3、pdf、apk等）
Ketch保证文件下载，除非明确取消或下载失败
Ketch提供所有下载信息，包括速度、文件大小、进度
Ketch提供暂停、恢复、取消、重试和删除下载文件的选项
Ketch提供以Flow形式观察下载项目（或单个下载项目）的选项
Ketch可以并行下载多个文件
Ketch支持大文件下载
Ketch提供各种自定义选项，包括自定义超时和自定义通知
Ketch简单易用
Ketch为每个下载提供通知，显示下载信息（速度、剩余时间、总大小、进度）
Ketch包括从通知中暂停、恢复、重试和取消下载的选项

高级设计

如何使用Ketch

安装

要将Ketch库集成到您的Android项目中，请按照以下简单步骤操作：

使用以下依赖项更新您的settings.gradle文件。

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url 'https://jitpack.io' } // 添加这一行
  }
}

使用以下依赖项更新您的模块级build.gradle文件。

dependencies {
  implementation 'com.github.khushpanchal:Ketch:2.0.1' // 使用最新可用版本
}

使用方法

使用Ketch的最简单方法：

在应用程序的onCreate中创建Ketch实例。（Ketch是一个单例类，首次使用时会自动创建实例）

  private lateinit var ketch: Ketch
  override fun onCreate() {
    super.onCreate()
    ketch = Ketch.builder().build(this)
  }

调用download()函数，传入url、fileName、path，并观察下载状态

  val id = ketch.download(url, fileName, path)
  lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
      ketch.observeDownloadById(id)
        .collect { downloadModel -> 
          // 使用downloadModel
        }
    }
  }

重要提示：根据API级别添加适当的存储权限，否则将触发onFailure(error)回调。请参考示例应用以获取更多信息。

取消下载

    ketch.cancel(downloadModel.id) // 其他选项：cancel(tag), cancelAll()

暂停下载

    ketch.pause(downloadModel.id) // 其他选项：pause(tag), pauseAll()

恢复下载

    ketch.resume(downloadModel.id) // 其他选项：resume(tag), resumeAll()

重试下载

    ketch.retry(downloadModel.id) // 其他选项：retry(tag), retryAll()

删除下载

    ketch.clearDb(downloadModel.id) // 其他选项：clearDb(tag), clearAllDb(), clearDb(timeInMillis)

观察：提供下载项目的状态流（每个项目包含下载信息，如url、fileName、path、tag、id、timeQueued、status、progress、length、speed、lastModified、metaData、failureReson、eTag）

  //在Fragment中观察
  viewLifecycleOwner.lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
      ketch.observeDownloads()
        .collect { 
           //将项目设置到适配器
        }
    }
  }

启用通知：

在清单文件中添加通知权限。

 <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

向用户请求权限（从Android 13（API级别33）开始需要）。请参考示例应用以获取更多信息。

在初始化时传递通知配置

ketch = Ketch.builder().setNotificationConfig(
         config = NotificationConfig(
           enabled = true,
           smallIcon = R.drawable.ic_launcher_foreground // 必须为通知传递smallIcon。
         )
       ).build(this)

自定义选项

为网络请求提供headers。

ketch.download(url, fileName, path,
 headers = headers, //默认：空哈希图
)

Tag：通过提供额外的Tag来对各种下载进行分组。（这个tag也可以用于取消、暂停、恢复、删除下载）
```
ketch.download(url, fileName, path,
 tag = tag, //默认：null
)
```

下载配置：提供自定义连接和读取超时

  ketch = Ketch.builder().setDownloadConfig(
    config = DownloadConfig(
      connectTimeOutInMs = 20000L, //默认：10000L
      readTimeOutInMs = 15000L //默认：10000L
    )
  ).build(this)

通知配置：提供自定义通知配置

  ketch = Ketch.builder().setNotificationConfig(
    config = NotificationConfig(
      enabled = true, //默认：false
      channelName = channelName, //默认："File Download"
      channelDescription = channelDescription, //默认："Notify file download status"
      importance = importance, //默认：NotificationManager.IMPORTANCE_HIGH
      smallIcon = smallIcon, //必需
      showSpeed = true, //默认：true
      showSize = true, //默认：true
      showTime = true //默认：true
    )
  ).build(this)

博客

查看博客以了解Ketch的工作原理（高级设计）：https://medium.com/@khush.panchal123/ketch-android-file-downloader-library-7369f7b93bd1

高级设计

联系我

查看我的博客：https://medium.com/@khush.panchal123

如果这个项目对你有帮助，请给这个项目一个 ⭐ 来表示你的喜爱 ❤️ ✌️

为项目做贡献

欢迎提供反馈、报告问题或为Ketch做出贡献。前往GitHub仓库，创建一个issue或查找待处理的issue。欢迎所有的拉取请求 😄

许可证

   Copyright (C) 2024 Khush Panchal

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.