Return Values Reference

ทุกอย่างที่ส่งคืนโดย useDropup hook

ภาพรวม

const {
  files,          // อาร์เรย์ของ file objects
  state,          // สถานะปัจจุบัน
  actions,        // actions ที่พร้อมใช้
  getDropProps,   // Props สำหรับ drop zone
  getInputProps,  // Props สำหรับ input element
  openFileDialog, // เปิด file picker
} = useDropup();

files

อาร์เรย์ของ DropupFile objects แทนไฟล์ทั้งหมดที่เพิ่ม

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://..." (รูปภาพเท่านั้น)
  console.log(file.uploadedUrl); // "https://..." (หลังอัปโหลด)
  console.log(file.error);       // DropupError (ถ้าล้มเหลว)
});

Properties ของ DropupFile

Property	ประเภท	คำอธิบาย
id	string	ตัวระบุเฉพาะ
file	File	File object ดั้งเดิมของเบราว์เซอร์
name	string	ชื่อไฟล์
size	number	ขนาดเป็นไบต์
type	string	MIME type
status	FileStatus	สถานะปัจจุบัน
progress	number	ความคืบหน้าการอัปโหลด (0-100)
preview	string | undefined	Preview URL สำหรับรูปภาพ
uploadedUrl	string | undefined	URL หลังอัปโหลดสำเร็จ
response	unknown	ข้อมูลตอบกลับจากเซิร์ฟเวอร์
error	DropupError | undefined	ข้อผิดพลาดถ้าอัปโหลดล้มเหลว
meta	Record<string, unknown>	Metadata ที่กำหนดเอง

ค่า FileStatus

สถานะ	คำอธิบาย
'idle'	เพิ่มไฟล์แล้ว ยังไม่อัปโหลด
'uploading'	กำลังอัปโหลด
'complete'	อัปโหลดสำเร็จ
'error'	อัปโหลดล้มเหลว
'paused'	หยุดการอัปโหลดชั่วคราว (การอัปโหลดแบบ resumable)

state

สถานะปัจจุบันของ dropzone

const { state } = useDropup();

console.log(state.isDragging);   // true เมื่อลากอยู่เหนือ
console.log(state.isDragAccept); // true เมื่อไฟล์ที่ลากผ่านการตรวจสอบ
console.log(state.isDragReject); // true เมื่อไฟล์ที่ลากไม่ผ่านการตรวจสอบ
console.log(state.isUploading);  // true เมื่อมีไฟล์กำลังอัปโหลด
console.log(state.progress);     // ความคืบหน้าโดยรวม 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

Properties ของ State

Property	ประเภท	คำอธิบาย
isDragging	boolean	กำลังลากไฟล์อยู่เหนือ drop zone
isDragAccept	boolean	ไฟล์ที่ลากผ่านการตรวจสอบ
isDragReject	boolean	ไฟล์ที่ลากไม่ผ่านการตรวจสอบ
isUploading	boolean	มีไฟล์กำลังอัปโหลดอยู่
progress	number	ความคืบหน้าเฉลี่ยของไฟล์ทั้งหมด (0-100)
status	DropupStatus	สถานะการอัปโหลดโดยรวม

ค่า DropupStatus

สถานะ	คำอธิบาย
'idle'	ไม่มีการอัปโหลด
'uploading'	มีไฟล์หนึ่งหรือหลายไฟล์กำลังอัปโหลด
'complete'	การอัปโหลดทั้งหมดเสร็จสำเร็จ
'error'	มีการอัปโหลดหนึ่งหรือหลายรายการล้มเหลว

actions

Object ที่มี actions ทั้งหมดที่พร้อมใช้

const { actions } = useDropup();

// เริ่มอัปโหลด
actions.upload();              // อัปโหลดไฟล์ idle ทั้งหมด
actions.upload(['id1', 'id2']); // อัปโหลดไฟล์ที่ระบุ

// ยกเลิกการอัปโหลด
actions.cancel();              // ยกเลิกการอัปโหลดทั้งหมด
actions.cancel('file-id');     // ยกเลิกไฟล์ที่ระบุ

// ลบไฟล์
actions.remove('file-id');     // ลบไฟล์ที่ระบุ
actions.reset();               // ลบไฟล์ทั้งหมด

