快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-downloader` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-downloader
bunx cap sync

导入

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

快速入门

下载到指定文件夹，监听进度，并在支持的情况下于应用重启后恢复下载。

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

const progressListener = await CapacitorDownloader.addListener('downloadProgress', (event) => {
  if (event.id === 'offline-pack') {
    console.log(event.progress);
  }
});

const task = await CapacitorDownloader.download({
  id: 'offline-pack',
  url: 'https://cdn.example.com/large-pack.zip',
  destination: 'downloads/offline-pack.zip',
});

示例：暂停与恢复

await CapacitorDownloader.pause({ id: 'offline-pack' });
await CapacitorDownloader.resume({ id: 'offline-pack' });

示例：检查已完成的文件

import { Capacitor } from '@capacitor/core';
import { Directory, Filesystem } from '@capacitor/filesystem';

const relativePath = 'downloads/offline-pack.zip';
const path =
  Capacitor.getPlatform() === 'ios'
    ? (await Filesystem.getUri({ directory: Directory.Documents, path: relativePath })).uri
    : relativePath;

const info = await CapacitorDownloader.getFileInfo({ path });

常见坑点

• 存储目标: 选择一个 destination 您的应用可以在各平台上读取。
• 后台运行: 下载任务在 iOS 和 Android 上可在后台运行。在 Web 端， download() 尚未实现；请改用浏览器下载流程。
• 状态：使用 checkStatus 在应用进程仍存活期间。在 iOS 上，重启后任务 ID 不会恢复。

API 概览

download

启动一个新的下载任务。

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

const task = await CapacitorDownloader.download({
  id: 'my-download',
  url: 'https://example.com/file.pdf',
  destination: 'downloads/file.pdf'
});

pause

暂停正在进行的下载。 之后可以从同一位置恢复下载。

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

await CapacitorDownloader.pause({ id: 'id-123' });

resume

恢复暂停的下载。 从暂停处继续下载。

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

await CapacitorDownloader.resume({ id: 'id-123' });

stop

停止并永久取消下载。 已下载的数据将被删除。

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

await CapacitorDownloader.stop({ id: 'id-123' });

checkStatus

检查当前下载状态。

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

const result = await CapacitorDownloader.checkStatus({ id: 'id-123' });
console.log(result);

getFileInfo

获取已下载文件的信息。

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

const result = await CapacitorDownloader.getFileInfo({ path: 'path/to/file' });
console.log(result);

类型参考

DownloadOptions

用于启动下载的配置选项。

export interface DownloadOptions {
  /** Unique identifier for this download task */
  id: string;
  /** URL of the file to download */
  url: string;
  /** Local file path where the download will be saved */
  destination: string;
  /** Optional HTTP headers to include in the request */
  headers?: { [key: string]: string };
  /** Network type requirement for download */
  network?: 'cellular' | 'wifi-only';
  /** Download priority level */
  priority?: 'high' | 'normal' | 'low';
}

DownloadTask

表示下载任务的当前状态和进度。

export interface DownloadTask {
  /** Unique identifier for the download task */
  id: string;
  /** Download progress from 0 to 100 */
  progress: number;
  /** Current state of the download */
  state: 'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR';
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划 dashboard 和 API 操作，请将其连接到 使用 @capgo/capacitor-downloader 用于“使用 @capgo/capacitor-downloader”中的原生能力， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。