NativeScript Downloader

@voicethread/nativescript-downloader

此下载器插件导出名为 Downloader 的类，该类有一个单函数 download()。

对于 iOS，Downloader 使用 NSURLSession 从有效 URL 启动下载。

对于 Android，Downloader 使用 DownloadManager 从有效 URL 启动下载。

https://github.com/VoiceThread/nativescript-plugins/assets/20136906/80d40e3f-2c42-4d61-8213-52b84e965ac9

内容

NativeScript Downloader

安装

npm install @voicethread/nativescript-downloader --save

ns plugin add @voicethread/nativescript-downloader

用法

了解如何使用此插件的最佳方式是研究此仓库中包含的演示应用程序。您可以通过查看 apps/demo/src/plugin-demos/nativescript-downloader.ts 页面来了解如何在 TypeScript 应用程序中使用此插件。

导入插件。

import { Downloader, DownloadOptions, MessageData } from '@voicethread/nativescript-downloader';

创建下载器实例。

const dp = new Downloader();

下载文件。

const dlfile = await dp.download({ url: 'https://some.domain.com/file.txt' });

唯一必需的选项是要下载的 URL。在开始下载之前，您还可以根据下面的下载器选项传递其他选项。

如果您想更新下载状态消息/指示器或处理错误，可以在下载操作期间监听下载器发出的事件。成功完成后，插件将返回一个文件引用，该文件位于 Android 的应用程序缓存目录或 iOS 的应用程序文档目录中，开发者可以直接使用，而无需额外的文件操作权限。

dp.on(Downloader.DOWNLOAD_STARTED, (payload: MessageData) => {
  console.log('started', payload?.data?.contentLength);
});
dp.on(Downloader.DOWNLOAD_PROGRESS, (payload: MessageData) => {
  console.log(' >>>>>  ', payload?.data?.progress, payload?.data?.url, payload?.data?.destinationFilename);
});
dp.on(Downloader.DOWNLOAD_COMPLETE, (payload: MessageData) => {
  console.log('finished', payload?.data?.filepath);
});
dp.on(Downloader.DOWNLOAD_ERROR, (payload: MessageData) => {
  console.log('ERROR!', payload?.data);
});
dp.download({ url: 'https://some.domain.com/file.txt' }).then((file: File) => {
  if (!file) {
    return console.error('Failed to download file!');
  }
  console.log('Finished downloading file ', file.path);
});

支持的下载器选项

interface DownloadOptions {
  url: string; //must be a valid url, usually https unless you allow http in your app
  request?: RequestOptions; //request header strings to be passed to the https connection
  destinationPath?: string; //must be a valid path for app to create a new file (existing directory with valid filename)
  destinationFilename?: string; //must be a string like XXXX[].[YYYYYY] without any path preceding
  copyPicker?: boolean; //present user with UI to choose destination directory to save a copy of download
  copyGallery?: boolean; //iOS only, if download has a recognized image/video file name extension, save a copy to iOS Photos, ignored on Android
  copyDownloads?: boolean; //Android only, adds a copy to device Downloads directory using legacy DIRECTORY_DOWNLOADS, or MediaStore for 29+
  notification?: boolean; //Android-only. Show system notification for download success/failure. defaults to false
}

对于两个平台，插件将尝试使用用户在选项中提供的文件名/路径下载文件，或尝试从 URL 中找到要使用的文件名。在任何情况下，如果输出路径的任何位置已存在要复制的文件，它将首先在文件名前附加 '-#' 以确保没有冲突。

Android 特定内容

Android 应用程序默认将文件下载到应用程序的缓存目录，这是 DownloadManager 支持的唯一目录，无需特殊权限。如果设备有 sd 卡，则此文件将对应于 android.content.Context.getExternalCacheDir()，如果没有，则对应于 android.content.Context.getCacheDir()。此文件可以在应用程序中直接用于其他目的，无需任何额外的权限/请求。

默认情况下，插件禁用了 Android 系统下载通知，这也要求您像这样将权限添加到 AndroidManifest.xml 中

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

您可以选择启用这些通知，这将显示用户的进度和完成/失败通知。

此插件的 Android 版本支持两种目标复制方法

copyPicker 首先将文件下载到默认缓存目录，然后向用户展示选择器 UI，以便他们选择希望保存副本的位置。这种方法避免了权限要求，因为用户参与了目标选择。
copyDownloads 将副本保存到设备的下载目录，以便用户可以从易于找到的位置使用该文件在其他应用程序中。API 版本 > 28 使用 MediaStore，不需要额外权限。对于 API 版本 28 以下的版本，您需要确保已使用以下方式在 AndroidManifest.xml 中定义了 Android 权限：

<manifest ... >
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

已在 Android API 25-33 上测试并通过。

iOS 特定内容

iOS 应用程序默认将文件下载到应用程序的文档目录，在 Nativescript 中定义为 knownFolders.documents()，不需要用户额外权限。这也有优点，即一旦配置为文档提供者，应用程序可以将下载的文件的位置对其他应用程序可见。

此插件的 iOS 版本支持两种目标副本方法

copyPicker 首先将文件下载到应用程序的文档目录，然后向用户展示选择器 UI，以便他们选择希望保存副本的位置。这种方法避免了权限要求，因为用户参与了目标选择。注意：此功能仅在 iOS 14+ 上可用
copyGallery 将副本保存到设备的照片库，以便用户可以从易于找到的位置使用该文件在其他应用程序中。此方法要求用户首先授予照片库权限，以便保存下载的文件。如果您的应用程序未提供关于为什么需要此权限的描述，可能会被 Apple App Store 拒绝。默认消息 "需要访问照片库。" 可能不足以满足 App Store 审查员的要求。您可以通过编辑应用程序中的 app/App_Resources/iOS/Info.plist 文件来自定义它，并添加如下内容
```
<key>NSPhotoLibraryUsageDescription</key>
<string>Requires access to save downloaded media to photo library.</string>
```

注意：如果在生产应用程序中使用 perms 插件，请首先阅读其 README.md，因为在生产应用程序中使用此插件将需要您添加所有 iOS Info.plist 权限字符串，以避免在自动处理过程中被拒绝，因为此插件包含所有权限类型的代码。

已在 iOS 12.x-16.x 上测试并通过，但要注意上述说明。

致谢

此插件受 https://github.com/tobydeh/nativescript-download-progress 的启发。

许可协议

Apache License Version 2.0