// ลองใหม่การอัปโหลดที่ล้มเหลว
actions.retry();               // ลองใหม่ทั้งหมดที่ล้มเหลว
actions.retry(['id1']);        // ลองใหม่ไฟล์ที่ระบุ

// เพิ่มไฟล์แบบ programmatic
actions.addFiles(fileList);    // เพิ่ม File[] หรือ FileList

// อัปเดต metadata ของไฟล์
actions.updateFileMeta('file-id', { tag: 'important' });

Action Methods

upload(fileIds?)

เริ่มอัปโหลดไฟล์

// อัปโหลดไฟล์ idle ทั้งหมด
actions.upload();

// อัปโหลดไฟล์ที่ระบุ
actions.upload(['file-id-1', 'file-id-2']);

พารามิเตอร์	ประเภท	คำอธิบาย
fileIds	string[] (ไม่บังคับ)	ID ไฟล์ที่จะอัปโหลด

cancel(fileId?)

ยกเลิกการอัปโหลดที่กำลังดำเนินการ

// ยกเลิกการอัปโหลดทั้งหมด
actions.cancel();

// ยกเลิกไฟล์ที่ระบุ
actions.cancel('file-id');

พารามิเตอร์	ประเภท	คำอธิบาย
fileId	string (ไม่บังคับ)	ID ไฟล์ที่จะยกเลิก

remove(fileId)

ลบไฟล์ออกจากรายการ

actions.remove('file-id');

พารามิเตอร์	ประเภท	คำอธิบาย
fileId	string	ID ไฟล์ที่จะลบ

reset()

ลบไฟล์ทั้งหมดและรีเซ็ต state

actions.reset();

retry(fileIds?)

ลองใหม่การอัปโหลดที่ล้มเหลว

// ลองใหม่การอัปโหลดที่ล้มเหลวทั้งหมด
actions.retry();

// ลองใหม่ไฟล์ที่ระบุ
actions.retry(['file-id-1']);

พารามิเตอร์	ประเภท	คำอธิบาย
fileIds	string[] (ไม่บังคับ)	ID ไฟล์ที่จะลองใหม่

addFiles(files)

เพิ่มไฟล์แบบ programmatic

// จาก clipboard
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

// จากแหล่งอื่น
actions.addFiles([file1, file2]);

พารามิเตอร์	ประเภท	คำอธิบาย
files	File[] | FileList	ไฟล์ที่จะเพิ่ม

updateFileMeta(fileId, meta)

อัปเดต metadata ของไฟล์

actions.updateFileMeta('file-id', {
  description: 'รูปถ่ายของฉัน',
  tags: ['vacation', '2024'],
});

พารามิเตอร์	ประเภท	คำอธิบาย
fileId	string	ID ไฟล์ที่จะอัปเดต
meta	Record<string, unknown>	Metadata ที่จะรวม

getDropProps

ส่งคืน props ที่จะ spread บน drop zone element

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  วางไฟล์ที่นี่
</div>

พร้อม Props ที่กำหนดเอง

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // Click handler ที่กำหนดเองของคุณ
      console.log('คลิกแล้ว!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Props ที่ส่งคืน

Property	ประเภท	คำอธิบาย
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	Tab index สำหรับ focus

getInputProps

ส่งคืน props ที่จะ spread บน hidden file input

const { getInputProps } = useDropup();

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

พร้อม Props ที่กำหนดเอง

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

Props ที่ส่งคืน

Property	ประเภท	คำอธิบาย
type	'file'	ประเภท input
accept	string	ประเภทไฟล์ที่ยอมรับ
multiple	boolean	อนุญาตหลายไฟล์
onChange	function	Change handler
style	object	Styles ที่ซ่อน

openFileDialog

ฟังก์ชันเปิด file picker แบบ programmatic

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  เรียกดูไฟล์
</button>

ตัวอย่างการใช้งาน

รายการไฟล์แบบสมบูรณ์

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}
      >
        อัปโหลดทั้งหมด
      </button>

      <button onClick={() => actions.reset()}>
        ล้างทั้งหมด
      </button>
    </div>
  );
}

การจัดสไตล์ Drag State

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>ยอมรับเฉพาะรูปภาพเท่านั้น!</p>
      ) : (
        <p>วางรูปภาพที่นี่</p>
      )}
    </div>
  );
}