diff options
Diffstat (limited to 'files/zh-tw/web/api/btoa/index.html')
| -rw-r--r-- | files/zh-tw/web/api/btoa/index.html | 137 |
1 files changed, 137 insertions, 0 deletions
diff --git a/files/zh-tw/web/api/btoa/index.html b/files/zh-tw/web/api/btoa/index.html new file mode 100644 index 0000000000..9f846d885d --- /dev/null +++ b/files/zh-tw/web/api/btoa/index.html @@ -0,0 +1,137 @@ +--- +title: WindowOrWorkerGlobalScope.btoa() +slug: Web/API/btoa +translation_of: Web/API/WindowOrWorkerGlobalScope/btoa +original_slug: Web/API/WindowOrWorkerGlobalScope/btoa +--- +<p>{{APIRef("HTML DOM")}}</p> + +<p>The <code><strong>WindowOrWorkerGlobalScope.btoa()</strong></code> method creates a {{glossary("Base64")}}-encoded ASCII string from a <a href="/en-US/docs/Web/API/DOMString/Binary">binary string</a> (i.e., a {{jsxref("String")}} object in which each character in the string is treated as a byte of binary data).</p> + +<p>You can use this method to encode data which may otherwise cause communication problems, transmit it, then use the {{domxref("WindowOrWorkerGlobalScope.atob", "atob()")}} method to decode the data again. For example, you can encode control characters such as ASCII values 0 through 31.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox notranslate">var <var>encodedData</var> = <var>scope</var>.btoa(<var>stringToEncode</var>);</pre> + +<h3 id="Parameters">Parameters</h3> + +<dl> + <dt><code><var>stringToEncode</var></code></dt> + <dd>The <a href="/en-US/docs/Web/API/DOMString/Binary">binary string</a> to encode.</dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>An ASCII string containing the Base64 representation of <code><var>stringToEncode</var></code>.</p> + +<h3 id="Exceptions">Exceptions</h3> + +<dl> + <dt><code>InvalidCharacterError</code></dt> + <dd>The string contained a character that did not fit in a single byte. See "Unicode strings" below for more detail.</dd> +</dl> + +<h2 id="Example">Example</h2> + +<pre class="brush:js notranslate">const encodedData = window.btoa('Hello, world'); // encode a string +const decodedData = window.atob(encodedData); // decode the string +</pre> + +<h2 id="Unicode_strings">Unicode strings</h2> + +<p>The <code>btoa()</code> function takes a JavaScript string as a parameter. In JavaScript strings are represented using the UTF-16 character encoding: in this encoding, strings are represented as a sequence of 16-bit (2 byte) units. Every ASCII character fits into the first byte of one of these units, but many other characters don't.</p> + +<p>Base64, by design, expects binary data as its input. In terms of JavaScript strings, this means strings in which each character occupies only one byte. So if you pass a string into <code>btoa()</code> containing characters that occupy more than one byte, you will get an error, because this is not considered binary data:</p> + +<pre class="brush: js notranslate">const ok = "a"; +console.log(ok.codePointAt(0).toString(16)); // 61: occupies < 1 byte + +const notOK = "✓" +console.log(notOK.codePointAt(0).toString(16)); // 2713: occupies > 1 byte + +console.log(btoa(ok)); // YQ== +console.log(btoa(notOK)); // error</pre> + +<p>If you need to encode Unicode text as ASCII using <code>btoa()</code>, one option is to convert the string such that each 16-bit unit occupies only one byte. For example:</p> + +<pre class="brush: js notranslate">// convert a Unicode string to a string in which +// each 16-bit unit occupies only one byte +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)); +} + +// a string that contains characters occupying > 1 byte +const myString = "☸☹☺☻☼☾☿"; + +const converted = toBinary(myString); +const encoded = btoa(converted); +console.log(encoded); // OCY5JjomOyY8Jj4mPyY= +</pre> + +<p>If you do this, of course you'll have to reverse the conversion on the decoded string:</p> + +<pre class="brush: js language-js notranslate">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); // ☸☹☺☻☼☾☿ +</pre> + +<h2 id="Polyfill">Polyfill</h2> + +<p>You can use a polyfill from <a href="https://github.com/MaxArt2501/base64-js/blob/master/base64.js">https://github.com/MaxArt2501/base64-js/blob/master/base64.js</a> for browsers that don't support it.</p> + +<h2 id="Specifications">Specifications</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('HTML WHATWG', '#dom-btoa', 'WindowOrWorkerGlobalScope.btoa()')}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td>Method moved to the <code>WindowOrWorkerGlobalScope</code> mixin in the latest spec.</td> + </tr> + <tr> + <td>{{SpecName('HTML5.1', '#dom-windowbase64-btoa', 'WindowBase64.btoa()')}}</td> + <td>{{Spec2('HTML5.1')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. No change.</td> + </tr> + <tr> + <td>{{SpecName("HTML5 W3C", "#dom-windowbase64-btoa", "WindowBase64.btoa()")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>Snapshot of {{SpecName("HTML WHATWG")}}. Creation of <code>WindowBase64</code> (properties where on the target before it).</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<div> + + +<p>{{Compat("api.WindowOrWorkerGlobalScope.btoa")}}</p> +</div> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs"><code>data</code> URIs</a></li> + <li>{{domxref("WindowOrWorkerGlobalScope.atob","atob()")}}</li> +</ul> |