diff options
Diffstat (limited to 'files/zh-tw/web/api/formdata')
| -rw-r--r-- | files/zh-tw/web/api/formdata/get/index.html | 145 | ||||
| -rw-r--r-- | files/zh-tw/web/api/formdata/index.html | 218 | ||||
| -rw-r--r-- | files/zh-tw/web/api/formdata/using_formdata_objects/index.html | 137 |
3 files changed, 500 insertions, 0 deletions
diff --git a/files/zh-tw/web/api/formdata/get/index.html b/files/zh-tw/web/api/formdata/get/index.html new file mode 100644 index 0000000000..b234ecb551 --- /dev/null +++ b/files/zh-tw/web/api/formdata/get/index.html @@ -0,0 +1,145 @@ +--- +title: FormData.get() +slug: Web/API/FormData/get +translation_of: Web/API/FormData/get +--- +<p>{{APIRef("XMLHttpRequest")}}</p> + +<p>{{domxref("FormData")}} 的 <code><strong>get() </strong></code>方法會返回 <code>FormData 物件中，</code>指定 key 值所對應之第一組物件中的 value 值 。然而，如果您想要獲得多組以及全部的 value ，那應該使用 {{domxref("FormData.getAll()","getAll()")}} 方法。</p> + +<p><strong>注意</strong>: 這個方法已可以在 <a href="/en-US/docs/Web/API/Web_Workers_API">Web Workers</a> 中使用。</p> + +<h2 id="語法">語法</h2> + +<pre>formData.get(name);</pre> + +<h3 id="append()_Parameters" name="append()_Parameters">參數</h3> + +<dl> + <dt><code>name</code></dt> + <dd>一個 {{domxref("USVString")}} ，代表您想要得到的 value 所對應的 key 值名稱。</dd> +</dl> + +<h3 id="回傳值">回傳值</h3> + +<p>A {{domxref("FormDataEntryValue")}} containing the value.</p> + +<h2 id="範例">範例</h2> + +<p>下面一行程式會產生一個空的 <code>FormData 物件：</code></p> + +<pre>var formData = new FormData();</pre> + +<p>用 {{domxref("FormData.append")}} 方法新增兩組 <code>username 值</code></p> + +<pre>formData.append('username', 'Chris'); +formData.append('username', 'Bob');</pre> + +<p>接下來使用 <code>get() 方法，將只會返回上一步驟，第一組新增的 username 所對應的值</code></p> + +<pre>formData.get('username'); // Returns "Chris"</pre> + +<h2 id="規範">規範</h2> + +<table> + <tbody> + <tr> + <th scope="col">規範</th> + <th scope="col">狀態</th> + <th scope="col">註解</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest','#dom-formdata-get','get()')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatGeckoDesktop('39.0')}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Available in web workers</td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatGeckoDesktop('39.0')}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Android Webview</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td> + <p>{{CompatVersionUnknown}}</p> + </td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(50.0)}}</td> + </tr> + <tr> + <td>Available in web workers</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(50.0)}}</td> + </tr> + </tbody> +</table> +</div> + +<h2 id="sect1"> </h2> + +<h2 id="延伸閱讀">延伸閱讀</h2> + +<ul> + <li>{{domxref("XMLHTTPRequest")}}</li> + <li><a href="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="Using XMLHttpRequest">Using XMLHttpRequest</a></li> + <li><a href="/en-US/docs/DOM/XMLHttpRequest/FormData/Using_FormData_Objects" title="DOM/XMLHttpRequest/FormData/Using_FormData_objects">Using FormData objects</a></li> + <li>{{HTMLElement("Form")}}</li> +</ul> diff --git a/files/zh-tw/web/api/formdata/index.html b/files/zh-tw/web/api/formdata/index.html new file mode 100644 index 0000000000..4151641a6e --- /dev/null +++ b/files/zh-tw/web/api/formdata/index.html @@ -0,0 +1,218 @@ +--- +title: FormData +slug: Web/API/FormData +translation_of: Web/API/FormData +--- +<p>{{APIRef("XMLHttpRequest")}}</p> + +<p><strong><code>FormData</code></strong> 介面可為表單資料中的欄位/值建立相對應的的鍵/值對（key/value）集合，之後便可使用 {{domxref("XMLHttpRequest.send()")}} 方法來送出資料。它在編碼類型設定為 <code>multipart/form-data</code> 時會採用與表單相同的格式送出。</p> + +<p>實作 <code>FormData</code> 的物件可以直接利用 {{jsxref("Statements/for...of", "for...of")}} 語法結構來替代 {{domxref('FormData.entries()', 'entries()')}}：<code>for (var p of myFormData)</code> 等同於 <code>for (var p of myFormData.entries())</code>。</p> + +<div class="note"> +<p><strong>備註：</strong>此特性適用於 <a href="/zh-TW/docs/Web/API/Web_Workers_API">Web Workers</a>。</p> +</div> + +<h2 id="建構式">建構式</h2> + +<dl> + <dt>{{domxref("FormData.FormData","FormData()")}}</dt> + <dd>建立一個新的 <code>FormData</code> 物件。</dd> +</dl> + +<h2 id="方法">方法</h2> + +<dl> + <dt>{{domxref("FormData.append()")}}</dt> + <dd>追加新值到 <code>FormData</code> 物件已有的對應鍵上；若該鍵不存在，則為其追加新的鍵。</dd> + <dt>{{domxref("FormData.delete()")}}</dt> + <dd>刪除指定的鍵值對。</dd> + <dt>{{domxref("FormData.entries()")}}</dt> + <dd>回傳 {{jsxref("Iteration_protocols","iterator")}}，可用來處理物件中所有的鍵值對。</dd> + <dt>{{domxref("FormData.get()")}}</dt> + <dd>回傳指定的鍵在 <code>FormData</code> 物件中找到的第一個對應值。</dd> + <dt>{{domxref("FormData.getAll()")}}</dt> + <dd>回傳指定的鍵在 <code>FormData</code> 物件中所有對應值的陣列。</dd> + <dt>{{domxref("FormData.has()")}}</dt> + <dd>回傳 <code>FormData</code> 物件是否含有指定鍵值對的布林值。</dd> + <dt>{{domxref("FormData.keys()")}}</dt> + <dd>回傳 {{jsxref("Iteration_protocols", "iterator")}}，可用來處理物件中所有鍵值對之中的鍵。</dd> + <dt>{{domxref("FormData.set()")}}</dt> + <dd>為 <code>FormData</code> 物件已有的鍵設定新值；若該鍵不存在，則為其追加新的鍵。</dd> + <dt>{{domxref("FormData.values()")}}</dt> + <dd>回傳 {{jsxref("Iteration_protocols", "iterator")}}，可用來處理物件中所有鍵值對之中的值。</dd> +</dl> + +<h2 id="規範">規範</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('XMLHttpRequest','#interface-formdata','FormData')}}</td> + <td>{{Spec2('XMLHttpRequest')}}</td> + <td>FormData defined in XHR spec</td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<div>{{CompatibilityTable}}</div> + +<div id="compat-desktop"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Chrome</th> + <th>Edge</th> + <th>Firefox (Gecko)</th> + <th>Internet Explorer</th> + <th>Opera</th> + <th>Safari</th> + </tr> + <tr> + <td>Basic support</td> + <td>{{CompatChrome(7.0)}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("2.0")}}<sup>[1]</sup></td> + <td>10</td> + <td>12</td> + <td>5</td> + </tr> + <tr> + <td>append with filename</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("22.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>delete()</code>, <code>get()</code>, <code>getAll()</code>, <code>has()</code>, <code>set()</code></td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("39.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td><code>entries()</code>, <code>keys()</code>, <code>values()</code>, and support of <code>for...of</code></td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoDesktop("44.0")}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + <tr> + <td>Available in web workers</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoDesktop("39.0")}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + </tr> + </tbody> +</table> +</div> + +<div id="compat-mobile"> +<table class="compat-table"> + <tbody> + <tr> + <th>Feature</th> + <th>Android</th> + <th>Android Webview</th> + <th>Edge</th> + <th>Firefox Mobile (Gecko)</th> + <th>Firefox OS (Gecko)</th> + <th>IE Mobile</th> + <th>Opera Mobile</th> + <th>Safari Mobile</th> + <th>Chrome for Android</th> + </tr> + <tr> + <td>Basic support</td> + <td>3.0<sup>[2]</sup></td> + <td>{{CompatVersionUnknown}}<sup>[2]</sup></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatGeckoMobile("2.0")}}<sup>[1]</sup></td> + <td>1.0.1</td> + <td>{{CompatUnknown}}</td> + <td>12</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td>append with filename</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("22.0")}}</td> + <td>1.2</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + <tr> + <td><code>delete()</code>, <code>get()</code>, <code>getAll()</code>, <code>has()</code>, <code>set()</code></td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatChrome(50.0)}}</td> + </tr> + <tr> + <td><code>entries()</code>, <code>keys()</code>, <code>values()</code>, and support of <code>for...of</code></td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(50.0)}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatGeckoMobile("44.0")}}</td> + <td>2.5</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatUnknown}}</td> + <td>{{CompatChrome(50.0)}}</td> + </tr> + <tr> + <td>Available in web workers</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + <td>{{CompatNo}}</td> + <td>{{CompatVersionUnknown}}</td> + </tr> + </tbody> +</table> +</div> + +<p>[1] 在 Gecko 7.0 {{geckoRelease("7.0")}} 之前，若把 {{domxref("Blob")}} 設定為物件中的值，則 HTTP 標頭中 "Content-Disposition" 的檔案名稱會是空字串，此行為會被某些伺服器視為錯誤。Gecko 7.0 之後則會將檔名設為 "blob" 送出。</p> + +<p>[2] XHR in Android 4.0 sends empty content for <code>FormData</code> with <code>blob</code>.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li>{{domxref("XMLHTTPRequest")}}</li> + <li><a href="/zh-TW/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">使用 XMLHttpRequest</a></li> + <li><a href="/zh-TW/docs/Web/API/FormData/Using_FormData_Objects">使用 FormData 物件</a></li> + <li>{{HTMLElement("Form")}}</li> +</ul> diff --git a/files/zh-tw/web/api/formdata/using_formdata_objects/index.html b/files/zh-tw/web/api/formdata/using_formdata_objects/index.html new file mode 100644 index 0000000000..e01b15eb90 --- /dev/null +++ b/files/zh-tw/web/api/formdata/using_formdata_objects/index.html @@ -0,0 +1,137 @@ +--- +title: Using FormData Objects +slug: Web/API/FormData/Using_FormData_Objects +translation_of: Web/API/FormData/Using_FormData_Objects +--- +<p class="summary">The <code><a href="/en-US/docs/Web/API/FormData">FormData</a></code> object lets you compile a set of key/value pairs to send using <code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code>. It is primarily intended for use in sending form data, but can be used independently from forms in order to transmit keyed data. The transmitted data is in the same format that the form's {{domxref("HTMLFormElement.submit","submit()")}} method would use to send the data if the form's encoding type were set to <code>multipart/form-data</code>.</p> + +<h2 id="Creating_a_FormData_object_from_scratch">Creating a FormData object from scratch</h2> + +<p>You can build a <code>FormData</code> object yourself, instantiating it then appending fields to it by calling its {{domxref("FormData.append","append()")}} method, like this:</p> + +<pre class="brush: js">var formData = new FormData(); + +formData.append("username", "Groucho"); +formData.append("accountnum", 123456); // number 123456 is immediately converted to a string "123456" + +// HTML file input, chosen by user +formData.append("userfile", fileInputElement.files[0]); + +// JavaScript file-like object +var content = '<a id="a"><b id="b">hey!</b></a>'; // the body of the new file... +var blob = new Blob([content], { type: "text/xml"}); + +formData.append("webmasterfile", blob); + +var request = new XMLHttpRequest(); +request.open("POST", "http://foo.com/submitform.php"); +request.send(formData); +</pre> + +<div class="note"><strong>Note:</strong> The fields "userfile" and "webmasterfile" both contain a file. The number assigned to the field "accountnum" is immediately converted into a string by the <a href="/en/DOM/XMLHttpRequest/FormData#append()" title="en/XMLHttpRequest/FormData#append()"><code>FormData.append()</code></a> method (the field's value can be a {{ domxref("Blob") }}, {{ domxref("File") }}, or a string: <strong>if the value is neither a Blob nor a File, the value is converted to a string</strong>).</div> + +<p>This example builds a <code>FormData</code> instance containing values for fields named "username", "accountnum", "userfile" and "webmasterfile", then uses the <code>XMLHttpRequest</code> method <a href="/en/DOM/XMLHttpRequest#send()" title="en/XMLHttpRequest#send()"><code>send()</code></a> to send the form's data. The field "webmasterfile" is a {{domxref("Blob")}}. A <code>Blob</code> object represents a file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The {{ domxref("File") }} interface is based on <code>Blob</code>, inheriting blob functionality and expanding it to support files on the user's system. In order to build a <code>Blob</code> you can invoke the {{domxref("Blob.Blob","Blob() constructor")}}.</p> + +<h2 id="Retrieving_a_FormData_object_from_an_HTML_form">Retrieving a FormData object from an HTML form</h2> + +<p>To construct a <code>FormData</code> object that contains the data from an existing {{ HTMLElement("form") }}, specify that form element when creating the <code>FormData</code> object:</p> + +<pre class="brush: js">var formData = new FormData(someFormElement); +</pre> + +<p>For example:</p> + +<pre class="brush: js">var formElement = document.querySelector("form"); +var request = new XMLHttpRequest(); +request.open("POST", "submitform.php"); +request.send(new FormData(formElement)); +</pre> + +<p>You can also append additional data to the <code>FormData</code> object between retrieving it from a form and sending it, like this:</p> + +<pre class="brush: js">var formElement = document.querySelector("form"); +var formData = new FormData(formElement); +var request = new XMLHttpRequest(); +request.open("POST", "submitform.php"); +formData.append("serialnumber", serialNumber++); +request.send(formData);</pre> + +<p>This lets you augment the form's data before sending it along, to include additional information that's not necessarily user-editable.</p> + +<h2 id="使用_FormData_物件傳送檔案">使用 FormData 物件傳送檔案</h2> + +<p>You can also send files using <code>FormData</code>. Simply include an {{ HTMLElement("input") }} element of type <code>file</code> in your {{htmlelement("form")}}:</p> + +<pre class="brush: html"><form enctype="multipart/form-data" method="post" name="fileinfo"> + <label>Your email address:</label> + <input type="email" autocomplete="on" autofocus name="userid" placeholder="email" required size="32" maxlength="64" /><br /> + <label>Custom file label:</label> + <input type="text" name="filelabel" size="12" maxlength="32" /><br /> + <label>File to stash:</label> + <input type="file" name="file" required /> + <input type="submit" value="Stash the file!" /> +</form> +<div></div> +</pre> + +<p>Then you can send it using code like the following:</p> + +<pre class="brush: js">var form = document.forms.namedItem("fileinfo"); +form.addEventListener('submit', function(ev) { + + var oOutput = document.querySelector("div"), + oData = new FormData(form); + + oData.append("CustomField", "This is some extra data"); + + var oReq = new XMLHttpRequest(); + oReq.open("POST", "stash.php", true); + oReq.onload = function(oEvent) { + if (oReq.status == 200) { + oOutput.innerHTML = "Uploaded!"; + } else { + oOutput.innerHTML = "Error " + oReq.status + " occurred when trying to upload your file.<br \/>"; + } + }; + + oReq.send(oData); + ev.preventDefault(); +}, false); +</pre> + +<div class="note"> +<p><strong>Note</strong>: If you pass in a reference to the form the method specified in the form will be used over the method specified in the open() call.</p> +</div> + +<p>You can also append a {{ domxref("File") }} or {{ domxref("Blob") }} directly to the {{ domxref("FormData") }} object, like this:</p> + +<pre class="brush: js">data.append("myfile", myBlob, "filename.txt"); +</pre> + +<p>When using the {{domxref("FormData.append","append()")}} method it is possible to use the third optional parameter to pass a filename inside the <code>Content-Disposition</code> header that is sent to the server. When no filename is specified (or the parameter isn't supported), the name "blob" is used.</p> + +<p>You can also use <code>FormData</code> with jQuery if you set the right options:</p> + +<pre class="brush: js">var fd = new FormData(document.querySelector("form")); +fd.append("CustomField", "This is some extra data"); +$.ajax({ + url: "stash.php", + type: "POST", + data: fd, + processData: false, // tell jQuery not to process the data + contentType: false // tell jQuery not to set contentType +}); +</pre> + +<h2 id="Submitting_forms_and_uploading_files_via_AJAX_without_FormData_objects">Submitting forms and uploading files via AJAX <em>without</em> <code>FormData</code> objects</h2> + +<p>If you want to know how to serialize and submit a form via <a href="/en-US/docs/AJAX" title="/en-US/docs/AJAX">AJAX</a> <em>without</em> using FormData objects, please read <a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files" title="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files">this paragraph</a>.</p> + +<h2 id="參見">參見</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li> + <li>{{domxref("HTMLFormElement")}}</li> + <li>{{domxref("Blob")}}</li> + <li><a href="/en-US/docs/Web/JavaScript/Typed_arrays">Typed Arrays</a></li> +</ul> |