ගොනු හැසිරවීම

ගොනු තෝරාගත් මොහොතේ සිට upload වන තුරු Dropup සුමට අත්දැකීමක් ලබා දෙයි.

ගොනු තේරීමේ ක්‍රම

Drag and Drop

ඕනෑම element එකක drag-and-drop සක්‍රීය කිරීමට getDropProps() භාවිතා කරන්න:

function DropZone() {
  const { getDropProps, getInputProps, state } = useDropup();

  return (
    <div
      {...getDropProps()}
      style={{
        border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
        backgroundColor: state.isDragging ? '#f0f8ff' : 'transparent',
      }}
    >
      <input {...getInputProps()} />
      <p>ගොනු මෙතැනට ඇද දමන්න</p>
    </div>
  );
}

Click කර තේරීම

Drop zone පෙරනිමියෙන් click කළ හැකියි:

<div {...getDropProps()}>
  <input {...getInputProps()} />
  <p>ගොනු මෙතැනට ඇද දමන්න හෝ click කරන්න</p>
</div>

Programmatic තේරීම

File dialog programmatically විවෘත කරන්න:

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  ගොනු තෝරන්න
</button>

Programmatic ගොනු එකතු කිරීම

ගොනු කෙලින්ම එකතු කරන්න (paste events හෝ integrations සඳහා ප්‍රයෝජනවත්):

const { actions } = useDropup();

// Clipboard එකෙන්
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files?.length) {
    actions.addFiles(files);
  }
});

File Object ව්‍යුහය

files array එකේ සෑම ගොනුවකම මෙම ව්‍යුහය ඇත:

interface DropupFile {
  // හඳුනාගැනීම
  id: string;              // අනන්‍ය හඳුනාගැනීම (ස්වයංක්‍රීයව සාදයි)
  file: File;              // මුල් browser File object

  // Metadata
  name: string;            // ගොනු නාමය
  size: number;            // Bytes වලින් ප්‍රමාණය
  type: string;            // MIME type (උදා., "image/png")

  // Preview (images සඳහා)
  preview?: string;        // Preview සඳහා Object URL

  // Upload State
  status: FileStatus;      // 'idle' | 'uploading' | 'complete' | 'error' | 'paused'
  progress: number;        // 0-100

  // ප්‍රතිඵල
  uploadedUrl?: string;    // සාර්ථක upload එකෙන් පසු URL
  response?: unknown;      // Server response
  error?: DropupError;     // අසාර්ථක නම් error විස්තර

  // Custom data
  meta?: Record<string, unknown>;
}

File Status Lifecycle

idle → uploading → complete
                 ↘ error → (retry) → uploading
                 ↘ paused → (resume) → uploading

Status අගයන්

Status	විස්තරය
idle	ගොනුව එකතු වූ නමුත් upload තවම නැත
uploading	දැනට upload වෙමින් පවතී
complete	Upload සාර්ථකයි
error	Upload අසාර්ථකයි
paused	Upload විරාම කර ඇත (resumable uploads සඳහා)

ගොනු සමඟ වැඩ කිරීම

ගොනු වෙත ප්‍රවේශය

const { files } = useDropup();

// සියලුම ගොනු
console.log(files);

// Status අනුව filter කරන්න
const uploading = files.filter(f => f.status === 'uploading');
const completed = files.filter(f => f.status === 'complete');
const failed = files.filter(f => f.status === 'error');

ගොනු ඉවත් කිරීම

const { files, actions } = useDropup();

// එක ගොනුවක් ඉවත් කරන්න
actions.remove(files[0].id);

// සියලුම ගොනු ඉවත් කරන්න
actions.reset();

File Metadata යාවත්කාලීන කිරීම

const { actions } = useDropup();

// Custom metadata එකතු කරන්න
actions.updateFileMeta(fileId, {
  customField: 'value',
  category: 'documents',
});

File Previews

Image ගොනු සඳහා, Dropup preview URLs සාදා ගත හැක:

const { files } = useDropup({
  generatePreviews: true, // පෙරනිමි: true
});

// ඔබගේ UI හි preview භාවිතා කරන්න
{files.map(file => (
  file.preview && (
    <img
      src={file.preview}
      alt={file.name}
      style={{ maxWidth: 100, maxHeight: 100 }}
    />
  )
))}

Memory Management

Preview URLs යනු memory භාවිතා කරන Object URLs ය. ගොනු ඉවත් කළ විට හෝ component unmount වන විට Dropup ස්වයංක්‍රීයව ඒවා revoke කරයි.

File Size Formatting

ගොනු ප්‍රමාණ පෙන්වීමට helper:

function formatFileSize(bytes: number): string {
  if (bytes === 0) return '0 Bytes';
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
}

// භාවිතය
{files.map(file => (
  <span>{formatFileSize(file.size)}</span>
))}

විශාල ගොනු හැසිරවීම

විශාල ගොනු සඳහා, chunked uploads සලකා බලන්න:

import { useDropup, createChunkedUploader } from '@samithahansaka/dropup';

const { files } = useDropup({
  upload: createChunkedUploader({
    url: '/api/upload',
    chunkSize: 5 * 1024 * 1024, // 5MB chunks
  }),
});

වැඩි විස්තර සඳහා Chunked Uploads බලන්න.