HTMLCanvasElement : méthode toBlob()

Syntaxe

toBlob(callback)
toBlob(callback, type)
toBlob(callback, type, quality)

Paramètres

callback

Une fonction de rappel recevant l'objet Blob résultant en argument unique. null peut être passé si l'image ne peut pas être créée pour une raison quelconque.

type Facultatif

Une chaîne de caractères indiquant le format de l'image. Le type par défaut est image/png ; ce type est également utilisé si le type fourni n'est pas pris en charge.

quality Facultatif

Un nombre (Number) compris entre 0 et 1 indiquant la qualité de l'image à utiliser lors de la création d'images avec des formats prenant en charge la compression destructive (par exemple image/jpeg ou image/webp). L'agent utilisateur utilise sa valeur de qualité par défaut si cette option n'est pas précisée, ou si le nombre est en dehors de la plage autorisée.

Valeur de retour

Aucune (undefined).

Exceptions

SecurityError

Le bitmap du canevas n'est pas d'origine sûre ; au moins une partie de son contenu a été ou pourrait avoir été chargée depuis un site différent de celui d'où provient le document.

Exemples

Obtenir un fichier représentant le canevas

Une fois que vous avez dessiné du contenu dans un canevas, vous pouvez le convertir en un fichier dans n'importe quel format d'image pris en charge. Le fragment de code ci‑dessous, par exemple, récupère l'image contenue dans l'élément HTML <canvas> dont l'ID est « canvas », obtient une copie en tant qu'image PNG, puis ajoute un nouvel élément <img> au document, dont la source est l'image créée à partir du canevas.

const canvas = document.getElementById("canvas");

canvas.toBlob((blob) => {
  const newImg = document.createElement("img");
  const url = URL.createObjectURL(blob);

  newImg.src = url;
  document.body.appendChild(newImg);
});

Ici nous créons une image PNG ; si vous ajoutez un second paramètre à l'appel toBlob(), vous pouvez préciser un autre type d'image pris en charge par l'agent utilisateur. Par exemple, pour obtenir l'image au format JPEG :

canvas.toBlob(
  (blob) => {
    /* … */
  },
  "image/jpeg",
  0.95,
); // JPEG à 95% de qualité

Remarquez que nous ne révoquons pas immédiatement l'URL d'objet après le chargement de l'image, car cela rendrait l'image inutilisable pour les interactions utilisateur (comme le clic droit pour enregistrer l'image ou l'ouverture dans un nouvel onglet). Pour les applications de longue durée, vous devez révoquer les URL d'objet lorsqu'elles ne sont plus nécessaires (par exemple lorsque l'image est retirée du DOM) afin de libérer de la mémoire en appelant la méthode URL.revokeObjectURL() et en lui passant la chaîne de caractères de l'URL d'objet.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'interface Blob