WindowOrWorkerGlobalScope.btoa()

WindowOrWorkerGlobalScope.btoa() メソッドは、 Base64 でエンコードされた ASCII 文字列をバイナリ文字列 (例えば String オブジェクトのうち、文字列中のすべての文字がバイナリデータのバイトとして扱うことができるもの) から生成します。

このメソッドを使用すると、通信に支障をきたす可能性のあるデータをエンコードして送信し、その後 atob() メソッドを使用して再度デコードすることができます。例えば ASCII で 0 から 31 の値ような制御文字をエンコードすることもできます。

構文

var encodedData = scope.btoa(stringToEncode);

引数

stringToEncode
エンコードするバイナリ文字列です。

返値

stringToEncode の Base64 表現である ASCII 文字列です。

例外

InvalidCharacterError
文字列には、1 バイトに収まらない文字が含まれていた場合。詳細は後述の「Unicode文字列」を参照してください。

const encodedData = window.btoa('Hello, world'); // 文字列をエンコード
const decodedData = window.atob(encodedData); // 文字列をデコード

Unicode 文字列

btoa() 関数は、JavaScript の文字列を引数にとります。JavaScript の文字列は UTF-16 文字エンコーディングで表現されます。このエンコーディングでは、文字列は 16 ビット (2 バイト) 単位の並びとして表現されます。すべての ASCII 文字はこれらの単位の 1 バイト目に収まりますが、他の多くの文字は収まりません。

Base64 は、設計上、バイナリデータを入力として期待します。 JavaScript の文字列では、これは各文字が 1 バイトしか占有しない文字列を意味します。したがって、2 バイト以上の文字を含む文字列を btoa() に渡した場合、これはバイナリデータとはみなされないため、エラーが発生します。

const ok = "a";
console.log(ok.codePointAt(0).toString(16)); //   61: 長さ < 1 バイト

const notOK = "✓"
console.log(notOK.codePointAt(0).toString(16)); // 2713: 長さ > 1 バイト

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

btoa() を用いて Unicode テキストを ASCII としてエンコードする必要がある場合、一つの選択肢として、各 16 ビット単位が 1 バイトしか占有しないように文字列を変換することができます。例えば、以下のようになります。

// Unicode 文字列で、各 16 ビット単位を 1 バイトしか占有
// しない文字列に変換します。
function toBinary(string) {
  const codeUnits = new Uint16Array(string.length);
  for (let i = 0; i < codeUnits.length; i++) {
    codeUnits[i] = string.charCodeAt(i);
  }
  return String.fromCharCode(...new Uint8Array(codeUnits.buffer));
}

// 1 バイトを超える文字を含んだ文字列
const myString = "☸☹☺☻☼☾☿";

const converted = toBinary(myString);
const encoded = btoa(converted);
console.log(encoded);                 // OCY5JjomOyY8Jj4mPyY=

このようにした場合、当然ながらデコードされた文字列を逆変換する必要があります。

function fromBinary(binary) {
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < bytes.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return String.fromCharCode(...new Uint16Array(bytes.buffer));
}

const decoded = atob(encoded);
const original = fromBinary(decoded);
console.log(original);                // ☸☹☺☻☼☾☿

ポリフィル

対応していないブラウザーでは、 https://github.com/MaxArt2501/base64-js/blob/master/base64.js のポリフィルを利用することができます。

仕様書

仕様書 状態 備考
HTML Living Standard
WindowOrWorkerGlobalScope.btoa() の定義
現行の標準 最新の仕様で、メソッドを WindowOrWorkerGlobalScope ミックスインに移動。
HTML 5.1
WindowBase64.btoa() の定義
勧告 HTML Living Standard のスナップショット、変更なし。
HTML5
WindowBase64.btoa() の定義
勧告 HTML Living Standard のスナップショット。 WindowBase64 の作成 (properties where on the target before it).

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
btoaChrome 完全対応 4Edge 完全対応 12Firefox 完全対応 1
完全対応 1
完全対応 52
補足
補足 btoa() now defined on WindowOrWorkerGlobalScope mixin.
IE 完全対応 10Opera 完全対応 10.5Safari 完全対応 3WebView Android 完全対応 ≤37Chrome Android 完全対応 18Firefox Android 完全対応 4
完全対応 4
完全対応 52
補足
補足 atob() now defined on WindowOrWorkerGlobalScope mixin.
Opera Android 完全対応 11Safari iOS 完全対応 1Samsung Internet Android 完全対応 1.0

凡例

完全対応  
完全対応
実装ノートを参照してください。
実装ノートを参照してください。

関連情報