Return Values Reference

useDropup hook මගින් return වන සියල්ල.

දළ විසඳුම

const {
  files,          // ගොනු objects array
  state,          // වත්මන් state
  actions,        // ලබා ගත හැකි actions
  getDropProps,   // Drop zone සඳහා props
  getInputProps,  // Input element සඳහා props
  openFileDialog, // File picker විවෘත කරන්න
} = useDropup();

files

එකතු කළ සියලුම ගොනු නියෝජනය කරන DropupFile objects array.

const { files } = useDropup();

files.forEach(file => {
  console.log(file.id);          // "abc123"
  console.log(file.name);        // "photo.jpg"
  console.log(file.size);        // 1234567
  console.log(file.type);        // "image/jpeg"
  console.log(file.status);      // "idle" | "uploading" | "complete" | "error"
  console.log(file.progress);    // 0-100
  console.log(file.preview);     // "blob:http://..." (images පමණි)
  console.log(file.uploadedUrl); // "https://..." (upload පසුව)
  console.log(file.error);       // DropupError (අසාර්ථක නම්)
});

DropupFile Properties

Property	Type	විස්තරය
id	string	අනන්‍ය හඳුනාගැනීම
file	File	මුල් browser File object
name	string	ගොනු නාමය
size	number	Bytes වලින් ප්‍රමාණය
type	string	MIME type
status	FileStatus	වත්මන් status
progress	number	Upload progress (0-100)
preview	string | undefined	Images සඳහා Preview URL
uploadedUrl	string | undefined	සාර්ථක upload පසු URL
response	unknown	Server response data
error	DropupError | undefined	Upload අසාර්ථක නම් Error
meta	Record<string, unknown>	Custom metadata

FileStatus අගයන්

Status	විස්තරය
'idle'	ගොනුව එකතු විය, upload නැත
'uploading'	Upload සිදුවෙමින්
'complete'	Upload සාර්ථකයි
'error'	Upload අසාර්ථකයි
'paused'	Upload විරාම කළා (resumable uploads)

state

Dropzone හි වත්මන් state.

const { state } = useDropup();

console.log(state.isDragging);   // drag වෙමින් ඇති විට true
console.log(state.isDragAccept); // drag කළ ගොනු වලංගු විට true
console.log(state.isDragReject); // drag කළ ගොනු අවලංගු විට true
console.log(state.isUploading);  // ගොනු upload වෙමින් ඇති විට true
console.log(state.progress);     // සමස්ත progress 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

State Properties

Property	Type	විස්තරය
isDragging	boolean	Drop zone උඩින් ගොනු drag වෙමින්
isDragAccept	boolean	Drag කළ ගොනු validation pass කරයි
isDragReject	boolean	Drag කළ ගොනු validation fail කරයි
isUploading	boolean	ගොනුවක් upload වෙමින්
progress	number	සියලුම ගොනුවල සාමාන්‍ය progress (0-100)
status	DropupStatus	සමස්ත upload status

DropupStatus අගයන්

Status	විස්තරය
'idle'	Uploads සිදුවෙමින් නැත
'uploading'	එකක් හෝ වැඩි ගොනු upload වෙමින්
'complete'	සියලුම uploads සාර්ථකව අවසන්
'error'	එකක් හෝ වැඩි uploads අසාර්ථක

actions

ලබා ගත හැකි සියලුම actions අඩංගු object.

const { actions } = useDropup();

// Uploads ආරම්භ කරන්න
actions.upload();              // සියලුම idle ගොනු upload කරන්න
actions.upload(['id1', 'id2']); // නිශ්චිත ගොනු upload කරන්න

// Uploads අවලංගු කරන්න
actions.cancel();              // සියලුම uploads අවලංගු කරන්න
actions.cancel('file-id');     // නිශ්චිත ගොනුව අවලංගු කරන්න

// ගොනු ඉවත් කරන්න
actions.remove('file-id');     // නිශ්චිත ගොනුව ඉවත් කරන්න
actions.reset();               // සියලුම ගොනු ඉවත් කරන්න

// අසාර්ථක uploads නැවත උත්සාහ කරන්න
actions.retry();               // අසාර්ථක සියල්ල නැවත උත්සාහ කරන්න
actions.retry(['id1']);        // නිශ්චිත ගොනු නැවත උත්සාහ කරන්න

// Programmatically ගොනු එකතු කරන්න
actions.addFiles(fileList);    // File[] හෝ FileList එකතු කරන්න

// File metadata යාවත්කාලීන කරන්න
actions.updateFileMeta('file-id', { tag: 'important' });

Action Methods

upload(fileIds?)

ගොනු upload ආරම්භ කරන්න.

// සියලුම idle ගොනු upload කරන්න
actions.upload();

// නිශ්චිත ගොනු upload කරන්න
actions.upload(['file-id-1', 'file-id-2']);

Parameter	Type	විස්තරය
fileIds	string[] (විකල්ප)	Upload කළ යුතු නිශ්චිත file IDs

cancel(fileId?)

සිදුවෙමින් පවතින uploads අවලංගු කරන්න.

// සියලුම uploads අවලංගු කරන්න
actions.cancel();

