跳转到内容
Capgo

Getting Started

此内容尚不支持你的语言。

Installation

Terminal window
npm install @capgo/capacitor-downloader
npx cap sync

Usage Example

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


// Start a download
const downloadId = 'my-download-001';
await CapacitorDownloader.download({
  id: downloadId,
  url: 'https://example.com/large-file.zip',
  destination: '/downloads/large-file.zip',
  headers: {
    'Authorization': 'Bearer token123'
  },
  network: 'wifi-only',
  priority: 'high'
});


// Listen for progress updates
CapacitorDownloader.addListener('downloadProgress', (data) => {
  console.log(`Download ${data.id}: ${data.progress}% complete`);
  console.log(`Downloaded: ${data.bytesDownloaded}/${data.totalBytes} bytes`);
});


// Handle completion
CapacitorDownloader.addListener('downloadCompleted', (data) => {
  console.log(`Download completed: ${data.id}`);
  console.log(`File saved to: ${data.path}`);
});


// Handle errors
CapacitorDownloader.addListener('downloadFailed', (error) => {
  console.error(`Download failed: ${error.id}`, error.message);
});


// Pause a download
await CapacitorDownloader.pause(downloadId);


// Resume the download
await CapacitorDownloader.resume(downloadId);


// Check download status
const status = await CapacitorDownloader.checkStatus(downloadId);
console.log('Download status:', status);


// Stop the download
await CapacitorDownloader.stop(downloadId);

Core API Methods

Download Management

  • download(options) - Start a new file download
  • pause(id) - Pause an ongoing download
  • resume(id) - Resume a paused download
  • stop(id) - Stop and cancel a download
  • checkStatus(id) - Get current download status

File Operations

  • getFileInfo(path) - Retrieve file information and metadata

Download Configuration

interface DownloadOptions {
  id: string;                    // Unique download identifier
  url: string;                   // Download source URL
  destination: string;           // Local save path
  headers?: Record<string, string>; // Custom HTTP headers
  network?: 'cellular' | 'wifi-only'; // Network restrictions
  priority?: 'high' | 'normal' | 'low'; // Download priority
}

Event Listeners

The plugin provides comprehensive event handling:

  • downloadProgress - Track real-time download progress
  • downloadCompleted - Handle successful download completion
  • downloadFailed - Handle download errors and failures

Network Configuration

WiFi-Only Downloads

await CapacitorDownloader.download({
  id: 'large-file',
  url: 'https://example.com/video.mp4',
  destination: '/downloads/video.mp4',
  network: 'wifi-only' // Restricts to WiFi networks only
});

Priority Management

// High priority download
await CapacitorDownloader.download({
  id: 'urgent-update',
  url: 'https://example.com/update.zip',
  destination: '/downloads/update.zip',
  priority: 'high'
});

Download States

Downloads can be in various states:

  • Pending: Queued for download
  • Running: Currently downloading
  • Paused: Temporarily stopped
  • Completed: Successfully finished
  • Failed: Encountered an error
  • Stopped: Manually cancelled

File Information

// Get file details
const fileInfo = await CapacitorDownloader.getFileInfo('/downloads/my-file.pdf');
console.log('File size:', fileInfo.size);
console.log('Last modified:', fileInfo.lastModified);
console.log('MIME type:', fileInfo.mimeType);

Best Practices

  • Use unique download IDs to avoid conflicts
  • Implement proper error handling for network failures
  • Consider storage space before starting large downloads
  • Use WiFi-only mode for large files to preserve mobile data
  • Clean up completed downloads to manage storage