戻り値リファレンス

useDropupフックが返すすべての値。

概要

const {
  files,          // ファイルオブジェクトの配列
  state,          // 現在の状態
  actions,        // 利用可能なアクション
  getDropProps,   // ドロップゾーン用のprops
  getInputProps,  // input要素用のprops
  openFileDialog, // ファイルピッカーを開く
} = useDropup();

files

追加されたすべてのファイルを表すDropupFileオブジェクトの配列。

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 (失敗時)
});

DropupFileプロパティ

プロパティ	タイプ	説明
`id`	`string`	一意の識別子
`file`	`File`	元のブラウザFileオブジェクト
`name`	`string`	ファイル名
`size`	`number`	バイト単位のサイズ
`type`	`string`	MIMEタイプ
`status`	`FileStatus`	現在のステータス
`progress`	`number`	アップロード進捗（0-100）
`preview`	`string \| undefined`	画像のプレビューURL
`uploadedUrl`	`string \| undefined`	アップロード成功後のURL
`response`	`unknown`	サーバーレスポンスデータ
`error`	`DropupError \| undefined`	アップロード失敗時のエラー
`meta`	`Record<string, unknown>`	カスタムメタデータ

FileStatus値

ステータス	説明
`'idle'`	ファイル追加済み、未アップロード
`'uploading'`	アップロード中
`'complete'`	アップロード成功
`'error'`	アップロード失敗
`'paused'`	アップロード一時停止（再開可能なアップロード）

state

ドロップゾーンの現在の状態。

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'

Stateプロパティ

プロパティ	タイプ	説明
`isDragging`	`boolean`	ファイルがドロップゾーン上でドラッグされている
`isDragAccept`	`boolean`	ドラッグされたファイルが検証を通過
`isDragReject`	`boolean`	ドラッグされたファイルが検証に失敗
`isUploading`	`boolean`	いずれかのファイルが現在アップロード中
`progress`	`number`	すべてのファイルの平均進捗（0-100）
`status`	`DropupStatus`	全体のアップロードステータス

DropupStatus値

ステータス	説明
`'idle'`	アップロード進行中なし
`'uploading'`	1つ以上のファイルをアップロード中
`'complete'`	すべてのアップロードが正常に完了
`'error'`	1つ以上のアップロードが失敗

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']);        // 特定のファイルを再試行

// プログラムでファイルを追加
actions.addFiles(fileList);    // File[]またはFileListを追加

// ファイルメタデータを更新
actions.updateFileMeta('file-id', { tag: 'important' });

アクションメソッド

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()

すべてのファイルを削除して状態をリセット。

actions.reset();

retry(fileIds?)

失敗したアップロードを再試行。

// すべての失敗したアップロードを再試行
actions.retry();

// 特定のファイルを再試行
actions.retry(['file-id-1']);

パラメータ	タイプ	説明
`fileIds`	`string[]`（オプション）	再試行する特定のファイルID

addFiles(files)

プログラムでファイルを追加。

// クリップボードから
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

// 別のソースから
actions.addFiles([file1, file2]);

パラメータ	タイプ	説明
`files`	`File[] \| FileList`	追加するファイル

updateFileMeta(fileId, meta)

ファイルメタデータを更新。

actions.updateFileMeta('file-id', {
  description: '私の写真',
  tags: ['vacation', '2024'],
});

パラメータ	タイプ	説明
`fileId`	`string`	更新するファイルID
`meta`	`Record<string, unknown>`	マージするメタデータ

getDropProps

ドロップゾーン要素にスプレッドするpropsを返します。

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  ここにファイルをドロップ
</div>

カスタムPropsと共に

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // カスタムクリックハンドラー
      console.log('クリックされました！');
    },
  })}
>
  <input {...getInputProps()} />
</div>

返されるProps

プロパティ	タイプ	説明
`onDragEnter`	`function`	ドラッグエンターハンドラー
`onDragOver`	`function`	ドラッグオーバーハンドラー
`onDragLeave`	`function`	ドラッグリーブハンドラー
`onDrop`	`function`	ドロップハンドラー
`onClick`	`function`	クリックハンドラー（ダイアログを開く）
`role`	`string`	アクセシビリティロール
`tabIndex`	`number`	フォーカス用のタブインデックス

getInputProps

非表示のファイル入力にスプレッドするpropsを返します。

const { getInputProps } = useDropup();

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

カスタムPropsと共に

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

返されるProps

プロパティ	タイプ	説明
`type`	`'file'`	入力タイプ
`accept`	`string`	受け入れるファイルタイプ
`multiple`	`boolean`	複数ファイルを許可
`onChange`	`function`	変更ハンドラー
`style`	`object`	非表示スタイル

openFileDialog

プログラムでファイルピッカーを開く関数。

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>
  );
}

ドラッグ状態のスタイリング

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>
  );
}

概要​

files​

DropupFileプロパティ​

FileStatus値​

state​

Stateプロパティ​

DropupStatus値​

actions​

アクションメソッド​

upload(fileIds?)​

cancel(fileId?)​

remove(fileId)​

reset()​

retry(fileIds?)​

addFiles(files)​

updateFileMeta(fileId, meta)​

getDropProps​

カスタムPropsと共に​

返されるProps​

getInputProps​

カスタムPropsと共に​

返されるProps​

openFileDialog​

使用例​

完全なファイルリスト​

ドラッグ状態のスタイリング​

概要

files

DropupFileプロパティ

FileStatus値

state

Stateプロパティ

DropupStatus値

actions

アクションメソッド

upload(fileIds?)

cancel(fileId?)

remove(fileId)

reset()

retry(fileIds?)

addFiles(files)

updateFileMeta(fileId, meta)

getDropProps

カスタムPropsと共に

返されるProps

getInputProps

カスタムPropsと共に

返されるProps

openFileDialog

使用例

完全なファイルリスト

ドラッグ状態のスタイリング