// නිශ්චිත ගොනුව අවලංගු කරන්න
actions.cancel('file-id');

Parameter	Type	විස්තරය
fileId	string (විකල්ප)	අවලංගු කළ යුතු නිශ්චිත file ID

remove(fileId)

ලැයිස්තුවෙන් ගොනුවක් ඉවත් කරන්න.

actions.remove('file-id');

Parameter	Type	විස්තරය
fileId	string	ඉවත් කළ යුතු File ID

reset()

සියලුම ගොනු ඉවත් කර state reset කරන්න.

actions.reset();

retry(fileIds?)

අසාර්ථක uploads නැවත උත්සාහ කරන්න.

// අසාර්ථක සියල්ල නැවත උත්සාහ කරන්න
actions.retry();

// නිශ්චිත ගොනු නැවත උත්සාහ කරන්න
actions.retry(['file-id-1']);

Parameter	Type	විස්තරය
fileIds	string[] (විකල්ප)	නැවත උත්සාහ කළ යුතු නිශ්චිත file IDs

addFiles(files)

Programmatically ගොනු එකතු කරන්න.

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

// වෙනත් මූලාශ්‍රයකින්
actions.addFiles([file1, file2]);

Parameter	Type	විස්තරය
files	File[] | FileList	එකතු කළ යුතු ගොනු

updateFileMeta(fileId, meta)

File metadata යාවත්කාලීන කරන්න.

actions.updateFileMeta('file-id', {
  description: 'මගේ ඡායාරූපය',
  tags: ['නිවාඩු', '2024'],
});

Parameter	Type	විස්තරය
fileId	string	යාවත්කාලීන කළ යුතු File ID
meta	Record<string, unknown>	ඒකාබද්ධ කළ යුතු Metadata

getDropProps

Drop zone element එක මත spread කළ යුතු props return කරයි.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  ගොනු මෙතැනට දමන්න
</div>

Custom Props සමඟ

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // ඔබගේ custom click handler
      console.log('Click විය!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Returned Props

Property	Type	විස්තරය
onDragEnter	function	Drag enter handler
onDragOver	function	Drag over handler
onDragLeave	function	Drag leave handler
onDrop	function	Drop handler
onClick	function	Click handler (dialog විවෘත කරයි)
role	string	Accessibility role
tabIndex	number	Focus සඳහා tab index

getInputProps

සැඟවුණු file input මත spread කළ යුතු props return කරයි.

const { getInputProps } = useDropup();

<input {...getInputProps()} />

Custom Props සමඟ

<input
  {...getInputProps({
    id: 'file-input',
    name: 'files',
  })}
/>

Returned Props

Property	Type	විස්තරය
type	'file'	Input type
accept	string	පිළිගන්නා ගොනු වර්ග
multiple	boolean	බහු ගොනු අවසර දෙන්න
onChange	function	Change handler
style	object	සැඟවීමේ styles

openFileDialog

File picker programmatically විවෘත කිරීමේ function.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  ගොනු Browse කරන්න
</button>

භාවිත උදාහරණ

සම්පූර්ණ File List

function FileList() {
  const { files, actions, state } = useDropup({
    upload: { url: '/api/upload' },
  });

  return (
    <div>
      <h3>ගොනු ({files.length})</h3>

      {files.map(file => (
        <div key={file.id}>
          {file.preview && (
            <img src={file.preview} alt="" width={50} />
          )}
          <span>{file.name}</span>
          <span>{(file.size / 1024).toFixed(1)} KB</span>
          <span>{file.status}</span>

          {file.status === 'uploading' && (
            <progress value={file.progress} max={100} />
          )}

          {file.status === 'error' && (
            <>
              <span style={{ color: 'red' }}>{file.error?.message}</span>
              <button onClick={() => actions.retry([file.id])}>නැවත උත්සාහ</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>ඉවත් කරන්න</button>
        </div>
      ))}

      {state.isUploading && (
        <p>උඩුගත වෙමින්... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        සියල්ල Upload කරන්න
      </button>

      <button onClick={() => actions.reset()}>
        සියල්ල හිස් කරන්න
      </button>
    </div>
  );
}

Drag State Styling

function StyledDropzone() {
  const { state, getDropProps, getInputProps } = useDropup({
    accept: 'image/*',
  });

  const getStyle = () => {
    if (state.isDragAccept) return { borderColor: 'green', backgroundColor: '#e8f5e9' };
    if (state.isDragReject) return { borderColor: 'red', backgroundColor: '#ffebee' };
    if (state.isDragging) return { borderColor: 'blue', backgroundColor: '#e3f2fd' };
    return { borderColor: 'gray', backgroundColor: 'white' };
  };

  return (
    <div
      {...getDropProps()}
      style={{
        border: '2px dashed',
        borderRadius: 8,
        padding: 40,
        textAlign: 'center',
        transition: 'all 0.2s',
        ...getStyle(),
      }}
    >
      <input {...getInputProps()} />
      {state.isDragReject ? (
        <p>Images පමණක් පිළිගනී!</p>
      ) : (
        <p>Images මෙතැනට දමන්න</p>
      )}
    </div>
  );
}