Référence des valeurs de retour

Tout ce qui est retourné par le hook useDropup.

Vue d'ensemble

const {
  files,          // Tableau d'objets fichiers
  state,          // État actuel
  actions,        // Actions disponibles
  getDropProps,   // Props pour la zone de dépôt
  getInputProps,  // Props pour l'élément input
  openFileDialog, // Ouvrir le sélecteur de fichiers
} = useDropup();

files

Tableau d'objets DropupFile représentant tous les fichiers ajoutés.

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 uniquement)
  console.log(file.uploadedUrl); // "https://..." (après téléversement)
  console.log(file.error);       // DropupError (si échec)
});

Propriétés DropupFile

Propriété	Type	Description
id	string	Identifiant unique
file	File	Objet File original du navigateur
name	string	Nom du fichier
size	number	Taille en octets
type	string	Type MIME
status	FileStatus	Statut actuel
progress	number	Progression du téléversement (0-100)
preview	string | undefined	URL d'aperçu pour les images
uploadedUrl	string | undefined	URL après téléversement réussi
response	unknown	Données de réponse du serveur
error	DropupError | undefined	Erreur si le téléversement a échoué
meta	Record<string, unknown>	Métadonnées personnalisées

Valeurs FileStatus

Statut	Description
'idle'	Fichier ajouté, pas en cours de téléversement
'uploading'	Téléversement en cours
'complete'	Téléversement réussi
'error'	Téléversement échoué
'paused'	Téléversement en pause (téléversements reprenables)

state

État actuel de la zone de dépôt.

const { state } = useDropup();

console.log(state.isDragging);   // true lors du glissement au-dessus
console.log(state.isDragAccept); // true lorsque les fichiers glissés sont valides
console.log(state.isDragReject); // true lorsque les fichiers glissés sont invalides
console.log(state.isUploading);  // true lorsqu'un fichier est en cours de téléversement
console.log(state.progress);     // progression globale 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

Propriétés d'état

Propriété	Type	Description
isDragging	boolean	Fichiers glissés au-dessus de la zone de dépôt
isDragAccept	boolean	Les fichiers glissés passent la validation
isDragReject	boolean	Les fichiers glissés échouent à la validation
isUploading	boolean	Un fichier actuellement en cours de téléversement
progress	number	Progression moyenne de tous les fichiers (0-100)
status	DropupStatus	Statut global du téléversement

Valeurs DropupStatus

Statut	Description
'idle'	Aucun téléversement en cours
'uploading'	Un ou plusieurs fichiers en cours de téléversement
'complete'	Tous les téléversements terminés avec succès
'error'	Un ou plusieurs téléversements ont échoué

actions

Objet contenant toutes les actions disponibles.

const { actions } = useDropup();

// Démarrer les téléversements
actions.upload();              // Téléverser tous les fichiers inactifs
actions.upload(['id1', 'id2']); // Téléverser des fichiers spécifiques

// Annuler les téléversements
actions.cancel();              // Annuler tous les téléversements
actions.cancel('file-id');     // Annuler un fichier spécifique

// Supprimer les fichiers
actions.remove('file-id');     // Supprimer un fichier spécifique
actions.reset();               // Supprimer tous les fichiers

// Réessayer les téléversements échoués
actions.retry();               // Réessayer tous les échecs
actions.retry(['id1']);        // Réessayer des fichiers spécifiques

// Ajouter des fichiers programmatiquement
actions.addFiles(fileList);    // Ajouter File[] ou FileList

// Mettre à jour les métadonnées du fichier
actions.updateFileMeta('file-id', { tag: 'important' });

Méthodes d'action

upload(fileIds?)

Démarrer le téléversement des fichiers.

// Téléverser tous les fichiers inactifs
actions.upload();

// Téléverser des fichiers spécifiques
actions.upload(['file-id-1', 'file-id-2']);

Paramètre	Type	Description
fileIds	string[] (optionnel)	IDs de fichiers spécifiques à téléverser

cancel(fileId?)

Annuler les téléversements en cours.

// Annuler tous les téléversements
actions.cancel();

// Annuler un fichier spécifique
actions.cancel('file-id');

Paramètre	Type	Description
fileId	string (optionnel)	ID de fichier spécifique à annuler

remove(fileId)

Supprimer un fichier de la liste.

actions.remove('file-id');

Paramètre	Type	Description
fileId	string	ID du fichier à supprimer

reset()

Supprimer tous les fichiers et réinitialiser l'état.

actions.reset();

retry(fileIds?)

Réessayer les téléversements échoués.

// Réessayer tous les téléversements échoués
actions.retry();

// Réessayer des fichiers spécifiques
actions.retry(['file-id-1']);

Paramètre	Type	Description
fileIds	string[] (optionnel)	IDs de fichiers spécifiques à réessayer

addFiles(files)

Ajouter des fichiers programmatiquement.

// Depuis le presse-papiers
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

// Depuis une autre source
actions.addFiles([file1, file2]);

Paramètre	Type	Description
files	File[] | FileList	Fichiers à ajouter

updateFileMeta(fileId, meta)

Mettre à jour les métadonnées du fichier.

actions.updateFileMeta('file-id', {
  description: 'Ma photo',
  tags: ['vacances', '2024'],
});

Paramètre	Type	Description
fileId	string	ID du fichier à mettre à jour
meta	Record<string, unknown>	Métadonnées à fusionner

getDropProps

Retourne les props à diffuser sur l'élément de la zone de dépôt.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  Déposer les fichiers ici
</div>

Avec des props personnalisées

<div
  {...getDropProps({
    className: 'my-dropzone',
    onClick: (e) => {
      // Votre gestionnaire de clic personnalisé
      console.log('Cliqué !');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Props retournées

Propriété	Type	Description
onDragEnter	function	Gestionnaire d'entrée de glissement
onDragOver	function	Gestionnaire de survol de glissement
onDragLeave	function	Gestionnaire de sortie de glissement
onDrop	function	Gestionnaire de dépôt
onClick	function	Gestionnaire de clic (ouvre le dialogue)
role	string	Rôle d'accessibilité
tabIndex	number	Index de tabulation pour le focus

getInputProps

Retourne les props à diffuser sur l'input de fichier caché.

const { getInputProps } = useDropup();

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

Avec des props personnalisées

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

Props retournées

Propriété	Type	Description
type	'file'	Type d'input
accept	string	Types de fichiers acceptés
multiple	boolean	Autoriser plusieurs fichiers
onChange	function	Gestionnaire de changement
style	object	Styles cachés

openFileDialog

Fonction pour ouvrir programmatiquement le sélecteur de fichiers.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Parcourir les fichiers
</button>

Exemples d'utilisation

Liste complète de fichiers

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

  return (
    <div>
      <h3>Fichiers ({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)} Ko</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])}>Réessayer</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>Supprimer</button>
        </div>
      ))}

      {state.isUploading && (
        <p>Téléversement en cours... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        Tout téléverser
      </button>

      <button onClick={() => actions.reset()}>
        Tout effacer
      </button>
    </div>
  );
}

Style d'état de glissement

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>Seules les images sont acceptées !</p>
      ) : (
        <p>Déposer les images ici</p>
      )}
    </div>
  );
}