Window : méthode showOpenFilePicker()

Syntaxe

showOpenFilePicker()
showOpenFilePicker(options)

Paramètres

options Facultatif

Un objet contenant des options, qui sont les suivantes :

excludeAcceptAllOption Facultatif

Une valeur booléenne qui vaut par défaut false. Par défaut, le sélecteur doit inclure une option pour ne pas appliquer de filtres de type de fichier (instiguée avec l'option type ci-dessous). Définir cette option sur true signifie que cette option n'est pas disponible.

id Facultatif

En définissant un identifiant, le navigateur peut se souvenir de différents répertoires pour différents identifiants. Si le même identifiant est utilisé pour un autre sélecteur, le sélecteur s'ouvre dans le même répertoire.

multiple Facultatif

Une valeur booléenne qui vaut par défaut false. Lorsqu'elle est définie sur true, plusieurs fichiers peuvent être sélectionnés.

startIn Facultatif

Un objet FileSystemHandle ou un répertoire bien connu ("desktop", "documents", "downloads", "music", "pictures" ou "videos") pour ouvrir la boîte de dialogue dans ce répertoire.

types Facultatif

Un tableau (Array) des types de fichiers autorisés à sélectionner. Chaque élément est un objet avec les options suivantes :

description Facultatif

Une description optionnelle de la catégorie de types de fichiers autorisés. Par défaut, une chaîne de caractères vide.

accept

Un Object dont les clés sont définies sur le type MIME et les valeurs un tableau (Array) d'extensions de fichiers (voir ci-dessous pour un exemple).

Valeur de retour

Une promesse (Promise) dont le gestionnaire de complétion reçoit un tableau (Array) d'objets FileSystemFileHandle.

Exceptions

AbortError DOMException

Levée si l'utilisateur·ice ferme l'invite sans faire de sélection, ou si l'agent utilisateur juge que les fichiers sélectionnés sont trop sensibles ou dangereux.

SecurityError DOMException

Levée si l'appel a été bloqué par la politique de même origine ou s'il n'a pas été effectué par une interaction utilisateur·ice telle qu'un clic sur un bouton.

TypeError

Levée si les types acceptés ne peuvent pas être traités, ce qui peut se produire si :

• Une chaîne de caractères clé des options accept de n'importe quel élément des options types ne peut pas analyser un type MIME valide.
• Une ou plusieurs chaînes de caractères valeur des options accept de n'importe quel élément des options types sont invalides, par exemple si elles ne commencent pas par . et ne se terminent pas par ., ou si elles contiennent des points de code invalides et que leur longueur est supérieure à 16.
• Les options types sont vides et les options excludeAcceptAllOption sont true.

Sécurité

Activation utilisateur transitoire est requise. L'utilisateur·ice doit interagir avec la page ou un élément de l'interface utilisateur pour que cette fonctionnalité fonctionne.

Exemples

Ici, nous définissons l'objet d'options à passer à la méthode. Nous autorisons la sélection de types de fichiers image, sans option pour autoriser tous les types de fichiers, ni sélection multiple de fichiers.

const listeOptions = {
  types: [
    {
      description: "Images",
      accept: {
        "image/*": [".png", ".gif", ".jpeg", ".jpg"],
      },
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false,
};

Ensuite, nous pouvons créer une fonction asynchrone qui affiche la boîte de dialogue de sélection de fichiers et retourne le fichier sélectionné.

// crée une référence pour notre gestionFichier
let gestionFichier;

async function obtenirFichier() {
  // ouvre la boîte de dialogue de sélection de fichiers, déstructure le tableau à un élément retourné
  [gestionFichier] = await window.showOpenFilePicker(listeOptions);

  // exécute le code avec notre gestionFichier
}

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'API File System
• L'API File System Access : simplification de l'accès aux fichiers locaux ^(angl.)