Window : méthode btoa()

Syntaxe

btoa(stringToEncode)

Paramètres

stringToEncode

La chaîne de caractères binaire à encoder. Les chaînes de caractères en JavaScript sont encodées en UTF-16, ce qui signifie que chaque caractère doit avoir un point de code inférieur à 256, représentant un octet de données.

Valeur de retour

Une chaîne de caractères ASCII contenant la représentation Base64 de stringToEncode.

Exceptions

InvalidCharacterError DOMException

La chaîne de caractères contenait un caractère qui ne tenait pas dans un seul octet. Voir la section « Chaîne de caractères Unicode » ci-dessous pour plus de détails.

Exemples

const donneesEncodees = window.btoa("Salut, le monde"); // encode une chaîne de caractères
const donneesDecodees = window.atob(donneesEncodees); // décode la chaîne de caractères

Chaînes de caractères Unicode

Base64, par conception, attend des données binaires comme entrée. En termes de chaînes de caractères JavaScript, cela signifie des chaînes dans lesquelles le point de code de chaque caractère occupe un seul octet. Donc, si vous passez une chaîne de caractères à btoa() contenant des caractères qui occupent plus d'un octet, vous obtiendrez une erreur, car cela n'est pas considéré comme des données binaires :

const ok = "a";
console.log(ok.codePointAt(0).toString(16)); //   61: occupe < 1 octet

const notOK = "✓";
console.log(notOK.codePointAt(0).toString(16)); // 2713: occupe > 1 octet

console.log(window.btoa(ok)); // YQ==
console.log(window.btoa(notOK)); // erreur

Comme btoa interprète les points de code de sa chaîne de caractères d'entrée comme des valeurs d'octet, appeler btoa sur une chaîne de caractères provoquera une exception « Caractère hors plage » si le point de code d'un caractère dépasse 0xff. Pour les cas où vous devez encoder du texte Unicode arbitraire, il est nécessaire de convertir d'abord la chaîne de caractères en ses octets constitutifs en UTF-8, puis d'encoder les octets.

La solution la plus simple consiste à utiliser TextEncoder et TextDecoder pour convertir entre UTF-8 et les représentations sur un seul octet de la chaîne de caractères :

function base64ToBytes(base64) {
  const binString = atob(base64);
  return Uint8Array.from(binString, (m) => m.codePointAt(0));
}

function bytesToBase64(bytes) {
  const binString = Array.from(bytes, (byte) =>
    String.fromCodePoint(byte),
  ).join("");
  return btoa(binString);
}

// Utilisation
bytesToBase64(new TextEncoder().encode("a Ā 𐀀 文 🦄")); // "YSDEgCDwkICAIOaWhyDwn6aE"
new TextDecoder().decode(base64ToBytes("YSDEgCDwkICAIOaWhyDwn6aE")); // "a Ā 𐀀 文 🦄"

Convertir des données binaires arbitraires

Les fonctions bytesToBase64 et base64ToBytes de la section précédente peuvent être utilisées directement pour convertir entre des chaînes de caractères Base64 et Uint8Array.

Pour de meilleures performances, la conversion asynchrone entre des URL de données base64 est possible nativement sur la plateforme web via les API FileReader et fetch :

async function bytesToBase64DataUrl(bytes, type = "application/octet-stream") {
  return await new Promise((resolve, reject) => {
    const reader = Object.assign(new FileReader(), {
      onload: () => resolve(reader.result),
      onerror: () => reject(reader.error),
    });
    reader.readAsDataURL(new File([bytes], "", { type }));
  });
}

async function dataUrlToBytes(dataUrl) {
  const res = await fetch(dataUrl);
  return new Uint8Array(await res.arrayBuffer());
}

// Utilisation
await bytesToBase64DataUrl(new Uint8Array([0, 1, 2])); // "data:application/octet-stream;base64,AAEC"
await dataUrlToBytes("data:application/octet-stream;base64,AAEC"); // Uint8Array [0, 1, 2]

Spécifications

Compatibilité des navigateurs

Voir aussi

• Une prothèse d'émulation pour btoa ^(angl.) est disponible dans core-js ^(angl.)
• Les url data
• WorkerGlobalScope.btoa() : la même méthode, mais dans les contextes de worker.
• La méthode Window.atob()
• La méthode Uint8Array.prototype.toBase64()
• L'entrée de glossaire Base64